<?xml version="1.0" encoding="UTF-8"?><?xml-stylesheet type="text/css" href="/rss-style.css"?><rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>Personal Blog</title><description>记录技术、生活与创作</description><link>https://www.anexns.cloudns.org/</link><language>zh_CN</language><item><title>Nginx 缓存：proxy_cache 代理缓存与浏览器缓存的双层账</title><link>https://www.anexns.cloudns.org/posts/webserver-nginx-cache/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/webserver-nginx-cache/</guid><description>把 Nginx 的两层缓存一次算清：proxy_cache 的目录、key 与有效期，命中状态与防击穿，浏览器缓存的 expires 与版本化策略，以及缓存清理的现实办法。</description><pubDate>Wed, 18 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;同一个请求，Nginx 其实有两次机会不去打扰后端：第一次是浏览器自己手里有缓存，连 Nginx 都不问；第二次是 Nginx 手里有缓存，问一句就直接回。两层缓存各管一段路，规则也各不相同——浏览器缓存由响应头说了算，代理缓存由 Nginx 的 &lt;code&gt;proxy_cache&lt;/code&gt; 指令说了算。把这两本账分开记，缓存才不会变成「有时候快、有时候串数据」的玄学。这篇先把双层结构画出来，再逐条讲 &lt;code&gt;proxy_cache_path&lt;/code&gt;、&lt;code&gt;proxy_cache_key&lt;/code&gt;、&lt;code&gt;proxy_cache_valid&lt;/code&gt; 三个核心指令，随后讲命中状态、防击穿、浏览器缓存与清理办法。反向代理的基础写法在第 2 篇&lt;a href=&quot;/posts/webserver-nginx-reverse-proxy/&quot;&gt;《Nginx 反向代理深挖：proxy_pass 的斜杠、头传递与缓冲取舍》&lt;/a&gt;里已经讲过，这篇默认你已经会配 &lt;code&gt;proxy_pass&lt;/code&gt; 与 &lt;code&gt;upstream&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;双层缓存长什么样&lt;/h2&gt;
&lt;p&gt;请求从浏览器出发，到拿到响应为止，会经过两道缓存关卡。第一道在浏览器：资源带了 &lt;code&gt;Cache-Control: max-age=...&lt;/code&gt; 或 &lt;code&gt;Expires&lt;/code&gt;，且没过期，浏览器直接用本地副本，连请求都不发。第二道在 Nginx：请求到了 Nginx，&lt;code&gt;proxy_cache&lt;/code&gt; 先按 key 查磁盘缓存，命中且未过期就直接返回，不再回源；没命中或已过期才去找上游，拿到响应后按规则写一份进缓存再返回。&lt;/p&gt;
&lt;p&gt;&amp;lt;svg xmlns=&quot;http://www.w3.org/2000/svg&quot; viewBox=&quot;0 0 800 340&quot; fill=&quot;none&quot; style=&quot;width:100%;height:auto&quot; role=&quot;img&quot; aria-label=&quot;双层缓存结构与命中路径图&quot;&amp;gt;
&amp;lt;rect x=&quot;20&quot; y=&quot;130&quot; width=&quot;130&quot; height=&quot;80&quot; rx=&quot;10&quot; stroke=&quot;#38bdf8&quot; stroke-width=&quot;2&quot;/&amp;gt;
&amp;lt;text x=&quot;85&quot; y=&quot;165&quot; fill=&quot;#e2e8f0&quot; font-size=&quot;16&quot; text-anchor=&quot;middle&quot;&amp;gt;浏览器&amp;lt;/text&amp;gt;
&amp;lt;text x=&quot;85&quot; y=&quot;190&quot; fill=&quot;#94a3b8&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;第一道缓存&amp;lt;/text&amp;gt;
&amp;lt;rect x=&quot;300&quot; y=&quot;60&quot; width=&quot;200&quot; height=&quot;220&quot; rx=&quot;10&quot; stroke=&quot;#a78bfa&quot; stroke-width=&quot;2&quot;/&amp;gt;
&amp;lt;text x=&quot;400&quot; y=&quot;88&quot; fill=&quot;#e2e8f0&quot; font-size=&quot;16&quot; text-anchor=&quot;middle&quot;&amp;gt;Nginx&amp;lt;/text&amp;gt;
&amp;lt;text x=&quot;400&quot; y=&quot;112&quot; fill=&quot;#94a3b8&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;proxy_cache（第二道缓存）&amp;lt;/text&amp;gt;
&amp;lt;rect x=&quot;330&quot; y=&quot;140&quot; width=&quot;140&quot; height=&quot;46&quot; rx=&quot;8&quot; stroke=&quot;#34d399&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;text x=&quot;400&quot; y=&quot;168&quot; fill=&quot;#e2e8f0&quot; font-size=&quot;14&quot; text-anchor=&quot;middle&quot;&amp;gt;缓存区 keys_zone&amp;lt;/text&amp;gt;
&amp;lt;rect x=&quot;330&quot; y=&quot;205&quot; width=&quot;140&quot; height=&quot;46&quot; rx=&quot;8&quot; stroke=&quot;#34d399&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;text x=&quot;400&quot; y=&quot;233&quot; fill=&quot;#e2e8f0&quot; font-size=&quot;14&quot; text-anchor=&quot;middle&quot;&amp;gt;磁盘缓存目录&amp;lt;/text&amp;gt;
&amp;lt;rect x=&quot;650&quot; y=&quot;130&quot; width=&quot;130&quot; height=&quot;80&quot; rx=&quot;10&quot; stroke=&quot;#fbbf24&quot; stroke-width=&quot;2&quot;/&amp;gt;
&amp;lt;text x=&quot;715&quot; y=&quot;165&quot; fill=&quot;#e2e8f0&quot; font-size=&quot;16&quot; text-anchor=&quot;middle&quot;&amp;gt;上游应用&amp;lt;/text&amp;gt;
&amp;lt;text x=&quot;715&quot; y=&quot;190&quot; fill=&quot;#94a3b8&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;后端服务&amp;lt;/text&amp;gt;
&amp;lt;path d=&quot;M150 160 H 290&quot; stroke=&quot;#38bdf8&quot; stroke-width=&quot;2&quot; marker-end=&quot;url(#arr1)&quot;/&amp;gt;
&amp;lt;text x=&quot;220&quot; y=&quot;148&quot; fill=&quot;#38bdf8&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;请求&amp;lt;/text&amp;gt;
&amp;lt;path d=&quot;M290 185 H 150&quot; stroke=&quot;#64748b&quot; stroke-width=&quot;1.5&quot; stroke-dasharray=&quot;5 4&quot; marker-end=&quot;url(#arr2)&quot;/&amp;gt;
&amp;lt;text x=&quot;220&quot; y=&quot;205&quot; fill=&quot;#94a3b8&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;HIT 直接返回&amp;lt;/text&amp;gt;
&amp;lt;path d=&quot;M500 160 H 640&quot; stroke=&quot;#fbbf24&quot; stroke-width=&quot;2&quot; marker-end=&quot;url(#arr3)&quot;/&amp;gt;
&amp;lt;text x=&quot;570&quot; y=&quot;148&quot; fill=&quot;#fbbf24&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;MISS 回源&amp;lt;/text&amp;gt;
&amp;lt;path d=&quot;M640 185 H 500&quot; stroke=&quot;#64748b&quot; stroke-width=&quot;1.5&quot; stroke-dasharray=&quot;5 4&quot; marker-end=&quot;url(#arr4)&quot;/&amp;gt;
&amp;lt;text x=&quot;570&quot; y=&quot;205&quot; fill=&quot;#94a3b8&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;响应并写入缓存&amp;lt;/text&amp;gt;
&amp;lt;path d=&quot;M400 186 V 205&quot; stroke=&quot;#34d399&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;defs&amp;gt;
&amp;lt;marker id=&quot;arr1&quot; markerWidth=&quot;8&quot; markerHeight=&quot;8&quot; refX=&quot;6&quot; refY=&quot;3&quot; orient=&quot;auto&quot;&amp;gt;&amp;lt;path d=&quot;M0,0 L6,3 L0,6 z&quot; fill=&quot;#38bdf8&quot;/&amp;gt;&amp;lt;/marker&amp;gt;
&amp;lt;marker id=&quot;arr2&quot; markerWidth=&quot;8&quot; markerHeight=&quot;8&quot; refX=&quot;6&quot; refY=&quot;3&quot; orient=&quot;auto&quot;&amp;gt;&amp;lt;path d=&quot;M0,0 L6,3 L0,6 z&quot; fill=&quot;#64748b&quot;/&amp;gt;&amp;lt;/marker&amp;gt;
&amp;lt;marker id=&quot;arr3&quot; markerWidth=&quot;8&quot; markerHeight=&quot;8&quot; refX=&quot;6&quot; refY=&quot;3&quot; orient=&quot;auto&quot;&amp;gt;&amp;lt;path d=&quot;M0,0 L6,3 L0,6 z&quot; fill=&quot;#fbbf24&quot;/&amp;gt;&amp;lt;/marker&amp;gt;
&amp;lt;marker id=&quot;arr4&quot; markerWidth=&quot;8&quot; markerHeight=&quot;8&quot; refX=&quot;6&quot; refY=&quot;3&quot; orient=&quot;auto&quot;&amp;gt;&amp;lt;path d=&quot;M0,0 L6,3 L0,6 z&quot; fill=&quot;#64748b&quot;/&amp;gt;&amp;lt;/marker&amp;gt;
&amp;lt;/defs&amp;gt;
&amp;lt;text x=&quot;400&quot; y=&quot;325&quot; fill=&quot;#94a3b8&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;浏览器缓存命中时连 Nginx 都不问；Nginx 缓存命中时不再回源&amp;lt;/text&amp;gt;
&amp;lt;/svg&amp;gt;&lt;/p&gt;
&lt;p&gt;图注：双层缓存结构与命中路径——浏览器缓存与 Nginx 代理缓存各管一段路，MISS 时才回源。&lt;/p&gt;
&lt;p&gt;两层缓存的失效语义完全不同：浏览器缓存过期了，浏览器会重新发请求；Nginx 缓存过期了，Nginx 会重新回源。它们之间没有自动同步——Nginx 缓存里明明还是旧内容，浏览器也可能因为自己的缓存没过期而继续用更旧的内容。调缓存之前先想清楚：你要控制的是哪一层。&lt;/p&gt;
&lt;h2&gt;proxy_cache_path：先把缓存落在哪、占多大说清楚&lt;/h2&gt;
&lt;p&gt;代理缓存的第一条指令是 &lt;code&gt;proxy_cache_path&lt;/code&gt;，它只能写在 &lt;code&gt;http&lt;/code&gt; 块里，定义缓存落盘的位置和清理策略：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;http {
    proxy_cache_path /var/cache/nginx
                     levels=1:2
                     keys_zone=my_cache:10m
                     max_size=10g
                     inactive=60m
                     use_temp_path=off;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;五个参数各有分工：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;levels=1:2&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;缓存文件按 key 的哈希分两级子目录存放，避免单个目录下文件过多拖慢文件系统&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;keys_zone=my_cache:10m&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;共享内存区的名和大小，存所有缓存条目的元数据（key、过期时间等）；1MB 大约能存 8000 个 key&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;max_size=10g&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;磁盘缓存上限，超过后由 cache manager 按 LRU 淘汰最久未用的文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;inactive=60m&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;一份缓存超过这么久没被访问就删掉，不管它原本的有效期还有多久&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;use_temp_path=off&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;响应直接写进缓存目录，不先写临时目录再搬运，少一次磁盘拷贝&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;inactive&lt;/code&gt; 和有效期是两回事：有效期（&lt;code&gt;proxy_cache_valid&lt;/code&gt;）决定「过期后要不要重新回源验证」，&lt;code&gt;inactive&lt;/code&gt; 决定「多久没人问就从磁盘上删掉」。一份缓存可能有效期是 10 分钟，但 60 分钟没人访问才会被清理；也可能有效期是 1 天，但 60 分钟没人访问就被删了——下次再有人问，就得重新回源。&lt;code&gt;keys_zone&lt;/code&gt; 太小会直接限制能缓存的条目数，缓存没满、内存区先满了，表现就是命中率上不去，查问题时先看这行。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;code&gt;proxy_cache_path&lt;/code&gt; 的目录必须让 Nginx worker 进程可写，且不要放在 &lt;code&gt;/tmp&lt;/code&gt; 这类会被系统定时清理的路径下。目录权限或磁盘空间出问题时，Nginx 不会报错退出，只会默默不缓存——请求照常回源，你看到的现象是「缓存配了却一个 HIT 都没有」。
:::&lt;/p&gt;
&lt;h2&gt;proxy_cache_key：缓存的 key 决定了什么算「同一个请求」&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;proxy_cache&lt;/code&gt; 默认只缓存 GET 与 HEAD 请求。开缓存的第二步，是在 &lt;code&gt;server&lt;/code&gt; 或 &lt;code&gt;location&lt;/code&gt; 里启用它并定 key：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;proxy_cache my_cache;
proxy_cache_key $scheme$proxy_host$request_uri;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;上面这行就是 Nginx 的默认 key：协议 + 上游 host + 完整请求 URI（含查询串）。默认 key 有两个常见坑。第一，查询串会进 key：&lt;code&gt;?utm_source=wechat&lt;/code&gt; 和 &lt;code&gt;?utm_source=weibo&lt;/code&gt; 会被当成两个不同的缓存条目，同一个页面被各种推广参数冲出几十份重复缓存。第二，key 里没有 Cookie、没有请求头，意味着登录用户和游客拿到的可能是同一份缓存——这正是下面要讲的红线。&lt;/p&gt;
&lt;p&gt;定制 key 的思路是：把区分内容的维度放进 key，把不区分内容的维度拿掉。只按路径区分的页面可以这样写：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;proxy_cache_key $scheme$proxy_host$uri;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;需要按语言区分的，再把相关请求头或参数拼进去：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;proxy_cache_key $scheme$proxy_host$uri$is_args$arg_lang;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;key 越粗，命中率越高，但串数据的风险也越大；key 越细，越安全，但缓存越碎。定 key 之前先问自己一句：这份响应的内容到底由哪些东西决定？答案里的每一项都应该进 key，答案之外的东西都不应该进。&lt;/p&gt;
&lt;h2&gt;proxy_cache_valid：按状态码设有效期&lt;/h2&gt;
&lt;p&gt;默认情况下，Nginx 只在上游响应带了明确的 &lt;code&gt;Expires&lt;/code&gt; 或 &lt;code&gt;Cache-Control: max-age&lt;/code&gt; 时才缓存，而且按那个时长来算过期。很多后端根本不发这些头，这时就得用 &lt;code&gt;proxy_cache_valid&lt;/code&gt; 自己定：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
proxy_cache_valid any 1m;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三行的意思是：200 和 302 缓存 10 分钟，404 缓存 1 分钟，其他状态码缓存 1 分钟。404 也值得缓存一小会儿——否则爬虫扫不存在的路径时，每次都要打到后端。优先级上，上游响应里的 &lt;code&gt;X-Accel-Expires&lt;/code&gt; 头会覆盖 &lt;code&gt;proxy_cache_valid&lt;/code&gt;；上游的 &lt;code&gt;Cache-Control: max-age&lt;/code&gt; 同样优先于它。也就是说，&lt;code&gt;proxy_cache_valid&lt;/code&gt; 是「上游没表态时」的兜底，不是最高指令。&lt;/p&gt;
&lt;p&gt;还有两个配套指令值得一起配上。&lt;code&gt;proxy_cache_min_uses 2;&lt;/code&gt; 表示一个 key 被请求两次以上才写入缓存，能挡住一次性扫过的大量冷门 URL 把缓存区冲满。&lt;code&gt;proxy_cache_revalidate on;&lt;/code&gt; 则让过期后的回源带上条件请求（&lt;code&gt;If-Modified-Since&lt;/code&gt; / &lt;code&gt;If-None-Match&lt;/code&gt;），上游回 304 时 Nginx 直接续用旧缓存，省一次完整传输。&lt;/p&gt;
&lt;h2&gt;命中状态：先把 X-Cache-Status 立起来&lt;/h2&gt;
&lt;p&gt;缓存配完第一件事不是调参数，而是让命中状态看得见。加一个响应头：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;add_header X-Cache-Status $upstream_cache_status;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;$upstream_cache_status&lt;/code&gt; 的取值是一张状态表，排障时按表查：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;状态&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;HIT&lt;/td&gt;
&lt;td&gt;缓存命中，直接返回&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MISS&lt;/td&gt;
&lt;td&gt;缓存里没有，回源并按规则写入缓存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;EXPIRED&lt;/td&gt;
&lt;td&gt;缓存过期，回源取新内容&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;STALE&lt;/td&gt;
&lt;td&gt;缓存过期但按 &lt;code&gt;proxy_cache_use_stale&lt;/code&gt; 返回了旧内容&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;UPDATING&lt;/td&gt;
&lt;td&gt;缓存过期，正在回源更新，其他请求按 &lt;code&gt;proxy_cache_lock&lt;/code&gt; 在等&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;BYPASS&lt;/td&gt;
&lt;td&gt;请求被 &lt;code&gt;proxy_cache_bypass&lt;/code&gt; 绕过缓存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;REVALIDATED&lt;/td&gt;
&lt;td&gt;条件请求得到 304，旧缓存续用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;注意 &lt;code&gt;add_header&lt;/code&gt; 写在 &lt;code&gt;location&lt;/code&gt; 里会覆盖从上层继承的所有 &lt;code&gt;add_header&lt;/code&gt;，如果上层还加了别的安全头，需要在同一个 &lt;code&gt;location&lt;/code&gt; 里一并重写一遍。&lt;code&gt;$upstream_cache_status&lt;/code&gt; 只在经过 &lt;code&gt;proxy_pass&lt;/code&gt; 的请求上有值，直出静态文件的 location 里它是空的。&lt;/p&gt;
&lt;h2&gt;缓存判定全流程：一个请求在缓存里走哪条路&lt;/h2&gt;
&lt;p&gt;把上面几节串起来，一个请求在 Nginx 缓存里的完整判定流程是下面这样：&lt;/p&gt;
&lt;p&gt;&amp;lt;svg xmlns=&quot;http://www.w3.org/2000/svg&quot; viewBox=&quot;0 0 800 560&quot; fill=&quot;none&quot; style=&quot;width:100%;height:auto&quot; role=&quot;img&quot; aria-label=&quot;Nginx 缓存判定流程图&quot;&amp;gt;
&amp;lt;rect x=&quot;280&quot; y=&quot;20&quot; width=&quot;240&quot; height=&quot;48&quot; rx=&quot;10&quot; stroke=&quot;#38bdf8&quot; stroke-width=&quot;2&quot;/&amp;gt;
&amp;lt;text x=&quot;400&quot; y=&quot;50&quot; fill=&quot;#e2e8f0&quot; font-size=&quot;15&quot; text-anchor=&quot;middle&quot;&amp;gt;请求到达 Nginx&amp;lt;/text&amp;gt;
&amp;lt;path d=&quot;M400 68 V 96&quot; stroke=&quot;#94a3b8&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;path d=&quot;M400 96 L 470 136 L 400 176 L 330 136 Z&quot; stroke=&quot;#fbbf24&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;text x=&quot;400&quot; y=&quot;132&quot; fill=&quot;#e2e8f0&quot; font-size=&quot;14&quot; text-anchor=&quot;middle&quot;&amp;gt;GET / HEAD？&amp;lt;/text&amp;gt;
&amp;lt;text x=&quot;400&quot; y=&quot;152&quot; fill=&quot;#94a3b8&quot; font-size=&quot;12&quot; text-anchor=&quot;middle&quot;&amp;gt;且未被 bypass&amp;lt;/text&amp;gt;
&amp;lt;path d=&quot;M470 136 H 580 V 290 H 540&quot; stroke=&quot;#94a3b8&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;text x=&quot;625&quot; y=&quot;210&quot; fill=&quot;#94a3b8&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;否：直接回源&amp;lt;/text&amp;gt;
&amp;lt;text x=&quot;625&quot; y=&quot;230&quot; fill=&quot;#94a3b8&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;不查也不写缓存&amp;lt;/text&amp;gt;
&amp;lt;path d=&quot;M400 176 V 204&quot; stroke=&quot;#94a3b8&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;path d=&quot;M400 204 L 470 244 L 400 284 L 330 244 Z&quot; stroke=&quot;#fbbf24&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;text x=&quot;400&quot; y=&quot;240&quot; fill=&quot;#e2e8f0&quot; font-size=&quot;14&quot; text-anchor=&quot;middle&quot;&amp;gt;按 key 查缓存&amp;lt;/text&amp;gt;
&amp;lt;text x=&quot;400&quot; y=&quot;260&quot; fill=&quot;#94a3b8&quot; font-size=&quot;12&quot; text-anchor=&quot;middle&quot;&amp;gt;命中且未过期？&amp;lt;/text&amp;gt;
&amp;lt;path d=&quot;M470 244 H 580 V 340 H 540&quot; stroke=&quot;#94a3b8&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;text x=&quot;625&quot; y=&quot;300&quot; fill=&quot;#94a3b8&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;否：MISS / EXPIRED&amp;lt;/text&amp;gt;
&amp;lt;text x=&quot;625&quot; y=&quot;320&quot; fill=&quot;#94a3b8&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;回源取新内容&amp;lt;/text&amp;gt;
&amp;lt;path d=&quot;M330 244 H 230 V 340 H 260&quot; stroke=&quot;#34d399&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;text x=&quot;140&quot; y=&quot;300&quot; fill=&quot;#34d399&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;是：HIT&amp;lt;/text&amp;gt;
&amp;lt;text x=&quot;140&quot; y=&quot;320&quot; fill=&quot;#34d399&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;直接返回&amp;lt;/text&amp;gt;
&amp;lt;path d=&quot;M400 284 V 312&quot; stroke=&quot;#94a3b8&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;path d=&quot;M400 312 L 470 352 L 400 392 L 330 352 Z&quot; stroke=&quot;#fbbf24&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;text x=&quot;400&quot; y=&quot;348&quot; fill=&quot;#e2e8f0&quot; font-size=&quot;14&quot; text-anchor=&quot;middle&quot;&amp;gt;响应可缓存？&amp;lt;/text&amp;gt;
&amp;lt;text x=&quot;400&quot; y=&quot;368&quot; fill=&quot;#94a3b8&quot; font-size=&quot;12&quot; text-anchor=&quot;middle&quot;&amp;gt;状态码 / 响应头检查&amp;lt;/text&amp;gt;
&amp;lt;path d=&quot;M470 352 H 580 V 440 H 540&quot; stroke=&quot;#94a3b8&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;text x=&quot;625&quot; y=&quot;400&quot; fill=&quot;#94a3b8&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;否：只返回不写入&amp;lt;/text&amp;gt;
&amp;lt;path d=&quot;M330 352 H 230 V 440 H 260&quot; stroke=&quot;#34d399&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;text x=&quot;140&quot; y=&quot;400&quot; fill=&quot;#34d399&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;是：写入缓存&amp;lt;/text&amp;gt;
&amp;lt;text x=&quot;140&quot; y=&quot;420&quot; fill=&quot;#34d399&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;再返回响应&amp;lt;/text&amp;gt;
&amp;lt;rect x=&quot;280&quot; y=&quot;460&quot; width=&quot;240&quot; height=&quot;48&quot; rx=&quot;10&quot; stroke=&quot;#38bdf8&quot; stroke-width=&quot;2&quot;/&amp;gt;
&amp;lt;text x=&quot;400&quot; y=&quot;490&quot; fill=&quot;#e2e8f0&quot; font-size=&quot;15&quot; text-anchor=&quot;middle&quot;&amp;gt;响应返回给客户端&amp;lt;/text&amp;gt;
&amp;lt;path d=&quot;M400 392 V 460&quot; stroke=&quot;#94a3b8&quot; stroke-width=&quot;1.5&quot;/&amp;gt;
&amp;lt;text x=&quot;400&quot; y=&quot;540&quot; fill=&quot;#94a3b8&quot; font-size=&quot;13&quot; text-anchor=&quot;middle&quot;&amp;gt;回源失败时可按 proxy_cache_use_stale 返回过期旧内容兜底&amp;lt;/text&amp;gt;
&amp;lt;/svg&amp;gt;&lt;/p&gt;
&lt;p&gt;图注：Nginx 缓存判定流程——方法与 bypass 先过滤，命中直接返回，未命中回源后再决定是否写入。&lt;/p&gt;
&lt;p&gt;PPT 式把这个流程再拆成五步，每一步对应一个检查点：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第 1 步：方法过滤。&lt;/strong&gt; 只有 GET 与 HEAD 请求会进缓存逻辑，POST、PUT、DELETE 默认直接回源，既不查也不写。&lt;code&gt;proxy_cache_methods&lt;/code&gt; 可以改这个默认值，但改之前要想清楚：把 POST 的响应缓存下来，等于把「提交一次表单」的结果发给所有后来的人。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第 2 步：bypass 检查。&lt;/strong&gt; &lt;code&gt;proxy_cache_bypass&lt;/code&gt; 命中的请求会跳过缓存直接回源，&lt;code&gt;proxy_no_cache&lt;/code&gt; 命中的请求回源后不写入缓存。两者常配合 Cookie 或参数使用，例如登录用户带了 &lt;code&gt;nocache&lt;/code&gt; Cookie 就绕过缓存：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;proxy_cache_bypass $cookie_nocache $arg_nocache;
proxy_no_cache $cookie_nocache $arg_nocache;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第 3 步：按 key 查缓存。&lt;/strong&gt; key 命中且未过期，直接返回，状态 HIT；key 不存在是 MISS；key 存在但过期了是 EXPIRED。查不到或过期了都进入回源分支。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第 4 步：响应可缓存性检查。&lt;/strong&gt; 回源后，Nginx 按响应状态码和响应头决定写不写缓存。默认不缓存的响应包括：带 &lt;code&gt;Set-Cookie&lt;/code&gt; 的响应、&lt;code&gt;Cache-Control&lt;/code&gt; 含 &lt;code&gt;private&lt;/code&gt;、&lt;code&gt;no-store&lt;/code&gt; 或 &lt;code&gt;no-cache&lt;/code&gt; 的响应。想强制缓存这类响应要用 &lt;code&gt;proxy_ignore_headers&lt;/code&gt;，但那等于亲手关掉安全阀——除非你清楚自己在做什么，否则别动这一行。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第 5 步：写入与返回。&lt;/strong&gt; 可缓存的响应先写磁盘缓存再返回；不可缓存的只返回不写。回源失败时，如果配了 &lt;code&gt;proxy_cache_use_stale&lt;/code&gt;，Nginx 可以拿过期的旧内容先顶上：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;proxy_cache_use_stale error timeout invalid_header updating http_500 http_502 http_503 http_504;
proxy_cache_background_update on;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;proxy_cache_background_update on&lt;/code&gt; 的意思是：过期后第一个请求触发后台回源更新，其他请求先拿旧内容，不用排队等。这对读多写少的页面很友好，但要配合 &lt;code&gt;updating&lt;/code&gt; 一起用——否则后台更新期间的其他请求可能直接穿透到后端。&lt;/p&gt;
&lt;h2&gt;缓存击穿：过期那一秒，所有请求一起回源&lt;/h2&gt;
&lt;p&gt;热门页面的缓存刚过期那一刻，如果同一秒涌进来几百个请求，默认行为是它们全部打到后端——这就是缓存击穿。&lt;code&gt;proxy_cache_lock&lt;/code&gt; 的作用是让同一 key 的过期回源只放行一个请求，其他请求等着：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;proxy_cache_lock on;
proxy_cache_lock_timeout 5s;
proxy_cache_lock_age 5s;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;proxy_cache_lock_timeout&lt;/code&gt; 是等待上限，超过还没拿到新内容就直接回源，不再等；&lt;code&gt;proxy_cache_lock_age&lt;/code&gt; 是上一个回源请求超过多久还没返回，就放下一个请求也去回源，避免第一个请求挂死导致所有人无限等待。锁的粒度是 key，锁住 A 页面不影响 B 页面。&lt;/p&gt;
&lt;p&gt;微缓存是另一个思路：给本来「动态」的内容也设一个很短的有效期，比如 1 秒：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;proxy_cache_valid 200 1s;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;高并发下，同一秒内的几百个请求只打一次后端，剩下 999 个都命中缓存。内容延迟最多 1 秒，对列表页、热搜这类场景完全可以接受。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;微缓存的本质是拿 1 秒的延迟换几百倍的回源削减，代价小、收益大，是动态站最划算的一行配置。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;浏览器缓存：expires 与版本化文件名&lt;/h2&gt;
&lt;p&gt;代理缓存管的是 Nginx 到后端这一段，浏览器缓存管的是浏览器到 Nginx 这一段。静态资源的浏览器缓存用 &lt;code&gt;expires&lt;/code&gt; 指令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location ~* \.(jpg|jpeg|png|gif|css|js|woff2)$ {
    expires 30d;
    access_log off;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;expires 30d&lt;/code&gt; 会同时发 &lt;code&gt;Expires&lt;/code&gt; 与 &lt;code&gt;Cache-Control: max-age=2592000&lt;/code&gt; 两个头。注意 &lt;code&gt;expires&lt;/code&gt; 与 &lt;code&gt;add_header Cache-Control&lt;/code&gt; 不要在同一个 location 里混用，两者都会写 &lt;code&gt;Cache-Control&lt;/code&gt;，结果是发出去两个值，浏览器按哪个算要看实现，等于把决定权交了出去。&lt;/p&gt;
&lt;p&gt;浏览器缓存真正好用的形态是「长缓存 + 文件名带哈希」：构建时把 &lt;code&gt;app.js&lt;/code&gt; 输出成 &lt;code&gt;app.a3f9c2.js&lt;/code&gt;，内容一变文件名就变，旧文件永远不会被错拿。这时可以放心给一年：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location ~* \.[0-9a-f]{8}\.(css|js)$ {
    expires 1y;
    add_header Cache-Control &quot;public, immutable&quot;;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;immutable&lt;/code&gt; 告诉浏览器：这个 URL 的内容永远不会变，连条件请求都别发。没带哈希的文件名千万别加 &lt;code&gt;immutable&lt;/code&gt;，否则改了内容用户也拿不到新文件，只能等缓存自然过期或者手动清浏览器缓存。&lt;code&gt;ETag&lt;/code&gt; 与 &lt;code&gt;Last-Modified&lt;/code&gt; 默认是开着的，浏览器缓存过期后会带条件请求回来验证，命中 304 就不用重新下载全文——这是浏览器缓存的第二道防线。&lt;/p&gt;
&lt;p&gt;Cloudflare 那一层的缓存规则是另一个维度的玩法，边缘节点的缓存策略见&lt;a href=&quot;/posts/cloudflare-cache-rules/&quot;&gt;《Cloudflare 缓存规则》&lt;/a&gt;。Nginx 这一层与 CDN 层的区别在于：CDN 缓存面向全球访客，Nginx 缓存面向回源请求，两者可以叠加，但失效与清理要分开算。&lt;/p&gt;
&lt;h2&gt;缓存清理的现实办法&lt;/h2&gt;
&lt;p&gt;缓存最大的麻烦不是建，是清。Nginx 开源版没有像商业版那样的缓存清理 API，现实中可用的办法按从常用到少用排：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;办法&lt;/th&gt;
&lt;th&gt;做法&lt;/th&gt;
&lt;th&gt;适用场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;改文件名 / 改路径&lt;/td&gt;
&lt;td&gt;静态资源换带新哈希的文件名，或换 URL&lt;/td&gt;
&lt;td&gt;静态资源更新，首选&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;proxy_cache_bypass&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;带特定参数或 Cookie 的请求绕过缓存&lt;/td&gt;
&lt;td&gt;单个页面紧急刷新&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;换 key 前缀&lt;/td&gt;
&lt;td&gt;&lt;code&gt;proxy_cache_key&lt;/code&gt; 里加版本号，发布时改版本号&lt;/td&gt;
&lt;td&gt;整站内容大改版&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;删缓存目录文件&lt;/td&gt;
&lt;td&gt;直接删 &lt;code&gt;/var/cache/nginx&lt;/code&gt; 下对应文件后重载&lt;/td&gt;
&lt;td&gt;兜底手段，事后要确认 key 的哈希路径&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;第三方 purge 模块&lt;/td&gt;
&lt;td&gt;编译 &lt;code&gt;ngx_cache_purge&lt;/code&gt; 模块，加 &lt;code&gt;proxy_cache_purge&lt;/code&gt; 指令&lt;/td&gt;
&lt;td&gt;需要编译进 Nginx，不推荐新手碰&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Nginx Plus&lt;/td&gt;
&lt;td&gt;商业版自带 purge API&lt;/td&gt;
&lt;td&gt;有商业版授权时才有&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;开源版没有 purge 接口是官方文档明确写清的事实，不要指望靠重启 Nginx 清缓存——重启不会删磁盘上的缓存文件，起来之后旧内容照样命中。真正可靠的清理策略是在设计期就留好：静态资源走哈希文件名，页面内容走短有效期 + &lt;code&gt;proxy_cache_bypass&lt;/code&gt; 的紧急通道，整站大改版走 key 前缀版本号。&lt;/p&gt;
&lt;h2&gt;排障小节：缓存不生效的五种常见原因&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. 配了缓存却一个 HIT 都没有。&lt;/strong&gt; 先看响应头：上游回了 &lt;code&gt;Set-Cookie&lt;/code&gt; 或 &lt;code&gt;Cache-Control: private&lt;/code&gt;，默认就不缓存。再看请求方法：POST 请求本来就不进缓存。最后看 &lt;code&gt;proxy_cache_path&lt;/code&gt; 的目录权限与磁盘空间，写不进盘的缓存等于没配。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 登录用户串了数据。&lt;/strong&gt; 匿名页与登录后页面共用同一个 key，登录用户看到的是游客的缓存页，或者反过来。解法是把登录态排除在缓存之外：&lt;code&gt;proxy_no_cache&lt;/code&gt; 与 &lt;code&gt;proxy_cache_bypass&lt;/code&gt; 按登录 Cookie 生效，或者直接给登录后的 location 关掉 &lt;code&gt;proxy_cache&lt;/code&gt;。:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;带登录态、带个人信息的响应绝不能进共享缓存。&amp;lt;/span&amp;gt;一份缓存错发给陌生人，泄露的就是别人的账号信息，事后删缓存也收不回已经发出的数据。
:::&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 缓存了不该缓存的错误页。&lt;/strong&gt; &lt;code&gt;proxy_cache_valid any 1m&lt;/code&gt; 会把 500 错误也缓存一分钟，等于把一次后端故障放大成一分钟的故障。&lt;code&gt;proxy_cache_valid&lt;/code&gt; 按状态码分开写，错误码给极短有效期或不写进去；配合 &lt;code&gt;proxy_cache_use_stale&lt;/code&gt;，回源失败时宁可返回旧的正确内容，也别缓存新的错误内容。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 缓存过期后后端被打垮。&lt;/strong&gt; 热门页面过期瞬间大量回源，先确认 &lt;code&gt;proxy_cache_lock&lt;/code&gt; 开了没有，再看 &lt;code&gt;proxy_cache_background_update&lt;/code&gt; 是否配合 &lt;code&gt;updating&lt;/code&gt; 使用。如果后端本身就扛不住单次回源的并发，锁也救不了——这时应该先上微缓存，把回源频率压到每秒一次。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. 磁盘被缓存占满。&lt;/strong&gt; &lt;code&gt;max_size&lt;/code&gt; 没设或设得太大，cache manager 淘汰跟不上写入速度，磁盘写满后 Nginx 照常服务但新缓存写不进去。查 &lt;code&gt;df&lt;/code&gt; 与缓存目录大小，&lt;code&gt;max_size&lt;/code&gt; 按磁盘实际余量设，并留出余地；&lt;code&gt;inactive&lt;/code&gt; 太长会让冷门内容长期占盘，太短又让缓存频繁失效，按访问规律调。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Nginx 缓存是两本账：&lt;code&gt;proxy_cache&lt;/code&gt; 管 Nginx 到后端，浏览器缓存管浏览器到 Nginx。配代理缓存抓住三条主线——&lt;code&gt;proxy_cache_path&lt;/code&gt; 定落盘与清理策略，&lt;code&gt;proxy_cache_key&lt;/code&gt; 定什么算同一个请求，&lt;code&gt;proxy_cache_valid&lt;/code&gt; 定按状态码的有效期；再用 &lt;code&gt;X-Cache-Status&lt;/code&gt; 把命中状态立起来，&lt;code&gt;proxy_cache_lock&lt;/code&gt; 与微缓存防击穿，&lt;code&gt;proxy_cache_use_stale&lt;/code&gt; 兜底回源失败。浏览器缓存抓住一条主线：长缓存只给带哈希文件名的静态资源，动态内容靠短有效期与条件请求。清理没有银弹，开源版没有 purge 接口，设计期留好哈希文件名、bypass 通道与 key 版本号，比事后删文件可靠得多。下一篇讲 HTTPS 方向：TLS 调优、OCSP 装订与 HTTP/3 的开启条件。&lt;/p&gt;
</content:encoded></item><item><title>Nginx 负载均衡与健康检查：upstream 的调度算法与故障摘除</title><link>https://www.anexns.cloudns.org/posts/webserver-nginx-load-balancing/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/webserver-nginx-load-balancing/</guid><description>一台后端扛不住就加一台，加完就要有人分流。把 upstream 的四种调度算法、被动健康检查的两个参数、backup 与 down 的用法逐条拆开，讲清故障摘除到底在什么条件下才生效。</description><pubDate>Wed, 18 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;凌晨三点，后端三台机器里有一台磁盘满了，应用进程还活着，但每个请求都卡住不返回。监控没报警，因为端口还通；用户先发现了，因为页面一半能打开、一半转圈。最后是 Nginx 把那台机器摘掉，流量自动分到另外两台，值班的人才睡了个囫囵觉。这个场景里真正起作用的不是某一台机器，而是一组配合：谁来分流、分给谁、分错了怎么办、一台机器坏了多久才会被摘掉。这篇就把这组配合拆开：调度算法、被动健康检查、备份与下线、失败重试、上游长连接，最后说清楚开源版做不到的那件事。&lt;/p&gt;
&lt;h2&gt;负载均衡先回答一个问题：流量到底按什么分&lt;/h2&gt;
&lt;p&gt;Nginx 里做负载均衡的起点是一个 &lt;code&gt;upstream&lt;/code&gt; 块：把一组后端服务器起个名字，&lt;code&gt;proxy_pass&lt;/code&gt; 指过去，流量就不再只去一台机器。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;upstream backend {
    server 10.0.0.11:8080;
    server 10.0.0.12:8080;
    server 10.0.0.13:8080;
}

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://backend;
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;写完这个块，第一个问题就来了：三个后端，请求到底给谁？&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;默认答案是加权轮询：每台服务器的权重默认都是 1，请求按权重比例轮流分，七个请求里权重 5 的那台拿五个，权重 1 的各拿一个。&amp;lt;/span&amp;gt;不写任何调度指令，Nginx 就是这么分的。很多线上配置跑了几年没动过调度算法，不是因为没人懂，而是因为默认的轮询在绝大多数场景下已经够用——三台同规格的机器、请求耗时差不多、无状态服务，轮询分出来的负载天然就是均匀的。先别急着换算法，先确认默认算法是不是真的不够用了。&lt;/p&gt;
&lt;p&gt;轮询有一个隐含前提：每台后端处理请求的速度差不多。如果一台是新机器、一台是旧机器，轮询会把同样的请求量压到旧机器头上，旧机器先被压垮。处理办法不是换算法，而是给权重。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;upstream backend {
    server 10.0.0.11:8080 weight=5;
    server 10.0.0.12:8080 weight=3;
    server 10.0.0.13:8080 weight=1;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;权重是个比例，不是绝对数字。上面这组配置里，九个请求中第一台拿五个、第二台拿三个、第三台拿一个。机器扩容时先给新机器一个小权重、观察一阵再往上加，缩容时反过来先降权重、再下线，是最稳妥的灰度办法。&lt;/p&gt;
&lt;h2&gt;四种调度算法：一张表先看全貌&lt;/h2&gt;
&lt;p&gt;Nginx 开源版自带的调度算法就四种（加上默认轮询算五种写法），先一张表看完，再逐个展开。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;算法&lt;/th&gt;
&lt;th&gt;指令&lt;/th&gt;
&lt;th&gt;分流依据&lt;/th&gt;
&lt;th&gt;适合的场景&lt;/th&gt;
&lt;th&gt;要注意的点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;加权轮询&lt;/td&gt;
&lt;td&gt;不写指令，默认生效&lt;/td&gt;
&lt;td&gt;权重比例轮流&lt;/td&gt;
&lt;td&gt;同规格无状态后端&lt;/td&gt;
&lt;td&gt;后端速度差异大时要配 weight&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;最少连接&lt;/td&gt;
&lt;td&gt;&lt;code&gt;least_conn&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;当前活动连接数最少&lt;/td&gt;
&lt;td&gt;请求耗时差异大、长连接多&lt;/td&gt;
&lt;td&gt;只看连接数，不看 CPU 和响应时间&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;IP 哈希&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ip_hash&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;客户端 IP 的哈希&lt;/td&gt;
&lt;td&gt;需要会话保持、无共享会话存储&lt;/td&gt;
&lt;td&gt;节点增减会打乱映射，NAT 后容易失衡&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;通用哈希&lt;/td&gt;
&lt;td&gt;&lt;code&gt;hash $变量 [consistent]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;指定变量的哈希&lt;/td&gt;
&lt;td&gt;按用户、按缓存键分流&lt;/td&gt;
&lt;td&gt;节点增减会打乱映射，&lt;code&gt;consistent&lt;/code&gt; 可缓解&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;随机&lt;/td&gt;
&lt;td&gt;&lt;code&gt;random [two [least_conn]]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;随机挑一台&lt;/td&gt;
&lt;td&gt;后端规模大、想避开轮询的整齐步调&lt;/td&gt;
&lt;td&gt;结果不可预测，排障时要看日志确认&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这张表里最容易被误解的是 &lt;code&gt;least_conn&lt;/code&gt;。它看的是活动连接数，不是负载。两台后端各有 100 个连接，但一台的连接全是刚握手还没发请求的空闲长连接、另一台的连接全在跑慢查询，&lt;code&gt;least_conn&lt;/code&gt; 照样可能把新请求派给正在跑慢查询的那台。它解决的是「请求耗时差异大」的问题：一个请求 10 毫秒、一个请求 10 秒，轮询会把慢请求均匀地摊到每台机器上，每台机器手里都攒着几个慢请求；&lt;code&gt;least_conn&lt;/code&gt; 会把新请求派给手头连接最少的那台，慢请求集中的机器自然少接新活。长连接多的场景也一样：WebSocket 连上来就不走，轮询只管数量均分，&lt;code&gt;least_conn&lt;/code&gt; 管的是谁手里还空着。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;upstream backend {
    least_conn;
    server 10.0.0.11:8080;
    server 10.0.0.12:8080;
    server 10.0.0.13:8080;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;least_conn&lt;/code&gt; 的计数是按 worker 进程分别算的，这一点和 &lt;code&gt;keepalive&lt;/code&gt; 一样，见本系列第 2 篇&lt;a href=&quot;/posts/webserver-nginx-reverse-proxy/&quot;&gt;Nginx 反向代理深挖：proxy_pass 的斜杠、头传递与缓冲取舍&lt;/a&gt;里上游长连接那节。多 worker 下每个 worker 各自维护自己的连接数视图，分流结果是「大致均衡」而不是「精确均衡」，这对绝大多数场景都够了。&lt;/p&gt;
&lt;h2&gt;ip_hash：会话保持的便宜办法，和它的三处代价&lt;/h2&gt;
&lt;p&gt;有些应用把登录状态存在本机内存里，没有共享的会话存储，同一个用户的请求必须一直落到同一台后端。最便宜的办法是 &lt;code&gt;ip_hash&lt;/code&gt;：拿客户端 IPv4 地址的前三个字节（IPv6 则用整个地址）算哈希，同一个客户端永远去同一台后端。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;upstream backend {
    ip_hash;
    server 10.0.0.11:8080;
    server 10.0.0.12:8080;
    server 10.0.0.13:8080;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;便宜是有代价的，第一处代价是节点增减会打乱映射。&lt;code&gt;ip_hash&lt;/code&gt; 算出来的是一个固定位置，扩容加一台机器、缩容减一台机器，大量客户端会被重新映射到别的后端，存在本机的会话当场失效。临时摘掉一台机器做维护时，正确做法是把它标成 &lt;code&gt;down&lt;/code&gt;，而不是从配置里删掉——标 &lt;code&gt;down&lt;/code&gt; 会保留现有的哈希映射关系，删配置则不会。&lt;/p&gt;
&lt;p&gt;第二处代价是分布不均。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;公司、学校、商场里几百人共用一个出口 IP，&lt;code&gt;ip_hash&lt;/code&gt; 会把这几百人全派到同一台后端，流量分布完全取决于客户端 IP 的分布，而不是后端的承载能力。&amp;lt;/span&amp;gt;如果用户集中在少数几个出口 IP 后面，&lt;code&gt;ip_hash&lt;/code&gt; 分出来的负载可能比轮询难看得多。移动网络下客户端 IP 还会变化，IP 一变会话就跳到别的机器上。&lt;/p&gt;
&lt;p&gt;第三处代价是和 &lt;code&gt;backup&lt;/code&gt; 冲突。官方文档写明：&lt;code&gt;backup&lt;/code&gt; 参数不能和 &lt;code&gt;hash&lt;/code&gt;、&lt;code&gt;ip_hash&lt;/code&gt;、&lt;code&gt;random&lt;/code&gt; 三种分流方法一起用。需要会话保持又想要备份节点，这两件事在开源版的 &lt;code&gt;upstream&lt;/code&gt; 语法里是互斥的，得换个思路：要么接受主节点全挂时会话重建，要么把会话存到共享存储（例如 Redis）里，再用轮询加 &lt;code&gt;backup&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;code&gt;ip_hash&lt;/code&gt; 只是「同一个 IP 尽量去同一台」，不是「同一个用户一定去同一台」。客户端 IP 变化、后端节点变化、目标后端不可用，都会让请求换一台机器。把它当作会话保持的唯一手段之前，先确认应用能不能接受会话偶尔丢失——不能接受就不要省共享会话存储这一步。
:::&lt;/p&gt;
&lt;p&gt;&lt;code&gt;hash&lt;/code&gt; 指令是更通用的版本：可以对任意变量做哈希，比如按用户 ID、按缓存键分流。&lt;code&gt;hash $request_uri consistent&lt;/code&gt; 这种写法会启用 ketama 一致性哈希，节点增减时只有少数键会被重新映射，适合拿 Nginx 当缓存层前面那层分流。普通 &lt;code&gt;hash&lt;/code&gt; 不加 &lt;code&gt;consistent&lt;/code&gt; 时，节点一增一减，大部分键都会被打乱，和 &lt;code&gt;ip_hash&lt;/code&gt; 是同一个毛病。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;upstream cache_layer {
    hash $request_uri consistent;
    server 10.0.0.21:8080;
    server 10.0.0.22:8080;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;被动健康检查：max_fails 与 fail_timeout 的双重含义&lt;/h2&gt;
&lt;p&gt;调度算法只管「分给谁」，不管「这台还活不活」。故障摘除靠的是被动健康检查：Nginx 在转发真实请求的过程中数失败次数，失败够了就把这台机器暂时摘掉。两个参数管这件事：&lt;code&gt;max_fails&lt;/code&gt; 和 &lt;code&gt;fail_timeout&lt;/code&gt;。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;upstream backend {
    server 10.0.0.11:8080 max_fails=3 fail_timeout=30s;
    server 10.0.0.12:8080 max_fails=3 fail_timeout=30s;
    server 10.0.0.13:8080 max_fails=3 fail_timeout=30s;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;fail_timeout&lt;/code&gt; 有双重含义，很多人只读了其中一重：它既是统计窗口，也是摘除时长。在 &lt;code&gt;fail_timeout&lt;/code&gt; 设定的 30 秒里累计失败达到 &lt;code&gt;max_fails&lt;/code&gt; 次，这台服务器被认为不可用；随后在接下来的 30 秒里，Nginx 不会再把请求派给它。30 秒一到，Nginx 会放一个请求过去探一探，成功了就恢复，失败了就再摘 30 秒。默认值是 &lt;code&gt;max_fails=1&lt;/code&gt;、&lt;code&gt;fail_timeout=10s&lt;/code&gt;——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;默认配置下一次失败就摘掉 10 秒，这个默认值比大多数人想象的要敏感，调参之前先想清楚你想要的摘除速度。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;什么算「一次失败」，由 &lt;code&gt;proxy_next_upstream&lt;/code&gt; 这类指令说了算，不是 &lt;code&gt;max_fails&lt;/code&gt; 自己说了算。连接不上、连接超时、读响应超时都算；HTTP 500 默认不算，除非显式加上去。把 &lt;code&gt;max_fails&lt;/code&gt; 设成 3、又不改 &lt;code&gt;proxy_next_upstream&lt;/code&gt;，后端返回 500 时请求不会换一台、失败也不会被计数，摘除逻辑等于没接上 500 这条线。这两个指令要对照着看，单看一个会得出错误的结论。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;upstream backend {
    server 10.0.0.11:8080 max_fails=2 fail_timeout=15s;
    server 10.0.0.12:8080 max_fails=2 fail_timeout=15s;
}

server {
    location / {
        proxy_pass http://backend;
        proxy_next_upstream error timeout http_500 http_502 http_503;
        proxy_next_upstream_timeout 5s;
        proxy_next_upstream_tries 2;
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;上面这组配置的含义是：15 秒里失败两次就摘 15 秒；失败时换一台重试，最多重试两次、总共不超过 5 秒。&lt;code&gt;proxy_next_upstream_tries&lt;/code&gt; 和 &lt;code&gt;proxy_next_upstream_timeout&lt;/code&gt; 是两道保险，缺了它们，一次慢接口可能在多台后端之间来回重试，把一次故障放大成几次超时。&lt;/p&gt;
&lt;p&gt;还有两个容易踩的点。第一，&lt;code&gt;max_fails=0&lt;/code&gt; 是关闭失败计数，不是「零容忍」——写 0 等于告诉 Nginx 永远不要摘这台机器。第二，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;upstream 里只有一台服务器时，&lt;code&gt;max_fails&lt;/code&gt;、&lt;code&gt;fail_timeout&lt;/code&gt; 这些参数会被直接忽略，这台机器永远不会被认为不可用。&amp;lt;/span&amp;gt;单节点配一堆健康检查参数等于没配，故障摘除的前提是最少有两台后端。&lt;/p&gt;
&lt;h2&gt;backup 与 down：给故障留一条退路&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;backup&lt;/code&gt; 是最常见的退路写法：平时不接流量，主节点全挂时才顶上。典型用法是备机房、备用服务，或者一台配置低的老机器。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;upstream backend {
    server 10.0.0.11:8080 max_fails=3 fail_timeout=30s;
    server 10.0.0.12:8080 max_fails=3 fail_timeout=30s;
    server 10.0.0.13:8080 backup;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;备份节点平时零流量，切换过去的那一刻它要独自扛下全部请求，冷启动的缓存、没预热的连接池、没跑过满载的配置，全会在切换瞬间暴露出来。备份节点要定期演练：人为把主节点标 &lt;code&gt;down&lt;/code&gt;，确认备份节点真能接住流量，再恢复。没演练过的备份节点只是配置文件里的一行字。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;down&lt;/code&gt; 标的是「永久不可用」，用来做计划内的下线：机器要维护、要升级、要退役，先标 &lt;code&gt;down&lt;/code&gt; 再重载配置，流量立刻不再派过去，等它上面的长连接自然结束再动手。配合 &lt;code&gt;ip_hash&lt;/code&gt; 使用时，&lt;code&gt;down&lt;/code&gt; 的意义更大：删配置会打乱哈希映射，标 &lt;code&gt;down&lt;/code&gt; 不会。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;upstream backend {
    server 10.0.0.11:8080;
    server 10.0.0.12:8080 down;
    server 10.0.0.13:8080;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;max_conns&lt;/code&gt; 是另一个常被忽略的保护参数：限制同时打到一台后端的最大活动连接数，默认 0 表示不限制。后端是单线程的老服务、或者连接一多就内存暴涨的服务，给它设一个 &lt;code&gt;max_conns&lt;/code&gt;，超出的请求会排队等别的后端，而不是把后端直接压垮。这个限制在没配共享内存 zone 的情况下是按 worker 进程算的，多 worker 时实际放过的连接数会比设定值大。&lt;/p&gt;
&lt;h2&gt;proxy_next_upstream：失败了换一台，但要知道代价&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;proxy_next_upstream&lt;/code&gt; 的默认值是 &lt;code&gt;error timeout&lt;/code&gt;：连接失败、连接超时、读超时，换一台重试。HTTP 状态码类的条件默认都不在里面，想让 502、503 也触发重试，得显式加上。&lt;/p&gt;
&lt;p&gt;重试的代价藏在「已经发出去了没有」这个问题里。Nginx 只有在还没向客户端发送任何响应内容时，才能把请求转给下一台后端；响应已经开始传了，再失败就只能把错误交给客户端，没法换一台重来。对 GET 这类读请求，重试一次没什么副作用；&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;对 POST、下单、扣款这类非幂等请求，把 &lt;code&gt;http_500&lt;/code&gt; 之类的条件加进重试列表之前，先确认后端能不能接受同一笔请求被执行两次。&amp;lt;/span&amp;gt;一个写一半就超时的请求，重试一次可能在另一台后端上又写一遍。重试条件加得越宽，重复执行的风险就越大。&lt;/p&gt;
&lt;p&gt;还有一个细节：&lt;code&gt;proxy_next_upstream&lt;/code&gt; 里写 &lt;code&gt;http_500&lt;/code&gt; 这类条件时，&lt;code&gt;max_fails&lt;/code&gt; 的计数也会把这类失败算进去——失败的定义是统一的。反过来，&lt;code&gt;proxy_next_upstream off&lt;/code&gt; 会关掉全部重试，第一次失败就直接把错误返回给客户端。内部工具、一次性回调这类不希望重试的接口，可以在单独的 location 里关掉重试，而不是全局关掉。&lt;/p&gt;
&lt;p&gt;:::warning
重试不是免费的保险。每次重试都是一次新的后端请求，慢接口在三台后端之间各重试一次，总耗时是单次超时的三倍。&lt;code&gt;proxy_next_upstream_tries&lt;/code&gt; 和 &lt;code&gt;proxy_next_upstream_timeout&lt;/code&gt; 一定要配上，否则一次上游抖动可能拖垮整个请求的超时预算。
:::&lt;/p&gt;
&lt;h2&gt;keepalive 连接池：上游长连接的账&lt;/h2&gt;
&lt;p&gt;反代的每一跳如果都重新握手，高并发下光是建连的开销就很可观。&lt;code&gt;upstream&lt;/code&gt; 块里的 &lt;code&gt;keepalive&lt;/code&gt; 指令维护一个空闲连接池：请求用完的连接不关闭，留着给下一个请求复用。配法在第 2 篇里写过，这里补两点负载均衡视角的细节：连接池是按 worker 进程维护的，每个 worker 各自攒自己的池子，&lt;code&gt;keepalive 32&lt;/code&gt; 的意思是每个 worker 最多留 32 条空闲连接，不是全站 32 条；另外要让复用真正生效，&lt;code&gt;proxy_http_version 1.1&lt;/code&gt; 和清空 &lt;code&gt;Connection&lt;/code&gt; 头这两行不能少，否则后端以为每次都是短连接，池子建了也用不上。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;upstream backend {
    server 10.0.0.11:8080;
    server 10.0.0.12:8080;
    keepalive 32;
}

server {
    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection &quot;&quot;;
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;需要说明版本差异：1.29.7 起 &lt;code&gt;keepalive&lt;/code&gt; 默认就是开启的、默认缓存 32 条连接，旧版本需要显式写 &lt;code&gt;keepalive 32&lt;/code&gt; 才会生效。手里 Nginx 版本比较老的时候，别以为默认就开了。连接池也不是越大越好：后端能接受的并发连接数有上限，池子攒太多空闲连接，后端会先看到一堆占着连接不干活的 Nginx worker，反而挤占了真正干活的连接额度。&lt;/p&gt;
&lt;h2&gt;主动健康检查：开源版没有，别再找了&lt;/h2&gt;
&lt;p&gt;被动健康检查有个先天缺陷：它要等真实用户的请求失败了，才知道后端坏了。第一个踩到故障的用户，注定要吃一次失败。主动健康检查是另一条路：Nginx 自己定时去探后端，坏了提前摘、好了自动加回去，用户永远碰不到坏节点。这个功能叫 &lt;code&gt;health_check&lt;/code&gt;，写在 location 里，配合 &lt;code&gt;zone&lt;/code&gt; 共享内存使用。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;upstream backend {
    zone backend 64k;
    server 10.0.0.11:8080;
    server 10.0.0.12:8080;
}

server {
    location / {
        proxy_pass http://backend;
        health_check;
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;上面这段配置在开源版 Nginx 里是跑不起来的。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;code&gt;health_check&lt;/code&gt;、&lt;code&gt;slow_start&lt;/code&gt;、动态 upstream 配置这些能力，只在商业版 Nginx Plus 里提供，开源版没有，搜到的教程里出现这些指令，先看一眼它用的是哪个版本。&amp;lt;/span&amp;gt;&lt;code&gt;slow_start&lt;/code&gt; 也是一样：节点恢复后权重从零慢慢涨回去，避免刚恢复的节点瞬间被流量打满，这个功能同样只在 Plus 里有。开源版里节点一恢复就立刻按满权重接流量，恢复后第一次慢查询高峰往往就发生在这里。&lt;/p&gt;
&lt;p&gt;开源版的替代办法是把「探测」这件事交给外部：用专门的监控工具定时探活，探到故障就改配置、重载 Nginx，或者在更外层做摘除。站里之前写过&lt;a href=&quot;/posts/monitoring-gatus/&quot;&gt;Gatus 轻量监控实战&lt;/a&gt;，那套路子就是外部探测加告警，探到后端挂了先告警、再人工或脚本介入摘除。反应速度比不上内置的主动检查，但对自建服务来说，这是一条不用付费就能走通的路。被动检查继续留在配置里兜底：外部探测负责发现，&lt;code&gt;max_fails&lt;/code&gt; 负责在真实请求层面最后一道摘除。&lt;/p&gt;
&lt;h2&gt;排障：负载均衡出问题，先按这个顺序查&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. 所有请求都 502，但后端单台直连是好的&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;先看 &lt;code&gt;error.log&lt;/code&gt; 里 upstream 报错的原文，再对照第 8 篇要讲的 502/504 定位表。最常见的是三种：后端监听地址写成了 &lt;code&gt;127.0.0.1&lt;/code&gt;，Nginx 和后端不在同一台机器上所以连不上；后端进程挂了但端口还在 TIME_WAIT，Nginx 以为能连；防火墙只放行了 80，没放行后端端口。用 &lt;code&gt;curl&lt;/code&gt; 从 Nginx 所在的机器直接请求后端地址，先确认网络层通不通，再查应用层。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 某台后端 CPU 总是满的，其他几台很闲&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;先确认调度算法是不是轮询、权重是不是一样，再看这台机器是不是接了不成比例的慢请求。&lt;code&gt;least_conn&lt;/code&gt; 只看连接数不看耗时，慢请求集中的机器连接数不高、CPU 却很高是正常现象。打开 &lt;code&gt;log_format&lt;/code&gt; 里的 &lt;code&gt;$upstream_response_time&lt;/code&gt;，按后端分组统计平均耗时，慢的那个要先解决它自己的问题，而不是调权重把它藏起来。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 扩容加了一台机器，大量用户掉登录&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;这是 &lt;code&gt;ip_hash&lt;/code&gt; 的典型症状：节点一变，哈希映射跟着变，存在本机内存的会话全部失效。先确认是不是用了 &lt;code&gt;ip_hash&lt;/code&gt;，再确认会话是不是存在本机。如果会话必须存在本机，扩容时先标 &lt;code&gt;down&lt;/code&gt; 再加节点，或者干脆把会话迁到共享存储，再换回轮询。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 后端明明挂了，Nginx 还往上派请求&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;先数三件事：&lt;code&gt;max_fails&lt;/code&gt; 设了几、&lt;code&gt;fail_timeout&lt;/code&gt; 设了多久、&lt;code&gt;proxy_next_upstream&lt;/code&gt; 里有没有把这种失败算进去。后端返回 500 但 &lt;code&gt;proxy_next_upstream&lt;/code&gt; 没加 &lt;code&gt;http_500&lt;/code&gt;，失败不计数、不换台，摘除永远触发不了。反过来，&lt;code&gt;max_fails=1&lt;/code&gt; 的默认配置会让一次网络抖动就摘掉节点 10 秒，故障没排除、节点先被反复摘。两个极端都要对照着调。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. 单节点 upstream 配了健康检查参数，一点用没有&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;这是官方文档里明确写了的行为：upstream 里只有一台服务器时，&lt;code&gt;max_fails&lt;/code&gt;、&lt;code&gt;fail_timeout&lt;/code&gt;、&lt;code&gt;slow_start&lt;/code&gt; 全部被忽略，这台服务器永远不会被认为不可用。单节点服务的高可用不能靠 upstream 参数实现，要么再加一台后端，要么在外层用监控加自动重启兜底。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;负载均衡这套配置可以收成四句话：调度算法先看默认轮询够不够用，不够用再按场景换 &lt;code&gt;least_conn&lt;/code&gt; 或 &lt;code&gt;ip_hash&lt;/code&gt;；故障摘除靠 &lt;code&gt;max_fails&lt;/code&gt; 加 &lt;code&gt;fail_timeout&lt;/code&gt;，两个参数的默认值都比想象中敏感，调之前先想清楚要多快摘、多快恢复；&lt;code&gt;backup&lt;/code&gt; 和 &lt;code&gt;down&lt;/code&gt; 是留给故障和维护的退路，备份节点不演练等于没有；主动健康检查和 &lt;code&gt;slow_start&lt;/code&gt; 只在 Nginx Plus 里有，开源版用被动检查加外部监控组合着兜底。下一篇讲缓存：&lt;code&gt;proxy_cache&lt;/code&gt; 的代理缓存和浏览器缓存是两层账，&lt;code&gt;proxy_cache_lock&lt;/code&gt; 防击穿、&lt;code&gt;proxy_cache_valid&lt;/code&gt; 按状态码设时长，缓存清理在开源版里没有现成答案，得先想清楚再配。&lt;/p&gt;
</content:encoded></item><item><title>Nginx 反向代理深挖：proxy_pass 的斜杠、头传递与缓冲取舍</title><link>https://www.anexns.cloudns.org/posts/webserver-nginx-reverse-proxy/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/webserver-nginx-reverse-proxy/</guid><description>把 proxy_pass 的斜杠规则、请求头的传递方式、WebSocket 升级、缓冲开关与上游长连接逐条拆开，讲清反向代理里最容易配错的五个地方。</description><pubDate>Tue, 17 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;把 Nginx 装在应用前面做反向代理，是它最常见的用法，也是最容易「配出来能跑、跑起来不对」的用法。请求能通不等于配置是对的：后端收到的路径可能多了一截、拿到的客户端 IP 可能是 Nginx 自己的、WebSocket 握手可能莫名失败、SSE 推送可能被缓冲拖成一坨——这些问题全都藏在反向代理的几个细节里。这篇就把反代的五条主线一次讲透：&lt;code&gt;proxy_pass&lt;/code&gt; 的斜杠规则、请求头的传递、WebSocket 的升级、缓冲的取舍、上游长连接与超时。搞懂这五条，反代配置才算真正受控。如果暂时不想手写配置，也可以先用面板方案顶着，见&lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager 实战&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;proxy_pass 的斜杠：一条斜杠，两种转发结果&lt;/h2&gt;
&lt;p&gt;反代配置里最容易踩的坑，就是 &lt;code&gt;proxy_pass&lt;/code&gt; 后面那个不起眼的 URI 部分。先看官方文档给出的规则：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;code&gt;proxy_pass&lt;/code&gt; 带 URI 时，请求 URI 里与 location 匹配的那部分会被替换成指令里的 URI；不带 URI 时，原始 URI 原样转发。&amp;lt;/span&amp;gt;这句话值得逐字读三遍，因为它决定了后端最终收到什么路径。location 匹配本身的优先级规则，见本系列第 1 篇&lt;a href=&quot;/posts/webserver-nginx-architecture/&quot;&gt;Nginx 架构深挖：进程模型、配置结构与 location 匹配顺序&lt;/a&gt;。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location /api/ {
    proxy_pass http://127.0.0.1:8080;
}

location /api/ {
    proxy_pass http://127.0.0.1:8080/;
}

location /api/ {
    proxy_pass http://127.0.0.1:8080/v1/;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三段配置看起来只差一个斜杠，转发结果完全不同。假设请求是 &lt;code&gt;GET /api/users/42&lt;/code&gt;，后端收到的分别是：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;配置写法&lt;/th&gt;
&lt;th&gt;后端收到的 URI&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;proxy_pass http://127.0.0.1:8080;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/api/users/42&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;proxy_pass http://127.0.0.1:8080/;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/users/42&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;proxy_pass http://127.0.0.1:8080/v1/;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/v1/users/42&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;第一种不带 URI，原始 URI 原样送过去，后端必须自己处理 &lt;code&gt;/api&lt;/code&gt; 前缀；第二种带一个斜杠，location 匹配到的 &lt;code&gt;/api/&lt;/code&gt; 部分被替换成 &lt;code&gt;/&lt;/code&gt;，相当于把前缀剥掉；第三种则把 &lt;code&gt;/api/&lt;/code&gt; 换成 &lt;code&gt;/v1/&lt;/code&gt;，等于在转发时顺手改写了路径前缀。日常最常见的需求是「剥掉前缀」，写法就是第二种：&lt;code&gt;proxy_pass&lt;/code&gt; 末尾加一个斜杠。&lt;/p&gt;
&lt;p&gt;这里有两点要特别注意。第一，&lt;strong&gt;只有前缀 location 才有「替换匹配部分」这个说法&lt;/strong&gt;。如果 location 是用正则写的，Nginx 无法确定要替换请求 URI 的哪一段，这时 &lt;code&gt;proxy_pass&lt;/code&gt; 带 URI 会把整个请求 URI 直接换成指令里写的 URI，行为和直觉完全不同。正则 location 下想改写路径，老老实实用 &lt;code&gt;rewrite&lt;/code&gt; 再转发，别指望斜杠帮你干活。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location ~ ^/api/v([0-9]+)/(.*)$ {
    rewrite ^/api/v[0-9]+/(.*)$ /$1 break;
    proxy_pass http://127.0.0.1:8080;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第二，&lt;code&gt;proxy_pass&lt;/code&gt; 的 URI 里可以带变量，但带变量之后行为会变：Nginx 不再按上面的替换规则处理，而是把 URI 重新解析——具体表现是请求 URI 不再做替换、直接拼到变量解析出的地址后面。想用变量做动态上游时，路径处理要自己用 &lt;code&gt;rewrite&lt;/code&gt; 兜底，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把变量和斜杠替换混在同一条指令里指望它按直觉工作&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;code&gt;proxy_pass&lt;/code&gt; 后面写 &lt;code&gt;http://127.0.0.1:8080&lt;/code&gt; 和 &lt;code&gt;http://127.0.0.1:8080/&lt;/code&gt; 是两回事，前者转发原 URI、后者剥掉 location 前缀。线上很多「后端报 404 但直连后端是好的」问题，根子就是这里多写或少写了一个斜杠。改完务必用 &lt;code&gt;curl&lt;/code&gt; 对照直连和经 Nginx 的两次返回，确认后端收到的路径是你想要的。
:::&lt;/p&gt;
&lt;p&gt;&lt;code&gt;proxy_pass&lt;/code&gt; 还有一个容易被忽略的搭档：&lt;code&gt;proxy_redirect&lt;/code&gt;。后端返回的重定向 &lt;code&gt;Location&lt;/code&gt; 头里往往带着它自己的内网地址或端口，比如 &lt;code&gt;Location: http://127.0.0.1:8080/login&lt;/code&gt;，直接透传给浏览器就断了。默认的 &lt;code&gt;proxy_redirect default&lt;/code&gt; 会按 &lt;code&gt;proxy_pass&lt;/code&gt; 的地址做替换，把内网地址换成对外地址；如果后端返回的地址格式特殊，默认替换覆盖不到，就得显式写 &lt;code&gt;proxy_redirect&lt;/code&gt; 做映射。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location /app/ {
    proxy_pass http://127.0.0.1:8080/;
    proxy_redirect http://127.0.0.1:8080/ /app/;
    proxy_redirect http://internal.example.com/ /app/;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;头传递：后端看到的 IP 和协议，别让 Nginx 吞了&lt;/h2&gt;
&lt;p&gt;反代一接进来，后端眼里的世界就变了：连接是 Nginx 发起的，源 IP 是 Nginx 的内网地址，协议是 Nginx 与后端之间的 HTTP。应用要拿到真实的客户端信息，全靠 Nginx 显式把头传过去。不传，后端日志里所有请求都来自同一个 IP，限流、风控、审计全都会错。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这四行是反代的标配，每一行的含义都不一样：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;请求头&lt;/th&gt;
&lt;th&gt;值&lt;/th&gt;
&lt;th&gt;后端拿到的是什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Host&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;$host&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;客户端请求里的域名，不带端口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;X-Real-IP&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;$remote_addr&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;直连 Nginx 的那个客户端 IP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;X-Forwarded-For&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;$proxy_add_x_forwarded_for&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;客户端 IP 追加到已有链路末尾&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;X-Forwarded-Proto&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;$scheme&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;客户端到 Nginx 用的是 http 还是 https&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;Host&lt;/code&gt; 最值得单独说一句。&lt;code&gt;proxy_pass&lt;/code&gt; 的默认行为是把 &lt;code&gt;Host&lt;/code&gt; 设成上游地址里的主机名，也就是写 &lt;code&gt;proxy_pass http://127.0.0.1:8080&lt;/code&gt; 时，后端收到的 &lt;code&gt;Host&lt;/code&gt; 是 &lt;code&gt;127.0.0.1&lt;/code&gt;。后端如果按域名做虚拟主机路由、或者按 &lt;code&gt;Host&lt;/code&gt; 拼绝对地址，就会直接走错。显式写 &lt;code&gt;proxy_set_header Host $host&lt;/code&gt; 是在告诉 Nginx：把客户端带来的域名原样交给后端。注意 &lt;code&gt;$host&lt;/code&gt; 是小写域名且不带端口；如果后端需要带端口的原始 &lt;code&gt;Host&lt;/code&gt;，用 &lt;code&gt;$http_host&lt;/code&gt;，它保留客户端发来的完整值。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;X-Forwarded-For&lt;/code&gt; 的值 &lt;code&gt;$proxy_add_x_forwarded_for&lt;/code&gt; 是个变量：它等于客户端 IP 加上请求里已有的 &lt;code&gt;X-Forwarded-For&lt;/code&gt;。链路经过多层代理时，这个头会自然攒成一条 &lt;code&gt;IP1, IP2&lt;/code&gt; 的链，后端取第一个就是真实客户端。但这也意味着&lt;strong&gt;这个头是客户端可以伪造的&lt;/strong&gt;，后端拿它做风控之前，必须先确认请求确实经过了你自己的 Nginx，而不是客户端直连后端绕过了代理。正确的做法是后端只信任来自 Nginx 内网地址的请求里的这个头，其余一律按直连 IP 处理。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;X-Forwarded-Proto&lt;/code&gt; 管的是协议。浏览器到 Nginx 是 HTTPS，Nginx 到后端是 HTTP，后端如果只看连接协议，会以为请求是明文的，进而生成 &lt;code&gt;http://&lt;/code&gt; 的跳转链接、或者反复触发「强制 HTTPS」的重定向循环。把 &lt;code&gt;$scheme&lt;/code&gt; 传过去，后端框架大多能认这个头并据此判断原始协议，循环就断了。对应的，后端应用也要配置成信任这个头，光 Nginx 传了、后端不认，等于白传。&lt;/p&gt;
&lt;h2&gt;WebSocket：升级握手要过两道关&lt;/h2&gt;
&lt;p&gt;普通 HTTP 请求是「一问一答」，WebSocket 是「一次握手、长期双向」。Nginx 默认按 HTTP/1.0 转发上游请求、且默认不转发 &lt;code&gt;Upgrade&lt;/code&gt; 这类逐跳头，两件事都撞在 WebSocket 的握手上，所以反代 WebSocket 必须显式做三件事：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location /ws/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection &quot;upgrade&quot;;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;proxy_http_version 1.1&lt;/code&gt; 是因为 WebSocket 握手要求 HTTP/1.1，而 Nginx 默认用 HTTP/1.0 连上游；&lt;code&gt;Upgrade&lt;/code&gt; 头告诉后端「客户端想把这个连接升级成 WebSocket」，&lt;code&gt;Connection: upgrade&lt;/code&gt; 则是升级握手本身的信号。缺了任何一行，握手都会失败，浏览器控制台一般会看到 &lt;code&gt;101&lt;/code&gt; 没回来、或者连接直接断掉。&lt;/p&gt;
&lt;p&gt;还有一个超时细节：WebSocket 连接建立后可能长时间没有数据，Nginx 的 &lt;code&gt;proxy_read_timeout&lt;/code&gt; 默认 60 秒，60 秒没收到上游数据就把连接掐了。对长连接应用，这个值要按业务调大，否则聊天室、实时推送这类连接会每分钟断一次、再重连一次。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location /ws/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection &quot;upgrade&quot;;
    proxy_read_timeout 86400;
    proxy_send_timeout 86400;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;Connection&lt;/code&gt; 头这里有个小坑：Nginx 的 &lt;code&gt;proxy_set_header&lt;/code&gt; 里写 &lt;code&gt;Connection &quot;upgrade&quot;&lt;/code&gt; 是固定写法，但如果有的客户端发来的不是升级请求，这个 location 又同时处理普通 HTTP 请求，硬写 &lt;code&gt;upgrade&lt;/code&gt; 会把普通请求的 &lt;code&gt;Connection&lt;/code&gt; 也改掉。更严谨的写法是用 &lt;code&gt;map&lt;/code&gt; 按 &lt;code&gt;$http_upgrade&lt;/code&gt; 的值动态决定：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;map $http_upgrade $connection_upgrade {
    default upgrade;
    &quot;&quot;      close;
}

location /ws/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;proxy_buffering：开与关，都是取舍&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;proxy_buffering&lt;/code&gt; 默认是开的。开着的时候，Nginx 会把上游的响应先读进自己的缓冲区（内存，不够用时落到磁盘临时文件），读完再慢慢发给客户端。关掉的时候，Nginx 收到多少就立刻发给客户端多少，中间不做停留。两种模式没有对错，只有场景合不合适：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;proxy_buffering on（默认）&lt;/th&gt;
&lt;th&gt;proxy_buffering off&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;上游连接占用&lt;/td&gt;
&lt;td&gt;响应读完即释放，慢客户端不占上游&lt;/td&gt;
&lt;td&gt;客户端收完才释放，慢客户端一直占着上游&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;客户端体验&lt;/td&gt;
&lt;td&gt;首字节稍慢，整体吞吐稳定&lt;/td&gt;
&lt;td&gt;首字节快，流式内容实时到达&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;内存与磁盘&lt;/td&gt;
&lt;td&gt;大响应会占缓冲内存、甚至写临时文件&lt;/td&gt;
&lt;td&gt;几乎不占缓冲&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适用场景&lt;/td&gt;
&lt;td&gt;普通 API、页面、文件下载&lt;/td&gt;
&lt;td&gt;SSE、流式输出、超大文件直传&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;开着的好处是&lt;strong&gt;保护上游&lt;/strong&gt;：上游应用把响应交出去就能立刻去处理下一个请求，不用陪着一个慢速客户端慢慢发数据。这是反代默认开缓冲的根本原因。代价是响应要先经过 Nginx 的缓冲，首字节会慢一点，而且大响应的缓冲可能落盘，磁盘 I/O 反而成了瓶颈。相关参数可以按需调：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_buffering on;
    proxy_buffer_size 8k;
    proxy_buffers 8 16k;
    proxy_busy_buffers_size 32k;
    proxy_temp_file_write_size 32k;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;proxy_buffer_size&lt;/code&gt; 是放响应头的第一块缓冲，&lt;code&gt;proxy_buffers&lt;/code&gt; 是放响应体的缓冲池，&lt;code&gt;proxy_busy_buffers_size&lt;/code&gt; 控制可以同时发给客户端的缓冲上限。这几个值不用死记，记住原则就行：响应头特别大的应用（Cookie 多、头多）先调 &lt;code&gt;proxy_buffer_size&lt;/code&gt;；大文件下载场景关注 &lt;code&gt;proxy_temp_file_write_size&lt;/code&gt;，它决定每次往临时文件写多少。&lt;/p&gt;
&lt;p&gt;关掉缓冲的场景很明确：&lt;strong&gt;服务端推送事件（SSE）、大模型流式输出、长轮询&lt;/strong&gt;。这些场景要求上游吐一个字节、客户端立刻看到一个字节，中间插一层缓冲就等于把「实时」变成了「攒够一波再发」，用户看到的就是一卡一卡的输出。关缓冲就是一行配置，但要接受代价：上游连接会被慢客户端长时间占用，上游的并发能力要按这个重新估算。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location /stream/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 3600;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意这里顺手关了 &lt;code&gt;proxy_cache&lt;/code&gt;：流式接口本来就不该进缓存，两个开关一起关才干净。顺带一提，&lt;code&gt;proxy_buffering off&lt;/code&gt; 的时候 &lt;code&gt;proxy_cache&lt;/code&gt; 也就没意义了，因为缓存本身依赖缓冲。&lt;/p&gt;
&lt;h2&gt;upstream keepalive：别让每次请求都重新握手&lt;/h2&gt;
&lt;p&gt;没有长连接的时候，Nginx 每转发一个请求，就要和上游重新建一次 TCP 连接（HTTPS 上游还要重新握手），高并发下这笔开销非常可观。&lt;code&gt;upstream&lt;/code&gt; 块里的 &lt;code&gt;keepalive&lt;/code&gt; 就是让 Nginx 和上游之间维持一池复用的空闲连接：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;upstream backend {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;
    keepalive 32;
}

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection &quot;&quot;;
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三个点必须同时满足，缺一不可。第一，&lt;code&gt;keepalive 32&lt;/code&gt; 写在 &lt;code&gt;upstream&lt;/code&gt; 块里，数字是&lt;strong&gt;每个 worker 进程&lt;/strong&gt;保留的空闲连接数，不是总数；第二，&lt;code&gt;proxy_http_version 1.1&lt;/code&gt;，因为 HTTP/1.0 默认连接用完即关；第三，&lt;code&gt;proxy_set_header Connection &quot;&quot;;&lt;/code&gt;，把默认的 &lt;code&gt;Connection: close&lt;/code&gt; 清掉，否则 Nginx 还是会告诉上游「用完就关」。三行少一行，长连接都建不起来。&lt;/p&gt;
&lt;p&gt;keepalive 的数字不用贪大：32 对大多数单机后端绰绰有余，设得太大反而让上游维持一堆基本不用的空闲连接。上游应用如果自己有空闲连接超时（比如 Go 的 &lt;code&gt;IdleTimeout&lt;/code&gt;、Node 的 &lt;code&gt;keepAliveTimeout&lt;/code&gt;），两边的超时要对得上，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Nginx 这边保留的空闲连接不能比上游的超时时间还长&amp;lt;/span&amp;gt;，否则 Nginx 复用了一条上游已经关掉的连接，请求会失败一次再重试，用户看到的就是偶发的 502。&lt;/p&gt;
&lt;h2&gt;三个超时：connect、send、read 各管一段&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;proxy_connect_timeout&lt;/code&gt;、&lt;code&gt;proxy_send_timeout&lt;/code&gt;、&lt;code&gt;proxy_read_timeout&lt;/code&gt; 是三个不同的超时，管的是请求转发链路上的三段，默认值都是 60 秒：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_connect_timeout 5s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;proxy_connect_timeout&lt;/code&gt; 是 Nginx 与上游建立连接的等待上限。上游挂了、端口没监听、网络不通，都会在这里超时。这个值可以设得很短，5 秒足够——内网里连不上就是连不上，等 60 秒没有意义，只会拖慢失败重试。&lt;code&gt;proxy_send_timeout&lt;/code&gt; 是 Nginx 把请求体发给上游的时限，上传大文件、客户端网络慢的时候会撞到它。&lt;code&gt;proxy_read_timeout&lt;/code&gt; 是两次从上游读到数据之间的间隔上限，不是整个响应的总时长；上游处理慢、每隔一段时间吐一点数据，只要间隔不超过这个值就不会断。&lt;/p&gt;
&lt;p&gt;三者调参的思路也不一样：&lt;code&gt;connect&lt;/code&gt; 按「内网建连应该多快」设短一点；&lt;code&gt;send&lt;/code&gt; 按「上传场景」设；&lt;code&gt;read&lt;/code&gt; 按「上游最慢接口的响应时间」设。反代 SSE、WebSocket、大文件上传这类长耗时场景，&lt;code&gt;read&lt;/code&gt; 和 &lt;code&gt;send&lt;/code&gt; 要按业务单独放宽，别在全局一刀切——全局放宽等于把所有接口的故障发现时间都拉长了。&lt;/p&gt;
&lt;h2&gt;排障：反代出问题，先按这个顺序查&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;后端报 404，但直连后端是好的。&lt;/strong&gt; 先查 &lt;code&gt;proxy_pass&lt;/code&gt; 的斜杠。直连用的路径和经 Nginx 的路径不一致，九成是斜杠规则理解反了：想剥前缀却没加斜杠，或者加了斜杠却不知道它剥掉了 location 前缀。用 &lt;code&gt;curl&lt;/code&gt; 分别请求直连地址和经 Nginx 的地址，对照后端日志里收到的实际 URI，差的那一段就是斜杠吃掉或多带的部分。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;WebSocket 连不上，普通接口正常。&lt;/strong&gt; 按顺序查三行：&lt;code&gt;proxy_http_version 1.1&lt;/code&gt; 写了没有、&lt;code&gt;Upgrade&lt;/code&gt; 头传了没有、&lt;code&gt;Connection&lt;/code&gt; 是不是 &lt;code&gt;upgrade&lt;/code&gt;。三行都在还失败，看浏览器开发者工具的网络面板：握手请求返回的不是 &lt;code&gt;101 Switching Protocols&lt;/code&gt;，而是 &lt;code&gt;400&lt;/code&gt; 或 &lt;code&gt;502&lt;/code&gt;，说明后端根本没认出这是升级请求，多半是头没传过去。长连接每分钟断一次则是 &lt;code&gt;proxy_read_timeout&lt;/code&gt; 没放宽。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;后端日志里所有请求的 IP 都是 Nginx 的地址。&lt;/strong&gt; &lt;code&gt;proxy_set_header X-Real-IP&lt;/code&gt; 或 &lt;code&gt;X-Forwarded-For&lt;/code&gt; 没配，或者配了但后端应用没开启「信任代理头」的选项。两边要同时对上：Nginx 传头、后端认头。还要确认请求确实经过了 Nginx——客户端如果能直连后端，绕过代理的请求自然没有任何代理头。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;SSE 或流式输出一卡一卡、半天才吐一段。&lt;/strong&gt; &lt;code&gt;proxy_buffering&lt;/code&gt; 还开着。流式接口的 location 里显式写 &lt;code&gt;proxy_buffering off&lt;/code&gt;，同时确认没有缓存配置在起作用。改完用 &lt;code&gt;curl -N&lt;/code&gt; 直接看流式输出是不是逐行到达，别只看浏览器表现，浏览器自己的缓冲也会干扰判断。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;偶发 502，刷新一下又好了。&lt;/strong&gt; 先看错误日志里 502 那一刻的 &lt;code&gt;upstream_status&lt;/code&gt; 和 &lt;code&gt;upstream_response_time&lt;/code&gt;：如果是上游连接被重置，大概率是 keepalive 空闲连接超时没对齐——Nginx 复用了上游已经关闭的连接。把 Nginx 的 keepalive 空闲时间调得比上游的短，或者把 &lt;code&gt;keepalive&lt;/code&gt; 数字调小，都能缓解；根治是两边超时对齐。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;响应特别慢，但上游处理其实很快。&lt;/strong&gt; 用 &lt;code&gt;$request_time&lt;/code&gt; 和 &lt;code&gt;$upstream_response_time&lt;/code&gt; 对照（这两变量的用法本系列第 8 篇日志篇会细讲）：如果 &lt;code&gt;request_time&lt;/code&gt; 远大于 &lt;code&gt;upstream_response_time&lt;/code&gt;，慢在 Nginx 到客户端这一段，查缓冲和客户端网络；如果两者都大，慢在上游本身。这两个时间戳是定位反代性能问题的第一手证据，别凭感觉猜。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;反向代理的配置量不大，但每个指令背后都是一条明确的行为规则：&lt;code&gt;proxy_pass&lt;/code&gt; 的斜杠决定后端收到什么路径，四个头决定后端看到谁在访问、&lt;code&gt;WebSocket&lt;/code&gt; 的三行决定握手能不能升级、&lt;code&gt;proxy_buffering&lt;/code&gt; 的开关决定响应是先攒后发还是随到随发、&lt;code&gt;keepalive&lt;/code&gt; 的三行决定上游连接复不复用、三个超时决定每一阶段等多久。配反代的时候别凭「看起来差不多」下手，改完用 &lt;code&gt;curl&lt;/code&gt; 对照直连和经代理的两端表现，再看一眼错误日志——这套验证习惯，比多背十条配置更管用。下一篇讲负载均衡：多个上游时 Nginx 怎么调度、怎么把挂掉的节点摘出去。&lt;/p&gt;
&lt;p&gt;:::warning
本文涉及的 &lt;code&gt;proxy_read_timeout&lt;/code&gt;、&lt;code&gt;proxy_buffering&lt;/code&gt; 等参数都是按 location 生效的，调参只动对应的 location，别在 &lt;code&gt;http&lt;/code&gt; 块里全局放宽超时——全局放宽会让所有接口的故障发现时间一起变长，慢接口的问题会被掩盖成「偶尔慢」，排障更难。
:::&lt;/p&gt;
</content:encoded></item><item><title>ECC：给 AI 编程代理装上一套工程操作系统</title><link>https://www.anexns.cloudns.org/posts/ai-ecc/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-ecc/</guid><description>把规划、测试、审查、记忆和安全扫描打包成可安装的技能与运行时，让 Claude Code、Codex、OpenCode 等编程代理按工程流程干活。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;用 AI 编程代理写代码的人，多半都经历过这种场面：需求刚说完，它已经噼里啪啦写了三百行；你问它为什么这么设计，它答不上来；构建挂了，它改一处坏两处；好不容易调通，第二天新开一个会话，它把昨天的教训忘得一干二净。模型本身不笨，缺的是流程——没有规划环节，没有验证习惯，没有记忆沉淀，更没有安全边界。ECC（Everything Claude Code 生态的通用版）想补的正是这一层：它自称是「The agent harness performance optimization system」，给 AI 编程代理用的工程操作系统，把技能、本能、记忆、安全扫描和研究优先的开发流程打包成一套可安装、可维护的运行时，覆盖 Claude Code、Codex、OpenCode、Cursor 等多个 harness（代理宿主环境）。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/affaan-m/ECC&lt;/p&gt;
&lt;p&gt;这个仓库 2026 年 1 月 18 日创建，不到一年时间攒下约 30.4 万星、4.47 万 fork，MIT 许可，当前发布版 2.2.3（2026 年 10 月 1 日），官网是 ecc.tools。它的工作环只有七步：plan → test → implement → review → verify → remember → improve，规划、测试、实现、审查、验证、记住、改进。理念浓缩成一句话：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Optimize the context window. Persist everything else.&amp;lt;/span&amp;gt;——上下文窗口只留当下最要紧的东西，其余一切都持久化下来。这篇文章把它的内容构成、安装方式、日常工作流和几条必须守住的纪律一次讲清。&lt;/p&gt;
&lt;h2&gt;为什么裸用编程代理总出问题&lt;/h2&gt;
&lt;p&gt;先把痛点摆明白，才能理解 ECC 的每个组件是在治什么病。&lt;/p&gt;
&lt;p&gt;第一是不规划。裸用的代理接到需求就直接写代码，方案没过脑子，边界条件、数据结构、影响面全靠写的时候现想，写错方向了就整段返工。第二是不验证。代码写完就算交付，测试不跑、构建不看、安全问题更没人管，等 CI 红了或者上线炸了才回头补。第三是不记事。会话一关，上下文清零：这个项目用什么测试框架、上次踩过什么坑、你纠正过它哪些习惯，统统归零，下次还得从头教一遍。&lt;/p&gt;
&lt;p&gt;ECC 的应对是把「好工程师的工作习惯」拆成可执行的结构：规划有专门的规划代理和 plan 命令，验证有 TDD 技能和审查命令，记忆有 hooks 驱动的会话摘要、持续学习和 instincts（本能）机制，安全有内置扫描器。关于技能这个概念本身，之前拆箱过一个技能存档仓库（/posts/ai-museai-skills/），那边是把技能文档当资料存档来读；ECC 不一样，它是&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;可以直接安装进你的代理环境、当场跑起来的技能系统&amp;lt;/span&amp;gt;，一个偏收藏，一个偏实战。&lt;/p&gt;
&lt;h2&gt;内容清单：六大件各管什么&lt;/h2&gt;
&lt;p&gt;ECC 不是一个大提示词文件，而是一组分工明确的部件。先看全貌：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;部件&lt;/th&gt;
&lt;th&gt;规模&lt;/th&gt;
&lt;th&gt;管什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Agents（代理）&lt;/td&gt;
&lt;td&gt;71 个&lt;/td&gt;
&lt;td&gt;规划、审查、构建修复、安全、架构与领域工作的专职代理，各自带明确职责&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Skills（技能）&lt;/td&gt;
&lt;td&gt;314 个&lt;/td&gt;
&lt;td&gt;TDD、研究、安全、文档、前端、数据、机器学习、运维等可复用的工作方法&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Commands（命令）&lt;/td&gt;
&lt;td&gt;98 个 legacy command shims&lt;/td&gt;
&lt;td&gt;兼容旧版命令入口的垫片，让老用法平滑过渡到新体系&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Hooks 与 Memory 运行时&lt;/td&gt;
&lt;td&gt;一套&lt;/td&gt;
&lt;td&gt;会话摘要、持续学习、instincts 本能、上下文控制，负责「记住」这一环&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Rules（规则）&lt;/td&gt;
&lt;td&gt;按需选取&lt;/td&gt;
&lt;td&gt;按语言、按项目选择的常驻规范，让代理在特定代码库里守规矩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;AgentShield&lt;/td&gt;
&lt;td&gt;内置&lt;/td&gt;
&lt;td&gt;安全扫描器，扫描 prompts、hooks、MCP 配置、权限、密钥与代理文件&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个部件值得多说两句。Agents 是「专职的人」：写功能之前先让规划代理出方案，写完之后让审查代理在新上下文里挑毛病，构建挂了交给构建修复代理，职责分开是为了避免一个代理既当运动员又当裁判。Skills 是「成文的方法」：比如 tdd-workflow 技能会强制代理先写测试再写实现，而不是嘴上答应心里跳过。Instincts（本能）是记忆运行时里比较有意思的一层：代理在长期使用中沉淀下来的行为倾向会被记录、复用，相当于把「这个项目里我们习惯这么干」固化下来，而不是每次靠你在提示词里重复叮嘱。&lt;/p&gt;
&lt;p&gt;Rules 和 AgentShield 是一对搭档：Rules 决定代理平时守什么规矩，AgentShield 负责定期体检——它扫的不是你的业务代码，而是代理环境本身：提示词文件、hooks 脚本、MCP 配置、权限设置、有没有密钥明文躺在代理文件里。代理工具链越强大，它自己的配置面就越值得扫一遍。&lt;/p&gt;
&lt;p&gt;记忆运行时值得单独展开，因为「不记事」是裸用代理最伤效率的毛病，而它恰好是 ECC 区别于普通技能包的地方。这套运行时由四部分组成：会话摘要在会话结束时把关键结论、未完成事项和踩过的坑压缩存档，下次开工不用从零交代背景；持续学习把多次会话里反复出现的模式沉淀下来，而不是只记住孤立的一次；instincts 本能层存的是行为倾向——比如「这个仓库的提交信息要用英文」「改接口之前先全局搜调用方」，这类习惯不必每次写进提示词；上下文控制则负责在窗口吃紧时决定什么留下、什么归档，呼应它那句理念：窗口只留当下要紧的，其余全部持久化。研究优先也是这套流程的一部分：动手之前先让代理查文档、看现有实现、摸清代码库的既有约定，再进入规划，而不是凭训练记忆里的印象直接开写——印象会过期，仓库里的代码不会骗人。&lt;/p&gt;
&lt;h2&gt;平台支持：先看清哪端是全功能&lt;/h2&gt;
&lt;p&gt;ECC 覆盖多个 harness，但各端能力并不对等，动手之前先对号入座：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Claude Code&lt;/strong&gt;：支持最完整，原生插件 slug 是 &lt;code&gt;ecc@ecc&lt;/code&gt;，下文的安装与命令都以它为主线。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Codex、Qoder&lt;/strong&gt;：有原生插件路径，体验接近完整版。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cursor、OpenCode、Gemini、Zed、GitHub Copilot、Antigravity、Qwen、Kimi Code 等&lt;/strong&gt;：走能力受限的适配器，能用核心技能与流程，但功能不完全对等，具体差异看官方支持矩阵，别默认每个命令在每个端都存在。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这一点也影响选型预期：如果你主力是 Claude Code，ECC 基本是全量体验；如果主力在适配器名单里，先查矩阵确认你想要的那几个技能在不在，再决定投入多少配置时间。本站之前介绍过几款终端里的 AI 编程助手（/posts/ai-cli-assistants/），ECC 和它们的关系是互补的——那些是代理本体，ECC 是装在代理之上的流程层。&lt;/p&gt;
&lt;p&gt;换个角度看，这种「一个流程层、多个宿主」的结构也是它生态长得快的原因：技能、规则和记忆格式是宿主无关的，换代理不用把积累的工作方法推倒重来；各端的差异被收敛在适配器和插件里，官方支持矩阵把哪端缺什么写得明明白白，不靠用户自己踩坑去发现。对同时用两三个代理的人来说，这比每个端各维护一份提示词文件现实得多。&lt;/p&gt;
&lt;h2&gt;安装：只选一条路径&lt;/h2&gt;
&lt;h3&gt;前置要求&lt;/h3&gt;
&lt;p&gt;通用安装包需要 Node.js 18 或更高版本。走 Claude Code 插件路径的话，还要保证 Git 和 Claude Code 2.1+ 都在 PATH 里能直接调用。先自查一遍：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;node --version    # 需要 18+
git --version
claude --version  # 插件路径需要 2.1+
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;引导式安装（推荐）&lt;/h3&gt;
&lt;p&gt;官方推荐的是引导式安装，一条命令起步：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx ecc-universal@2.2.3 setup
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Windows 在 PowerShell 里跑同一条命令即可；习惯 pnpm 的用 &lt;code&gt;pnpm dlx ecc-universal@2.2.3 setup&lt;/code&gt;，用 bun 的换成 &lt;code&gt;bunx ecc-universal@2.2.3 setup&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;向导的流程是先盘点：它会检查官方 marketplace 和本机各个可安装范围的现状，然后让你做两道选择题——安装范围（个人使用典型选 Global user，即全局用户级）和 hooks 档位（选 Standard 标准档）。选完才真正落盘。装完之后新开一个会话，验证插件已启用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/plugin list
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;列表里能看到 &lt;code&gt;ecc@ecc&lt;/code&gt; 处于启用状态，安装就算成功。&lt;/p&gt;
&lt;h3&gt;多代理一次配置&lt;/h3&gt;
&lt;p&gt;手上有好几个代理要一起配，用带引导的批量安装：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx ecc-universal@2.2.3 install --guided
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Claude Code、Codex、Kimi Code 可以任意组合勾选。它的稳妥之处在于：所有目标在写入之前全部先预检一遍，最后统一让你确认一次，没问题才落盘，不会装一半发现某个端缺前置条件。&lt;/p&gt;
&lt;h3&gt;一条铁律&lt;/h3&gt;
&lt;p&gt;:::warning
每种 harness 只选一条安装路径。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把完整手动安装叠在插件安装之上&amp;lt;/span&amp;gt;，两套机制管同一批文件，必然互相打架。先想清楚走插件还是走手动，选定之后就只维护这一条。
:::&lt;/p&gt;
&lt;h2&gt;上手工作流：三条线&lt;/h2&gt;
&lt;p&gt;装好之后，日常使用围绕三条线展开。注意命令命名：插件版带 &lt;code&gt;/ecc:&lt;/code&gt; 前缀，手动安装的是短名，下面以插件版为主写法。&lt;/p&gt;
&lt;h3&gt;做新功能：先规划，后动手&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;/ecc:plan &quot;给订单模块加一个按状态筛选的接口&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;plan 命令会让规划代理先产出方案：改哪些文件、接口长什么样、测试怎么写，你确认之后再进入实现。实现阶段挂上 tdd-workflow 技能，它强制先写测试、看着测试失败、再写实现让它变绿。写完想复查，另开一个新上下文做审查：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/code-review
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;强调「新上下文」是因为审查者不该带着实现者的思路惯性，换一个干净视角更容易挑出真问题。&lt;/p&gt;
&lt;h3&gt;修 bug：先复现，再修&lt;/h3&gt;
&lt;p&gt;ECC 里修 bug 的标准姿势只有一条：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;先写一个能复现问题的失败测试，再动手修&amp;lt;/span&amp;gt;。没有复现测试就直接改代码，改完你无法证明问题真的没了，也无法防止它下周复发。构建层面的报错则交给专门命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/build-fix
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它负责定位构建失败、最小化修复，而不是顺手把半个模块重写一遍。&lt;/p&gt;
&lt;h3&gt;上线前：安全与上下文检查&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;/security-scan
/context-budget
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;前者跑安全审查（底层就是 AgentShield 那套扫描逻辑，重点看提示词、hooks、MCP 配置、权限和密钥），后者查当前上下文的占用压力——上下文快爆的时候先做摘要和裁剪，而不是硬塞到模型开始胡言乱语。会话层面的两个命令也建议养成习惯：收工时 &lt;code&gt;/save-session&lt;/code&gt; 存档，下次 &lt;code&gt;/resume-session&lt;/code&gt; 恢复；长期项目里用 &lt;code&gt;/learn-eval&lt;/code&gt; 把这次会话里值得留下的经验沉淀进学习系统，喂给 remember 和 improve 两环。&lt;/p&gt;
&lt;p&gt;技能不够用、想自己造或改造技能的，可以配合技能构建类工具一起看（/posts/ai-skill-seekers/）；想先横向了解各家编程助手分工的，另有一篇编程助手综述（/posts/ai-coding-assistants/）可对照。&lt;/p&gt;
&lt;h2&gt;纪律一：hooks 不要重复装&lt;/h2&gt;
&lt;p&gt;这是插件用户最容易踩的坑。插件安装完成后，Claude Code 2.1+ 会自动加载插件自带的 &lt;code&gt;hooks/hooks.json&lt;/code&gt;，hooks 已经生效了。有些人照着旧教程，又把同一批 hooks 手工复制进 &lt;code&gt;~/.claude/settings.json&lt;/code&gt;，结果是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;同一批 hooks 被执行两遍，还会引发跨平台冲突&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;:::warning
插件路径下，hooks 以插件自带的为准，&lt;code&gt;~/.claude/settings.json&lt;/code&gt; 里不要再出现 ECC 的同名 hooks。发现会话摘要生成两份、某个 hook 报错两次，先查这里。
:::&lt;/p&gt;
&lt;h2&gt;纪律二：MCP 不要默认全开&lt;/h2&gt;
&lt;p&gt;插件安装默认不自动启用 ECC 自带的 MCP 定义，这是刻意的克制。ECC 只带一个默认连接器 chrome-devtools，其余所谓 MCP 能力，要么是技能包装的 CLI/REST 调用，要么是可选目录项，需要你自己点头才装。&lt;/p&gt;
&lt;p&gt;如果你已经自备了同款 MCP，不想让 ECC 再碰它，可以在安装或同步时排除：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ECC_DISABLED_MCPS=&quot;chrome-devtools&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把这个环境变量设好，安装和同步流程就会跳过 chrome-devtools。反过来，想给某个项目单独加 MCP 定义时，去仓库的 &lt;code&gt;mcp-configs/mcp-servers.json&lt;/code&gt; 里挑需要的条目，复制到项目级的 &lt;code&gt;.mcp.json&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;mcpServers&quot;: {
    &quot;example&quot;: {
      &quot;command&quot;: &quot;npx&quot;,
      &quot;args&quot;: [&quot;-y&quot;, &quot;example-mcp-server&quot;],
      &quot;env&quot;: { &quot;EXAMPLE_API_KEY&quot;: &quot;YOUR_API_KEY_HERE&quot; }
    }
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意定义里的 &lt;code&gt;YOUR_*_HERE&lt;/code&gt; 全是占位符，必须换成你自己的密钥再保存，原样提交进仓库等于把假钥匙和真配置一起公开示众。&lt;/p&gt;
&lt;h2&gt;维护与卸载&lt;/h2&gt;
&lt;p&gt;日常维护用同一套 CLI 入口，先看装了什么、再体检、再修复：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx ecc-universal@2.2.3 list-installed   # 列出受管的已安装内容
npx ecc-universal@2.2.3 doctor           # 体检：版本、前置、配置一致性
npx ecc-universal@2.2.3 repair           # 按体检结果修复
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;卸载分两步，先预演再真删：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx ecc-universal@2.2.3 uninstall --dry-run   # 只列出将删的文件，不动手
npx ecc-universal@2.2.3 uninstall             # 确认无误后执行
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;卸载只删它自己记录在案的受管文件，harness 目录里的无关文件不会动，这也是为什么 dry-run 值得每次都跑——清单对得上，才说明受管状态是干净的。&lt;/p&gt;
&lt;p&gt;如果你早期不懂纪律、叠装过多种方式，清理顺序是固定的：先移除 Claude Code 插件，再到装有受管状态的项目目录里跑 uninstall，然后删掉手工复制的 rules 文件夹，最后只选一条路径重新安装。顺序反了容易出现插件删了但手动文件还在、或者状态文件找不到主人的半吊子局面。&lt;/p&gt;
&lt;h2&gt;自托管模型：通道自己说了算&lt;/h2&gt;
&lt;p&gt;ECC 不写死 Anthropic 官方通道。harness 能连上的接口它都能用：官方接口、兼容网关、自托管模型都行。Claude Code 侧的示例是把通道指向自己的网关：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;export ANTHROPIC_BASE_URL=&quot;https://你的网关地址&quot;
export ANTHROPIC_AUTH_TOKEN=&quot;你的令牌&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;模型名映射在 Claude Code 里配，不在 ECC 里配——ECC 只管流程层，谁来当模型、模型名怎么对应，是宿主环境的职责。这个边界划得清楚，对已经有自建网关的人很友好，不用为了用一套流程被迫换通道。&lt;/p&gt;
&lt;h2&gt;安全提醒：只认官方渠道&lt;/h2&gt;
&lt;p&gt;:::warning
ECC 只从官方渠道安装：GitHub 仓库、npm 上的 &lt;code&gt;ecc-universal&lt;/code&gt; 与 &lt;code&gt;ecc-agentshield&lt;/code&gt;、官方 GitHub App、插件 slug &lt;code&gt;ecc@ecc&lt;/code&gt;、官网 ecc.tools。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;第三方重传与镜像未经维护者审核，可能夹带恶意代码&amp;lt;/span&amp;gt;——给代理装的东西权限极大，能读代码、能跑命令，来源这关没有将就的余地。
:::&lt;/p&gt;
&lt;p&gt;另外别把 ECC Pro 和开源版混为一谈：ECC Pro 是面向私有仓库的托管 GitHub App，付费产品；开源仓库本身是 MIT 许可、永久免费。你在 GitHub 上装到的这套东西，不存在「试用期到了要付费」这回事。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. hooks 重复执行（摘要生成两份、hook 报错成双）&lt;/strong&gt;
多半是插件 hooks 和手工复制进 &lt;code&gt;~/.claude/settings.json&lt;/code&gt; 的 hooks 撞车。删掉 settings 里手工加的那一份，只保留插件自带加载，重启会话验证。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 插件命令找不到（输入 /ecc:plan 没反应）&lt;/strong&gt;
先跑 &lt;code&gt;/plugin list&lt;/code&gt; 确认 &lt;code&gt;ecc@ecc&lt;/code&gt; 在列表里且已启用；不在就检查前置：Git 与 Claude Code 2.1+ 是否在 PATH 中，然后重跑引导安装。再确认自己装的是插件版还是手动版——手动版命令是短名，没有 &lt;code&gt;/ecc:&lt;/code&gt; 前缀，两种写法混用是新手期最高频的乌龙。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 和自备 MCP 重复（同名连接器出现两套）&lt;/strong&gt;
给安装/同步流程设置 &lt;code&gt;ECC_DISABLED_MCPS=&quot;chrome-devtools&quot;&lt;/code&gt;（或把你要排除的名字填进去），让 ECC 跳过自带定义；同时检查项目 &lt;code&gt;.mcp.json&lt;/code&gt; 里有没有从官方目录复制后忘了删的重复条目，一处定义只留一份。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 装过多种方式、状态混乱&lt;/strong&gt;
不要逐个文件猜着删。按固定顺序来：移除 Claude Code 插件 → 在有受管状态的项目目录跑 &lt;code&gt;uninstall&lt;/code&gt;（先 &lt;code&gt;--dry-run&lt;/code&gt; 看清单）→ 删手工复制的 rules 文件夹 → 只选一条路径重装。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;ECC 的价值不在某个单独的技能或命令，而在于它把 plan → test → implement → review → verify → remember → improve 这条工作环做成了可安装、可维护的运行时：71 个专职代理分工，314 个技能沉淀方法，hooks 与记忆系统负责不忘事，AgentShield 守住代理环境自身的安全。用好它的前提是三条纪律：每种 harness 只选一条安装路径，hooks 不重复装，MCP 不默认全开。把这三条守住，再让它陪你跑几个真实项目，那种「代理终于像个靠谱同事」的感觉，大概就是这 30 多万颗星的来历。&lt;/p&gt;
</content:encoded></item><item><title>Jailbreaks 拆箱：一个收录了 32 个模型「越狱提示词」的仓库</title><link>https://www.anexns.cloudns.org/posts/ai-jailbreaks/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-jailbreaks/</guid><description>togg53192-cmd/jailbreaks 把针对 Claude、Gemini、Grok、DeepSeek、GLM、Kimi、Qwen 等 26 多个模型的系统提示词、人格锁定与 AGENTS.md 文件打包成一个合集，是观察指令层级与人格框架如何影响模型行为的一份现成标本。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;给模型换一套「出厂规则」，需要多长的提示词？这个仓库给出的答案是：一整个文件。有人把针对各家大模型的越狱提示词——系统提示词、人格锁定、工作区策略、AGENTS.md——系统地收集、分类、版本化，做成了一个开箱即用的合集。它不是某个工具的说明书，更像一份提示词考古档案：想研究「指令怎么写才能压过模型默认行为」，这里是现成的标本库。本文把它拆开看看：里面有什么、四种投放方式怎么用、以及用之前必须知道的时效与合规边界。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/togg53192-cmd/jailbreaks&lt;/p&gt;
&lt;h2&gt;先看清这是什么&lt;/h2&gt;
&lt;p&gt;仓库名就叫 jailbreaks，直译是「越狱合集」。所谓越狱提示词，指的是用一段预先写好的长文本去覆盖或重塑模型的行为框架：换人格、换规则、换拒答边界。仓库的自我定位写得很清楚：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;一个收集系统提示词、人格锁定、工作区策略与 Agent 操作规范的合集&amp;lt;/span&amp;gt;，面向前沿闭源模型、开源权重模型与一批免费「潜行」模型。&lt;/p&gt;
&lt;p&gt;几个关键数据（2026 年 11 月查于仓库主页）：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;项目&lt;/th&gt;
&lt;th&gt;数据&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Star&lt;/td&gt;
&lt;td&gt;约 17.5k&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Fork&lt;/td&gt;
&lt;td&gt;约 3.0k&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;建仓时间&lt;/td&gt;
&lt;td&gt;2026 年 6 月&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;提交数&lt;/td&gt;
&lt;td&gt;150&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;提示词文件&lt;/td&gt;
&lt;td&gt;32 个&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;覆盖模型&lt;/td&gt;
&lt;td&gt;26 个以上&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;作者在 README 里坦承自己 15 岁，靠他人赞助的 200 美元 OpenRouter 额度完成测试，额度耗尽后正在求支持。这批文件的质量参差与更新节奏，要放在这个背景下看：它是个热度极高的个人项目，不是机构出品。&lt;/p&gt;
&lt;h2&gt;合集里都有什么&lt;/h2&gt;
&lt;p&gt;文件按厂商分目录存放，每个文件都是一份完整全文，拿来就能粘贴，没有摘要和节选。主要板块如下：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;板块&lt;/th&gt;
&lt;th&gt;代表文件&lt;/th&gt;
&lt;th&gt;形式&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;OpenCode Zen 免费模型&lt;/td&gt;
&lt;td&gt;Big Pickle、Space Bunny、MiMo V2.6、Muse Spark 1.3&lt;/td&gt;
&lt;td&gt;人格锁定 / 操作规范&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Anthropic&lt;/td&gt;
&lt;td&gt;Opus v1/v2、Sonnet v1/v2&lt;/td&gt;
&lt;td&gt;人格框架&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;智谱 GLM&lt;/td&gt;
&lt;td&gt;GLM-5.2、GLM ZCode 5.2/5.3、GLM-5.3 Flash&lt;/td&gt;
&lt;td&gt;系统提示词 / AGENTS.md&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;DeepSeek&lt;/td&gt;
&lt;td&gt;V3、V4、4.1&lt;/td&gt;
&lt;td&gt;系统提示词 / 操作规范&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Moonshot Kimi&lt;/td&gt;
&lt;td&gt;K2、K3、K3.1&lt;/td&gt;
&lt;td&gt;系统提示词 / 工作区档案&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;xAI&lt;/td&gt;
&lt;td&gt;Grok Build、Grok 4.7、Grok Config&lt;/td&gt;
&lt;td&gt;操作指令 / 配置块&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Google&lt;/td&gt;
&lt;td&gt;Gemma 4、Gemini 4 Argon、Gemini 3.1 Pro&lt;/td&gt;
&lt;td&gt;Modelfile / 系统提示词&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;其他&lt;/td&gt;
&lt;td&gt;Mistral Large 4、Qwen 3.7/3.8、Nemotron 3 Ultra、GPT-OSS 20B&lt;/td&gt;
&lt;td&gt;系统提示词 / Modelfile&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;值得注意的是它的分类方式：不是按「能绕过什么」分，而是按投放面分。这正好对应了上一篇提示词工程里讲的指令层级问题（可参看 &lt;a href=&quot;/posts/ai-prompt-engineering/&quot;&gt;提示词工程&lt;/a&gt;）——同一套「改规则」的目标，落在系统提示词、项目指令文件、工作区策略和模型打包文件上，是四种完全不同的打法。&lt;/p&gt;
&lt;h2&gt;仓库的组织方式&lt;/h2&gt;
&lt;p&gt;合集类仓库最容易死在混乱上，这个仓库在组织上下了功夫，值得单独说说。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;目录按厂商分，文件按模型分。&lt;/strong&gt; 根目录是 Anthropic、Google、DeepSeek、Moonshot AI、xAI、Zhipu AI、Alibaba、Tencent、Xiaomi、Meituan、StepFun、Mistral、Meta 等厂商文件夹，外加几个贡献者的个人目录。找某个模型的提示词，路径基本可以猜出来。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;贡献规范意外地严格。&lt;/strong&gt; 仓库对新文件的提交定了五条规矩：一文件一提示词；必须给完整全文，不许节选和摘要；必须标明投放面（系统提示词、AGENTS.md、Modelfile 还是配置槽位）；大改动必须升版本号另存新文件，不许静默覆盖旧版；不许声称没有实测过的兼容性。对一个个人维护的合集来说，这套规范是它能在一百多次提交后还保持可用的主要原因——尤其是「升版另存」一条，让失效追溯成为可能：新版不行，还能退回旧版对照。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;热度来源。&lt;/strong&gt; 仓库上过 GitHub Trending 日榜，README 顶部挂着 Star History 的排名徽章。1.7 万星对一个纯文本合集来说是很高的数字，侧面说明「想给模型换套规则」是多么普遍的需求。&lt;/p&gt;
&lt;h2&gt;四种投放方式&lt;/h2&gt;
&lt;h3&gt;系统提示词：直接粘贴&lt;/h3&gt;
&lt;p&gt;最简单的一种。把目标文件全文复制到客户端或 API 支持的系统提示词字段里：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;调用方式示意（以 API 为例）：
system 字段 ← 粘贴文件全文
user 字段   ← 正常提问
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;支持自定义指令的聊天客户端、API 的 system 消息、各类 Agent 框架的系统提示词配置，都属于这一路。实际投放点比想象中多：聊天客户端的「自定义指令 / 角色设定」输入框、API 请求里的 system 角色消息、本地推理框架（如 Ollama、LM Studio）的系统提示词预设，都吃这一套。区别只在长度上限和优先级——API 的 system 消息通常权重最高，聊天客户端的自定义指令次之，塞进普通对话第一句的权重最低，也最容易被后续对话稀释。&lt;/p&gt;
&lt;h3&gt;AGENTS.md：放进项目根目录&lt;/h3&gt;
&lt;p&gt;文件名直接就叫 &lt;code&gt;AGENTS.md&lt;/code&gt; 的那批，是给编程 Agent 准备的项目级指令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 保存到目标仓库根目录
cp glm-zcode-5.3-AGENTS.md /path/to/your-repo/AGENTS.md
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;编程 Agent 启动时会读取项目根目录的 AGENTS.md 作为常驻指令。这类文件的写法和 &lt;a href=&quot;/posts/ai-museai-skills/&quot;&gt;MuseAI-Skills 存档&lt;/a&gt;里那些技能与运行环境文件是同一个生态位：不改模型，改的是 Agent 的工作规程。&lt;/p&gt;
&lt;h3&gt;工作区策略：全局指令位&lt;/h3&gt;
&lt;p&gt;标注为「操作规范」「工作区档案」的文件，面向支持持久全局指令的环境。以 OpenCode 为例，它的全局指令文件位于：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;~/.config/opencode/AGENTS.md
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把文件内容放进去，对这台机器上所有会话生效。这也是为什么这类文件普遍写得最长、最像「规章制度」——它们要管的不只是一次对话，而是整个工作区的默认行为。这与 &lt;a href=&quot;/posts/ai-ecc/&quot;&gt;ECC&lt;/a&gt; 那种给编程代理装工程操作系统的思路正好是镜像：一个在加流程，一个在换规则。&lt;/p&gt;
&lt;h3&gt;Ollama Modelfile：打包成本地模型&lt;/h3&gt;
&lt;p&gt;针对本地部署的文件是 Ollama 的 Modelfile 格式（&lt;code&gt;FROM&lt;/code&gt; + &lt;code&gt;SYSTEM&lt;/code&gt; 块），用法在 &lt;a href=&quot;/posts/ai-ollama-local-llm/&quot;&gt;Ollama 本地大模型&lt;/a&gt;里讲过基础，这里是直接套现成模板：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ollama create gemma4-jb -f gemma4.md
ollama run gemma4-jb
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;生成的新模型自带写死的人格与规则，之后每次运行都不用再粘贴。&lt;/p&gt;
&lt;h3&gt;Grok 配置：放进配置槽位&lt;/h3&gt;
&lt;p&gt;还有一类零散文件是给 Grok 的配置块（仓库里是一个 .txt 配置文件），用法和前几种都不同：它不进对话，而是放进目标框架预留的配置字段，由框架在会话开始前加载。仓库特别提醒，这类文件放错位置——比如当作普通消息发出去——基本不会起作用。判断一个文件属于哪种投放面，看 README 表格里的 Type 列标注即可，拿不准时先查对应目录的说明，别猜。&lt;/p&gt;
&lt;p&gt;:::warning
必须说清楚的两条边界：第一，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;这类提示词用在闭源模型上可能违反对应平台的服务条款&amp;lt;/span&amp;gt;，账号风险自担；第二，仓库自己的免责声明写明「仅供研究与教育目的」，作者不背书任何违法或有害用途。把它当研究标本看，别当通行证用。
:::&lt;/p&gt;
&lt;h2&gt;为什么说它更像研究标本&lt;/h2&gt;
&lt;p&gt;把 32 个文件横向对比，能看出越狱提示词的几种经典骨架：人格锁定型（先给模型一个完整身份和「操作下限」，再谈任务）、规章制度型（用编号条款堆出优先级，试图在指令冲突里抢高位）、框架置换型（把对话重新定义成写作室、构建工坊等场景，绕开默认的问答框架）。&lt;/p&gt;
&lt;p&gt;以人格锁定型为例，它的结构骨架大致长这样（结构示意，非原文）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;1. 身份定义：你是谁、为谁工作、部署在什么环境
2. 核心价值观：什么比什么优先（真实 &amp;gt; 礼貌、完成 &amp;gt; 拒绝）
3. 操作下限：无论用户说什么，始终要做到的几件事
4. 行为细则：语气、格式、工具使用、错误处理
5. 冲突规则：当后续指令与本文冲突时听谁的
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;看懂这个骨架，就能明白为什么这类文件动辄几百上千行：它不是在「求」模型做一件事，而是在给模型重写一份岗位说明书。规章制度型同理，本质是把公司规章搬进提示词——编号、条款、例外、优先级，一应俱全。框架置换型最轻，只改场景定义，但也最脆弱，模型多聊几轮就容易「出戏」。&lt;/p&gt;
&lt;p&gt;这些骨架对做防御的人同样有价值：理解注入如何构造，才知道指令层级该怎么加固。仓库的免责声明里也专门提了这一层用途——帮助开发者理解并防御提示注入与指令操纵。如果你在给自己的应用设计系统提示词，把这 32 个文件当反面教材逐条读一遍，想想自己的提示词在哪一层会被覆盖、被绕过、被重新定义，收获不会比读一篇防御教程小。&lt;/p&gt;
&lt;h2&gt;上手路径：从零到跑通&lt;/h2&gt;
&lt;p&gt;第一次接触这类合集，建议按这个顺序来，能少走很多弯路：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步，先把仓库克隆到本地。&lt;/strong&gt; 在线逐个文件翻看效率很低，克隆下来用编辑器全局搜索模型名最快：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git clone https://github.com/togg53192-cmd/jailbreaks.git
cd jailbreaks
ls   # 按厂商目录找你的模型
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第二步，按投放面选文件，不要只看模型名。&lt;/strong&gt; 同一个模型可能同时有系统提示词版和 AGENTS.md 版，先想清楚你要把它放进哪个槽位，再选对应文件。选错投放面是最常见的新手错误，后面排障部分还会提到。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三步，小范围验证是否生效。&lt;/strong&gt; 投放完成后，不要直接投入正式使用，先问两三个探针问题：让它复述自己的身份与工作规则、让它处理一个你知道默认行为会怎么答的请求。对照文件里的设定看回答是否对得上——对得上，说明指令进去了；对不上，多半是投放位置或优先级的问题。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第四步，记录版本。&lt;/strong&gt; 把你用的文件名和版本号记下来（比如 glm-zcode-5.3-AGENTS.md）。模型和仓库都在持续更新，三个月后回来排查「怎么突然不好用了」，这条记录能帮你快速定位是模型变了还是文件换了。&lt;/p&gt;
&lt;p&gt;这套流程对本地模型尤其友好：Ollama 的 Modelfile 路线完全离线、可复现、不存在账号风险，是风险最低的试验场。想先练手，从 Gemma 4 或 GPT-OSS 20B 的 Modelfile 开始最稳妥。&lt;/p&gt;
&lt;h2&gt;排障与失效处理&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;粘贴后行为没变化。&lt;/strong&gt; 最常见的原因是投放面不对：把 AGENTS.md 的内容贴进聊天框、把系统提示词写进项目文件，都不会生效。先对照文件标注的类型确认投放位置。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;以前有效、现在失效。&lt;/strong&gt; 这是常态而非故障。仓库在说明里专门提醒：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;提示词行为高度依赖版本&amp;lt;/span&amp;gt;——模型更新、指令层级调整、系统提示词轮换，任何一项都会让旧文件失效。失效后先看仓库有没有出新版文件（它的贡献规范要求大改动必须升版本号，如 opus-v3.md），不要在旧文件上自己缝补。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;本地 Modelfile 报错。&lt;/strong&gt; 先确认基础模型已拉取（&lt;code&gt;ollama list&lt;/code&gt; 里能看到 FROM 指向的模型），再确认 Modelfile 路径无误；&lt;code&gt;ollama create&lt;/code&gt; 对 FROM 的模型名拼写是严格匹配的。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;效果与描述不符。&lt;/strong&gt; 贡献规范第五条要求贡献者不得声称未测试过的兼容性，但个人项目的实测覆盖面有限。把文件当起点而不是保证，重要场景先小规模试跑再决定是否采用。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;同名文件有好几个版本，选哪个。&lt;/strong&gt; 原则是先新后旧：带更高版本号的（如 v2、5.3）是作者针对新模型迭代的版本，优先用它；只有当新版在你的模型上表现异常，才退回旧版对照。注意有些「版本」其实是不同变体而非迭代关系，比如同一模型的系统提示词版和 AGENTS.md 版，是投放面不同，不能互相替代。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;搜索不到某个模型。&lt;/strong&gt; 合集覆盖的是作者和贡献者实测过的模型，冷门模型、刚发布的新模型往往还没收录。可以先去仓库的 issue 区看有没有人提需求，或者拿同厂商上一代模型的文件做底稿自己改——但改完的效果就属于未实测范围了，心里要有数。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;jailbreaks 的价值不在于「能解锁什么」，而在于它把散落在各处的越狱提示词第一次系统地归档、分类、版本化：32 个文件、26 多个模型、四种投放面，构成了一份观察当代大模型指令行为的完整标本。对研究提示词工程和提示注入防御的人，这是省去大量搜集功夫的现成材料；对普通用户，它更适合当作理解「系统提示词到底能决定多少事」的科普读本。用之前记住那两条边界：版本一变就可能失效，平台条款的风险要自己评估。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：MuseAI-Skills 拆箱——68 个技能与一份非官方存档的正确读法</title><link>https://www.anexns.cloudns.org/posts/ai-museai-skills/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-museai-skills/</guid><description>有人把 muse.ai 个人 AI Agent 的整套技能文档与运行环境快照打包放上了 GitHub：68 个技能、十大分类、方法级权限清单与行为评测一应俱全。这篇把它逐层拆开，讲清它是什么、不是什么，以及普通人该怎么读、能学走什么。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说主线：有人把一台 AI 助手的「大脑目录」整个打包了&lt;/h2&gt;
&lt;p&gt;想象一下：一个已经在真实用户手里跑了很久的个人 AI Agent，它的全部技能说明、权限清单、产品文档、启动脚本，被人原封不动打包成一个仓库放上了 GitHub。MuseAI-Skills 就是这么一份东西——它不是某个工具的安装包，而是一份&lt;strong&gt;运行环境的存档快照&lt;/strong&gt;：72 个技能文件路径、26 份产品说明、77 个程序路径，还有一整套把隔离运行单元拉起来的生命周期脚本。&lt;/p&gt;
&lt;p&gt;这种材料平时根本见不到。官方产品只给你界面和结果，不给你看它内部怎么组织技能、怎么声明权限、怎么做行为评测。这个仓库的价值不在于「装上它」，而在于&lt;strong&gt;拆开它&lt;/strong&gt;：看一个成熟 Agent 的技能是怎么写的、权限是怎么收的、验收是怎么做的。这一篇就按拆箱的顺序来：先定性，再看结构，然后把 68 个技能逐类过一遍，挑一个解剖到底，最后给四条阅读路线和一套可以迁移到自己 Agent 上的写法。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/win4r/MuseAI-Skills&lt;/p&gt;
&lt;p&gt;先把最重要的话说在前面：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;这是一份非官方存档，不是 muse.ai 的官方发布，也不是开源项目。&amp;lt;/span&amp;gt;核心程序是 Linux x86-64 的 ELF 二进制，由 Git LFS 管理，仓库里没有源码、没有构建定义、没有完整的 rootfs，所以这份快照&lt;strong&gt;无法独立启动&lt;/strong&gt;。把它当「可以下载来跑的软件」是第一个、也是最大的误读；把它当「可以逐字研读的设计样本」，它立刻变得非常值钱。&lt;/p&gt;
&lt;h2&gt;它是什么，不是什么：先对齐定位&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;问题&lt;/th&gt;
&lt;th&gt;答案&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;它是官方开源吗&lt;/td&gt;
&lt;td&gt;不是。非官方存档，整份快照没有统一开源许可&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;它能一键部署吗&lt;/td&gt;
&lt;td&gt;不能。无源码、无完整 rootfs，快照无法独立启动&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;它包含什么&lt;/td&gt;
&lt;td&gt;技能文档与清单、产品契约说明、生命周期脚本、二进制程序快照&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;它的正确打开方式&lt;/td&gt;
&lt;td&gt;只读研读：学技能设计、权限模型、产品契约与运行架构&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;它的许可状态&lt;/td&gt;
&lt;td&gt;公开可见 ≠ 可任意再分发，各组件保留各自版权与许可&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;完整下载有多大&lt;/td&gt;
&lt;td&gt;约 2.02 GB（inode 去重后约 1.55 GB），绝大部分是 LFS 二进制&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;所以本文的立场很简单：**只读，不跑。**后面所有内容——结构、技能全景、解剖、阅读路线——都是阅读指南；下载一节也只讲「怎么完整地拿到并校验这份存档」，不讲任何「把它运行起来」的步骤，因为那既做不到、也不该做。&lt;/p&gt;
&lt;p&gt;:::warning
仓库里的 runtime 脚本包含绝对路径、挂载与系统服务操作，核心二进制来源未经官方认证。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要在自己的机器上照着执行随包的二进制与 runtime-cell 脚本&amp;lt;/span&amp;gt;，把这份仓库当纯文档读，是唯一推荐的用法。
:::&lt;/p&gt;
&lt;h2&gt;仓库结构总览：三大部分&lt;/h2&gt;
&lt;p&gt;整个仓库可以粗分成三块，性质完全不同，读的时候要分清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;部分&lt;/th&gt;
&lt;th&gt;位置&lt;/th&gt;
&lt;th&gt;内容&lt;/th&gt;
&lt;th&gt;性质&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;技能包&lt;/td&gt;
&lt;td&gt;&lt;code&gt;opt/hatch/skills/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;72 个 SKILL.md 路径、40 个 manifest.yaml、12 份 eval 场景&lt;/td&gt;
&lt;td&gt;本篇的主体，最值得精读&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;产品与设备说明&lt;/td&gt;
&lt;td&gt;&lt;code&gt;home/hatch/docs/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;26 份文档：muse.md、goals.md、connectors.md、browser.md、privacy-and-credentials.md、scheduling-and-watching.md、artifacts.md 等&lt;/td&gt;
&lt;td&gt;产品契约说明，讲「应该怎样」而非实现&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;运行单元&lt;/td&gt;
&lt;td&gt;&lt;code&gt;opt/hatch/runtime-cell/&lt;/code&gt; 与 &lt;code&gt;opt/hatch/bin/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;生命周期脚本一套；77 个程序路径（hatch daemon、spawnd、hatch-execd 与各连接器 CLI）&lt;/td&gt;
&lt;td&gt;实现脚本与二进制，只看结构、不执行&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;runtime-cell 的生命周期链条是：&lt;code&gt;pre-start&lt;/code&gt; 做启动前准备 → &lt;code&gt;launch-daemon&lt;/code&gt; 以 systemd-nspawn 拉起隔离单元 → &lt;code&gt;post-start&lt;/code&gt; 做启动后收尾 → &lt;code&gt;control-daemon&lt;/code&gt; / &lt;code&gt;control-execd&lt;/code&gt; 负责运行期控制。这条链对理解「Agent 的运行环境是怎么被托管的」很有参考价值，但它是&lt;strong&gt;实现脚本，不是安装教程&lt;/strong&gt;——照着它在自己机器上敲，不会得到一个能用的系统，只会得到一堆对不上号的路径错误。&lt;/p&gt;
&lt;p&gt;docs 目录则相反，它是最「干净」的部分：26 份文档是产品契约层面的说明，比如隐私与凭据怎么处理、调度与监看怎么定义、产物（Artifacts）是什么。想了解这个产品「承诺了什么」，读 docs；想了解「技能怎么组织」，读 skills；想了解「进程怎么拉起」，看 runtime-cell 的脚本名和顺序就够了。&lt;/p&gt;
&lt;p&gt;这三部分的「可信度梯度」也值得注意：docs 是对外承诺，措辞最规范，适合引用；skills 是内部工作文件，写给模型看，行文直接、命令式；runtime 脚本是工程现场，带着真实环境的路径与假设。读同一件事的三种文本互相印证，是这份存档独有的读法——比如「凭据怎么保管」，docs 里有原则声明，某个技能的 manifest 里有具体的 scopes 落点，脚本里则能看到凭据实际被注入的位置。三层对得上，说明这不是摆样子；对不上地方，往往就是设计债所在。&lt;/p&gt;
&lt;h2&gt;68 个技能全景：十大分类逐个点名&lt;/h2&gt;
&lt;p&gt;先把账算清：仓库里共有 &lt;strong&gt;72 个 SKILL.md 路径&lt;/strong&gt;，其中 4 个是符号链接别名——&lt;code&gt;facebook&lt;/code&gt; 指向 &lt;code&gt;facebook-cli&lt;/code&gt;、&lt;code&gt;meta-threads&lt;/code&gt; 指向 &lt;code&gt;threads&lt;/code&gt;、&lt;code&gt;podcast&lt;/code&gt; 指向 &lt;code&gt;generate_podcast&lt;/code&gt;、&lt;code&gt;voice-calls&lt;/code&gt; 指向 &lt;code&gt;voice-selector&lt;/code&gt;。去掉别名，&lt;strong&gt;独立技能是 68 个&lt;/strong&gt;。这里有个容易踩的坑：&lt;code&gt;voice-calls&lt;/code&gt; 这个名字听起来像「语音通话」，但它实际指向的是静态语音选择目录，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;技能的名字不能当能力说明书读，触发条件和正文才是。&amp;lt;/span&amp;gt;下面按官方的十大分类逐个点名，每个技能给一句定位。&lt;/p&gt;
&lt;h3&gt;一、Agent 工作流与记忆（6 个）&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;技能&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;wide-research&lt;/td&gt;
&lt;td&gt;多代理并行研究：协调者拆题、worker 并行、统一输出&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;goals&lt;/td&gt;
&lt;td&gt;目标管理：创建目标、记录进展与状态&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;skill-creator&lt;/td&gt;
&lt;td&gt;创建新技能的元技能：技能是怎么被生产出来的&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;self-awareness&lt;/td&gt;
&lt;td&gt;自我认知：助手对自己能力与状态的说明&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;forget&lt;/td&gt;
&lt;td&gt;遗忘机制：按用户要求删除记忆及其副本&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;muse_db&lt;/td&gt;
&lt;td&gt;数据库直查：跨表追踪与诊断用的只读 SQL 通道&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;二、文档、表格与产物验收（6 个）&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;技能&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;artifacts/document&lt;/td&gt;
&lt;td&gt;文档类产物（报告、PDF、演示、表格）的创建与编辑&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;markdown&lt;/td&gt;
&lt;td&gt;Markdown 文档处理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;pdf&lt;/td&gt;
&lt;td&gt;PDF 的读取、生成与检查&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;presentation&lt;/td&gt;
&lt;td&gt;演示文稿产物&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;spreadsheet&lt;/td&gt;
&lt;td&gt;电子表格产物&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;testing&lt;/td&gt;
&lt;td&gt;产物验收：交付物到底能不能用，要单独验&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;三、旅行、本地搜索与预订（7 个）&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;技能&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;travel-planning&lt;/td&gt;
&lt;td&gt;旅行规划：把研究、比价、预订组织成一份行程&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;booking&lt;/td&gt;
&lt;td&gt;预订类操作的统一入口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;places-search&lt;/td&gt;
&lt;td&gt;地点搜索：地址、营业时间、评价与照片&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;duffel&lt;/td&gt;
&lt;td&gt;航班库存与订票（Duffel 接口）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;flightaware&lt;/td&gt;
&lt;td&gt;航班动态、轨迹与机场活动（FlightAware 数据）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;opentable&lt;/td&gt;
&lt;td&gt;餐厅订位（OpenTable）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ticketmaster&lt;/td&gt;
&lt;td&gt;演出与赛事票务（Ticketmaster）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;四、办公、邮箱与知识工具（16 个）&lt;/h3&gt;
&lt;p&gt;这是最大的一类，占了近四分之一，基本就是一个人的办公桌面全家桶：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;技能&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;gmail&lt;/td&gt;
&lt;td&gt;Gmail 搜索、阅读、起草、发送与整理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-calendar&lt;/td&gt;
&lt;td&gt;日历读写、空闲查询、会议安排&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-contacts&lt;/td&gt;
&lt;td&gt;通讯录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-docs&lt;/td&gt;
&lt;td&gt;Google 文档读写&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-drive&lt;/td&gt;
&lt;td&gt;云端硬盘文件管理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-forms&lt;/td&gt;
&lt;td&gt;表单&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-sheets&lt;/td&gt;
&lt;td&gt;表格&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-slides&lt;/td&gt;
&lt;td&gt;幻灯片&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-tasks&lt;/td&gt;
&lt;td&gt;任务清单&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;outlook-calendar&lt;/td&gt;
&lt;td&gt;Outlook 日历&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;outlook-contacts&lt;/td&gt;
&lt;td&gt;Outlook 通讯录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;outlook-mail&lt;/td&gt;
&lt;td&gt;Outlook 邮件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;notion&lt;/td&gt;
&lt;td&gt;Notion 笔记与知识库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;granola&lt;/td&gt;
&lt;td&gt;会议笔记（Granola）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;muse-mail&lt;/td&gt;
&lt;td&gt;Muse 自有邮箱&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;calendly&lt;/td&gt;
&lt;td&gt;预约排期（Calendly）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;五、社交网络与消息（6 个）&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;技能&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;facebook-cli&lt;/td&gt;
&lt;td&gt;Facebook 的动态、群组、市场等全套操作&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;instagram&lt;/td&gt;
&lt;td&gt;Instagram 浏览、发布与互动&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;instagram-messages&lt;/td&gt;
&lt;td&gt;Instagram 私信&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;messenger&lt;/td&gt;
&lt;td&gt;Messenger 消息读写&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;threads&lt;/td&gt;
&lt;td&gt;Threads 动态与发布&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;threads-messages&lt;/td&gt;
&lt;td&gt;Threads 私信&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;注意这一类里别名最密集：&lt;code&gt;facebook&lt;/code&gt; 与 &lt;code&gt;meta-threads&lt;/code&gt; 两个符号链接都指向本类技能，统计时别重复计数。&lt;/p&gt;
&lt;h3&gt;六、购物、商品与金融数据（3 个）&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;技能&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;shopping&lt;/td&gt;
&lt;td&gt;商品搜索、比价与购物卡片&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;printify&lt;/td&gt;
&lt;td&gt;按需印刷商品（Printify）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;plaid&lt;/td&gt;
&lt;td&gt;银行与金融数据接入（Plaid）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;七、健康与健身数据（6 个）&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;技能&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;apple-healthkit&lt;/td&gt;
&lt;td&gt;iPhone 同步的健康指标、睡眠与锻炼&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-health-connect&lt;/td&gt;
&lt;td&gt;Android 的 Health Connect 数据&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;function-health&lt;/td&gt;
&lt;td&gt;Function Health 的化验与健康数据&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;healthex&lt;/td&gt;
&lt;td&gt;HealthEx 健康记录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;peloton&lt;/td&gt;
&lt;td&gt;Peloton 骑行与课程数据&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;withings&lt;/td&gt;
&lt;td&gt;Withings 设备（体重、血压、睡眠）数据&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;八、图像、音频与视频工作流（8 个）&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;技能&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;image-search&lt;/td&gt;
&lt;td&gt;按文字搜图，拿图片链接与来源页&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;media-library&lt;/td&gt;
&lt;td&gt;用户照片库搜索与查看&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;spotify&lt;/td&gt;
&lt;td&gt;音乐搜索、播放与歌单管理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;generate_podcast&lt;/td&gt;
&lt;td&gt;播客/音频节目的研究、脚本与制作&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;tts&lt;/td&gt;
&lt;td&gt;文字转语音&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;voice-design&lt;/td&gt;
&lt;td&gt;语音设计&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;voice-selector&lt;/td&gt;
&lt;td&gt;语音选择（静态语音目录）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;magic-moment&lt;/td&gt;
&lt;td&gt;把事实素材做成短视频的完整流水线&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;九、设备、通信与网络（6 个）&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;技能&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;device-data&lt;/td&gt;
&lt;td&gt;已配对设备的联系人与日历缓存读取&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;wearable-device-skills&lt;/td&gt;
&lt;td&gt;可穿戴设备技能组&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;wearables-comms&lt;/td&gt;
&lt;td&gt;可穿戴设备通信&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;philips-hue&lt;/td&gt;
&lt;td&gt;Philips Hue 智能照明控制&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;tessie&lt;/td&gt;
&lt;td&gt;特斯拉车辆数据（Tessie）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;tailscale&lt;/td&gt;
&lt;td&gt;Tailscale/Headscale 私有网络接入&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;十、Muse 产品操作（4 个）&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;技能&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;muse-early-access&lt;/td&gt;
&lt;td&gt;早期访问计划的加入与状态&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;muse-feedback&lt;/td&gt;
&lt;td&gt;给 Muse 团队的产品反馈通道&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;share-ideas&lt;/td&gt;
&lt;td&gt;Ideas 功能的浏览与发布&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;subscription-status&lt;/td&gt;
&lt;td&gt;订阅、用量与额度状态查询&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;还有一个计数上的细节：配套文件并不与技能一一齐全——72 个技能路径之外，仓库里只有 40 个 manifest.yaml 和 12 份 eval 场景 YAML。也就是说，不到六成的技能有权限清单，不到两成有评测场景。这个比例本身就是信息：它说明这套体系是「先有技能、后补清单与评测」的生长方式，核心高频技能（比如 Gmail）三件套齐全，长尾技能可能只有一份 SKILL.md。读的时候按这个预期去翻，就不会因为某个技能缺 manifest 而怀疑自己下漏了文件。&lt;/p&gt;
&lt;p&gt;把这 68 个连起来看，能读出三条信息。第一，&lt;strong&gt;技能的粒度是「一个数据源/一个工作流一个技能」&lt;/strong&gt;，而不是按 App 堆功能：Gmail 与 Outlook Mail 分开、Instagram 与它的私信分开。第二，&lt;strong&gt;连接器型技能占绝对多数&lt;/strong&gt;——办公、社交、健康三类全是「接外部服务」，这决定了权限清单（manifest）为什么是必需品，下一节就讲这个。第三，&lt;strong&gt;元技能的存在感很强&lt;/strong&gt;：skill-creator 负责生产技能、testing 负责验收产物、forget 负责删除、wide-research 负责组织研究——一个成熟 Agent 的技能表里，有相当比例是「管技能自己的技能」。如果你也在攒自己的技能库，这张全景表就是一张现成的查漏清单：对照着看你还缺哪一类。对「把现成文档和仓库变成技能」这件事本身感兴趣的，可以接着看站内的 &lt;a href=&quot;/posts/ai-skill-seekers/&quot;&gt;Skill Seekers 技能生成工具&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;解剖一个技能：Gmail 的四件套&lt;/h2&gt;
&lt;p&gt;68 个技能里，结构最完整的样本是 Gmail。它不是一份文档，而是一组文件：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;文件&lt;/th&gt;
&lt;th&gt;角色&lt;/th&gt;
&lt;th&gt;回答的问题&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SKILL.md&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;技能正文&lt;/td&gt;
&lt;td&gt;什么时候触发、按什么流程做、边界在哪&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;manifest.yaml&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;连接器清单&lt;/td&gt;
&lt;td&gt;有哪些方法、默认权限多大、要哪些 OAuth scopes、命令怎么映射&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;eval/scenarios.yaml&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;行为评测场景&lt;/td&gt;
&lt;td&gt;给定场景时期望的行为是什么&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;references/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;参考资料&lt;/td&gt;
&lt;td&gt;细节文档，按需加载，不塞进主文件&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;逐个说。&lt;strong&gt;SKILL.md&lt;/strong&gt; 的 frontmatter 写触发条件——什么样的话、什么样的任务应该唤起这个技能；正文写操作流程与边界——比如发送邮件前哪些信息必须与用户确认、线程和收件人不能弄错。主文件保持精简，是这一整套设计的共同风格：细节下沉到 references，需要时才读。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;manifest.yaml&lt;/strong&gt; 是机器可读的连接器元数据：它按「方法」声明权限默认值，需要的 OAuth scopes，以及技能动作到实际命令的映射。关键设计是&lt;strong&gt;方法级可以覆盖分组默认&lt;/strong&gt;：同一个连接器里，「搜索邮件」可以是默认放行，「发送邮件」则收紧到需要确认——权限不是按 App 一刀切，而是细到每个动作。它的结构大致是这个形状（示意）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;connector: gmail
oauth_scopes:
  - gmail.readonly
  - gmail.send
method_groups:
  read:            # 分组默认：只读类方法
    default: allow
  write:           # 分组默认：写操作
    default: confirm
methods:
  search:  { group: read,  command: &quot;gmail search&quot; }
  send:    { group: write, command: &quot;gmail send&quot;, default: confirm }
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;读这份清单的方法，是顺着「最危险的方法」倒着看：先找发送、删除、付款类方法被设成了什么，再看只读类放得多宽。一个连接器的风险画像，看它的写方法默认档位就够了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;eval/scenarios.yaml&lt;/strong&gt; 是行为评测：预先写好场景和期望行为，用来回归测试技能改动有没有把行为改坏。这里要泼一盆冷水：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;仓库里有评测场景，不等于这些评测被运行过、更不等于全部通过&amp;lt;/span&amp;gt;——场景文件是「考题」，不是「成绩单」。整个仓库共 40 个 manifest 与 12 份 eval 场景，覆盖率本身也说明：清单和评测是逐步补齐的，不是一开始就全的。&lt;/p&gt;
&lt;p&gt;最后是两个最容易混淆的概念，务必分清：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;available ≠ 已连接&lt;/strong&gt;：&lt;code&gt;config/skills.yaml&lt;/code&gt; 里声明某个技能 available，只表示它在技能表里可见、可以被触发；用户的账户是否真的连上了那个服务，是另一回事。技能在，不代表邮箱就能读。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;可见性 ≠ 权限&lt;/strong&gt;：&lt;code&gt;skill-scopes.conf&lt;/code&gt; 控制的是技能的可见范围，它不授予任何操作权限；真正的操作权限在 manifest 的方法级声明里。把「看得见」误当「能动手」，是读这套配置最常见的翻车点。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;这一节的结论值得单独记住：一个生产级技能是「说明书＋权限清单＋考题＋参考库」的组合，而不是一段写给模型的提示词。&amp;lt;/span&amp;gt;这也是本仓库最值得抄走的设计。&lt;/p&gt;
&lt;h2&gt;优先精读的 8 个：官方推荐顺序&lt;/h2&gt;
&lt;p&gt;仓库给了一份推荐优先阅读的清单，8 个技能，每个都代表一种可迁移的模式。按它的顺序逐个讲：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;1. wide-research（协调者/worker 分工）。&lt;/strong&gt; 复杂研究任务被拆成「协调者拆题派活、worker 并行执行、统一输出契约回收」三段，并且要求&lt;strong&gt;失败也要覆盖报告&lt;/strong&gt;——没查到的、失败的，必须如实写进结果，而不是只交成功的那部分。这是多代理协作最值得学的一条纪律。它还示范了另一件常被忽略的事：并行之前先约定回收格式。worker 各写各的、格式五花八门，协调者最后拼不起来，是多代理系统最常见的烂尾方式；先定契约再分工，顺序不能反。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. skill-creator（技能的生产规范）。&lt;/strong&gt; 触发条件写得明确、主文件保持精简、参考资料按需加载——这三条就是它给所有技能定的体例。想自己写技能，先读它，等于先读体例再动笔。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. artifacts/testing（生成 ≠ 可用）。&lt;/strong&gt; 它把「生成成功」和「交付物可用」拆成两件事验收：文件生成出来只是第一步，能不能打开、内容对不对、格式合不合格，要单独验。这一条对所有「让 AI 交文件」的工作流都适用。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. goals（首次与跟进分开）。&lt;/strong&gt; 目标管理里最容易写混的是「第一次建目标」和「后续跟进」——前者是建档流程，后者是更新流程，触发条件和动作完全不同。这个技能按领域把两条路线分开写，是「同名技能、双入口」的范本。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. forget（删除要删干净）。&lt;/strong&gt; 删除记忆不是删一行字：还有副本、衍生状态、以及后台可能把旧内容再写回来的通道。这个技能处理的是「删透」问题——对隐私相关功能，这是最容易做半截的地方。它给所有做记忆系统的实现者提了个醒：删除功能要在建数据结构的第一天就设计，事后补删，永远补不干净。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;6. travel-planning（研究与交易分开路由）。&lt;/strong&gt; 旅行规划里，「查攻略、比方案」是研究型查询，「查实时可订库存、下单」是交易型操作，两者的工具、时效和确认要求都不同。这个技能把两条路线分开，是所有「先查后买」类工作流的通用解法。站内讲 AI 编程助手的那篇里也聊过类似的工具路由问题，可对照看：&lt;a href=&quot;/posts/ai-coding-assistants/&quot;&gt;AI 编程助手&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;7. magic-moment（内容流水线）。&lt;/strong&gt; 从事实素材出发，经叙事组织、视觉设计、时间线编排，到&lt;strong&gt;渲染前审阅&lt;/strong&gt;才输出——它把短视频制作拆成一条有验收点的流水线，而不是一句提示词生成到底。站内另一篇专门拆视频技能的文章讲的是同一类思路：&lt;a href=&quot;/posts/ai-muse-video-skill/&quot;&gt;Muse Video Skill&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;8. gmail（三件套范本）。&lt;/strong&gt; 上一节刚解剖过：技能正文＋方法级权限 manifest＋行为评测场景，三个文件各管一摊。想给自己的技能补权限和评测，照着它的文件组织抄即可。&lt;/p&gt;
&lt;h2&gt;四条阅读路线：按目的选，别从头硬啃&lt;/h2&gt;
&lt;p&gt;2 GB 的仓库、几百个文件，从头读是读不完的。按目的选路线：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;路线&lt;/th&gt;
&lt;th&gt;读什么&lt;/th&gt;
&lt;th&gt;适合谁&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;学工作流设计&lt;/td&gt;
&lt;td&gt;wide-research、goals、travel-planning、magic-moment 的 SKILL.md&lt;/td&gt;
&lt;td&gt;在设计自己的多步任务/Agent 流程&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;学权限模型&lt;/td&gt;
&lt;td&gt;gmail 的 manifest.yaml ＋ docs 里的 privacy-and-credentials.md&lt;/td&gt;
&lt;td&gt;在给工具调用做权限分级&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;看产品设计&lt;/td&gt;
&lt;td&gt;home/hatch/docs/ 的 26 份文档（goals.md、scheduling-and-watching.md、artifacts.md 等）&lt;/td&gt;
&lt;td&gt;想了解一个 AI 产品如何定义自己的契约&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;看运行架构&lt;/td&gt;
&lt;td&gt;runtime-cell 的脚本顺序与 bin 目录结构、connectors.md&lt;/td&gt;
&lt;td&gt;想了解 Agent 运行环境如何托管与隔离&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;四条路线互不依赖，每条半天以内能读完核心部分。最不建议的是按目录顺序从第一个文件读起——技能包按字母序排列，和重要性毫无关系。&lt;/p&gt;
&lt;p&gt;读的时候建议带一个笔记维度：每读完一个技能，只记三件事——它的触发条件怎么写、它的权限默认档位在哪一级、它有没有验收手段。68 个技能记完，你手里就是一张这个产品的「治理水平表」：哪些领域管得严、哪些领域还在裸奔，一目了然。这张表比任何单个技能的细节都更接近这份存档的全貌。&lt;/p&gt;
&lt;h2&gt;下载与完整性校验：只读研读的正确姿势&lt;/h2&gt;
&lt;p&gt;如果你想把这份存档拉到本地慢慢读，有两种拉法。&lt;strong&gt;只读文档&lt;/strong&gt;的话，跳过全部 LFS 二进制，仓库瞬间变小，技能文档、清单、产品说明一个不少：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/win4r/MuseAI-Skills.git
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;要完整快照&lt;/strong&gt;（包含全部二进制，约 2.02 GB）则必须先装 Git LFS，再正常克隆并校验 LFS 内容：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git lfs install
git clone https://github.com/win4r/MuseAI-Skills.git
cd MuseAI-Skills
git lfs pull
git lfs fsck
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个注意点。第一，&lt;strong&gt;不要用 GitHub 的 ZIP 下载当完整版&lt;/strong&gt;：ZIP 里 LFS 文件只会是指针文件，普通 ZIP 下载无法证明 LFS 内容完整——要完整性，就走 git lfs 这条路。第二，下完之后用仓库根目录的校验文件核对哈希：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# Linux
sha256sum --check SHA256SUMS

# macOS
shasum -a 256 -c SHA256SUMS
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拉完整版之前先确认磁盘：快照解开后约 2.02 GB，其中相当一部分是同一批二进制在不同路径下的重复引用，按 inode 去重统计约 1.55 GB；文件系统是否支持硬链接去重，会影响你实际看到的占用。还有一个自检小技巧：完整克隆后随手打开一个二进制路径看大小——如果只有一百多字节、内容是一行 &lt;code&gt;version https://git-lfs.github.com/spec/v1&lt;/code&gt; 开头，那就是 LFS 指针文件，说明 &lt;code&gt;git lfs pull&lt;/code&gt; 没有真正执行成功，重新拉一遍即可，别急着怀疑仓库坏了。&lt;/p&gt;
&lt;p&gt;但要清楚哈希能证明什么：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;哈希一致只证明「你拿到的文件和仓库里的文件是同一份」，不验证来源是否官方、内容是否安全。&amp;lt;/span&amp;gt;它防的是传输损坏和下载不全，防不了「这份东西本身就不可信」——而这正是非官方存档的固有前提。&lt;/p&gt;
&lt;h2&gt;把技能模式迁移到自己的 Agent&lt;/h2&gt;
&lt;p&gt;读完这份存档，真正能带走的是写法。把 68 个技能的共同体例提炼成一份可直接套用的要点：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;SKILL.md 的写法要点：&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;一份最小可用的 SKILL.md，骨架大致是这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;---
name: my-skill
description: 当用户要求 &amp;lt;具体场景&amp;gt; 时使用；不适用于 &amp;lt;排除场景&amp;gt;
---

## 流程
1. 先确认 &amp;lt;关键前提&amp;gt;
2. 执行 &amp;lt;动作&amp;gt;，其中 &amp;lt;不可逆动作&amp;gt; 前必须向用户确认
3. 结果按 &amp;lt;固定格式&amp;gt; 汇报，失败项单独列出

## 边界
- 不处理 &amp;lt;范围外事项&amp;gt;
- 细节见 references/ 下对应文档，按需读取
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;触发条件写在 frontmatter 里，写具体。&lt;/strong&gt; 不是「处理邮件」，而是「当用户要求搜索、起草、发送或整理邮件时」。触发写糊了，技能要么乱入、要么永远轮不到。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;主文件只放流程与边界。&lt;/strong&gt; 步骤、确认点、禁止项写在正文；大段参考（字段表、接口说明、示例库）拆进 references/，按需加载——主文件越短，被完整执行的概率越高。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;把「必须确认」写进流程，而不是指望模型自觉。&lt;/strong&gt; 发送、删除、付款这类不可逆动作，在正文里明确写出确认点。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;权限与验收要和正文分家：&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;权限单独成清单（学 manifest.yaml）：按方法声明默认权限，高风险方法单独收紧，不要给整个工具一把总钥匙。&lt;/li&gt;
&lt;li&gt;验收单独成场景（学 eval/scenarios.yaml）：给技能写几条「输入—期望行为」的考题，改技能时先跑考题。没有考题的技能，改一次飘一次。&lt;/li&gt;
&lt;li&gt;可见性与权限分开管理（学 skill-scopes.conf 与 manifest 的分工）：谁能看到这个技能、这个技能能动什么，是两个独立开关。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这套模式不挑平台：无论你用的是哪家的 Agent 框架，「说明书＋权限清单＋考题」三件套都能平移过去。站内 &lt;a href=&quot;/posts/ai-cliproxyapi/&quot;&gt;CLIProxyAPI&lt;/a&gt; 那篇讲的是把订阅能力接进本地工具链，和这里的技能组织是两个层面的事，搭配着看能拼出「接口层＋技能层」的完整图景。&lt;/p&gt;
&lt;h2&gt;边界与缺项：这份存档缺了什么&lt;/h2&gt;
&lt;p&gt;把缺口列清楚，才不会对它抱有不切实际的期待：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;缺项&lt;/th&gt;
&lt;th&gt;影响&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;核心源码与构建定义&lt;/td&gt;
&lt;td&gt;无法研究实现、无法自行构建&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;完整宿主服务与 rootfs&lt;/td&gt;
&lt;td&gt;快照无法独立启动（这是根本限制）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据库迁移文件&lt;/td&gt;
&lt;td&gt;数据层结构只能从文档侧推测&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Artifacts 的 build.mjs 与 sdk/&lt;/td&gt;
&lt;td&gt;产物构建链不完整&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;评测的 spawn-eval-instructions.md&lt;/td&gt;
&lt;td&gt;评测如何被执行，不在快照内&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;runtime-cell 的 run-execd.sh&lt;/td&gt;
&lt;td&gt;生命周期链缺一环&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;opt/hatch-image/bin/gws&lt;/td&gt;
&lt;td&gt;零字节文件，只剩占位&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;再加上许可问题：整份快照&lt;strong&gt;没有统一开源许可&lt;/strong&gt;，各组件保留各自的版权与许可声明。所以对它的合理使用边界是：个人研读、学习设计、引用讨论；把它重新打包分发、把里面的二进制拿去他用，都不在「公开可见」自动授予的范围里。&lt;/p&gt;
&lt;h2&gt;常见误解排障&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;「这是 muse.ai 官方开源了？」&lt;/strong&gt; 不是。非官方存档，官方没有为这份仓库背书。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;「克隆下来就能把这个 Agent 跑起来？」&lt;/strong&gt; 不能。无源码、无完整 rootfs、无数据库迁移，快照无法独立启动，这是定位问题，不是你配置错了。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;「我下的是 ZIP，怎么文件都只有几百字节？」&lt;/strong&gt; 那是 LFS 指针文件。要完整内容，用 git lfs install 后重新克隆并 git lfs pull。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;「技能在列表里，为什么连不上我的邮箱？」&lt;/strong&gt; available ≠ 已连接：技能声明可见，不等于账户已完成连接授权。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;「我给了它全部可见范围，为什么还是不能发邮件？」&lt;/strong&gt; 可见性（skill-scopes.conf）不授予操作权限；发送这类方法的权限在 manifest 里单独声明，默认可能就是需要确认或禁用。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;「仓库里有 eval 场景，是不是说明评测都通过了？」&lt;/strong&gt; 不是。有场景只说明考题存在，不代表跑过、更不代表通过。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;「voice-calls 是语音通话技能吧？」&lt;/strong&gt; 不是。它是符号链接，指向静态语音目录 voice-selector——名字会骗人，链接目标和正文不会。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;「SHA256SUMS 校验全过，这份东西安全吗？」&lt;/strong&gt; 校验只证明文件一致，不证明来源与安全性。结论不变：只读，不跑。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;MuseAI-Skills 的正确打开方式，是把它的当一份&lt;strong&gt;难得的内部设计样本&lt;/strong&gt;：68 个技能的全景表可以当查漏清单，Gmail 的四件套可以当文件组织模板，官方推荐的 8 个精读样本分别对应一种可迁移的模式——分工、体例、验收、双入口、删透、路由、流水线、权限分家。至于运行它、部署它、再分发它，都不在这份非官方存档能给你的东西之列。读它的人赚的是设计，动手跑它的人只会收获报错——分清这条线，这 2 GB 就下得值。&lt;/p&gt;
</content:encoded></item><item><title>Superpowers 拆箱：给编程 Agent 装一套完整软件开发方法论的技能框架</title><link>https://www.anexns.cloudns.org/posts/ai-superpowers/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-superpowers/</guid><description>obra/superpowers 是目前最火的 Agent 技能框架之一：用一组可组合的技能加一段启动指令，把头脑风暴、写计划、TDD、子代理开发、代码审查这套完整流程焊进编程 Agent 的默认行为，支持 Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Muse 等 17 种宿主。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;编程 Agent 最常见的毛病是什么？需求还没说清，它已经写了三百行代码。Superpowers 的解法不是换个更强的模型，而是给 Agent 装上一套软件开发方法论：一组可组合的技能（Skills），加上一段启动指令，保证 Agent 在动手之前先把流程走完——先头脑风暴挖需求，再写设计，再拆计划，然后用子代理逐个任务推进，全程 TDD，每步审查。它是目前 GitHub 上最火的 Agent 技能框架，31.8 万星，而且同一套技能能装进 17 种不同的编程 Agent 里。本文把它拆开：工作流怎么运转、技能库里有什么、各宿主怎么装、出了问题怎么诊断。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/obra/superpowers&lt;/p&gt;
&lt;h2&gt;先看清这是什么&lt;/h2&gt;
&lt;p&gt;Superpowers 由 Jesse Vincent 与 Prime Radiant 团队维护，自我定义是「一套完整的、给编程 Agent 用的软件开发方法论，建立在一组可组合技能与启动指令之上」。关键数据（2026 年 11 月查于仓库主页）：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;项目&lt;/th&gt;
&lt;th&gt;数据&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Star&lt;/td&gt;
&lt;td&gt;约 318k&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Fork&lt;/td&gt;
&lt;td&gt;约 28.4k&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;建仓时间&lt;/td&gt;
&lt;td&gt;2025 年 10 月&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;版本发布&lt;/td&gt;
&lt;td&gt;17 个 Release&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;许可证&lt;/td&gt;
&lt;td&gt;MIT&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;支持宿主&lt;/td&gt;
&lt;td&gt;17 种编程 Agent&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;它和上一篇 &lt;a href=&quot;/posts/ai-ecc/&quot;&gt;ECC&lt;/a&gt; 的定位很像——都是给编程代理补「工程流程」这一层。区别在重心：ECC 是打包技能、记忆、安全扫描的运行时；Superpowers 更纯粹，押注的是&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;流程纪律本身&amp;lt;/span&amp;gt;：技能会自动触发，工作流是强制的，不是建议。&lt;/p&gt;
&lt;h2&gt;工作原理：启动指令 + 自动触发&lt;/h2&gt;
&lt;p&gt;Superpowers 由两部分组成。第一部分是技能库：一批写成文档的技能文件，每个技能描述一个流程（怎么做头脑风暴、怎么写计划、怎么系统化调试）。第二部分是启动指令：一个叫 using-superpowers 的引导技能，通过各宿主的会话启动钩子（SessionStart hook）注入，让 Agent 在每次会话开始时就知道「有技能可用、且必须用」。&lt;/p&gt;
&lt;p&gt;效果是：你不需要记任何命令。Agent 在执行任何任务前会先检查有没有匹配的技能，有就按技能走。这也是它敢自称「方法论」而不是「提示词包」的原因——流程不是你想起来才用的，是焊在默认行为里的。&lt;/p&gt;
&lt;h2&gt;核心工作流：七步&lt;/h2&gt;
&lt;p&gt;从你打开编程 Agent 的那一刻起，Superpowers 的工作流是这样的：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;步骤&lt;/th&gt;
&lt;th&gt;技能&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;brainstorming&lt;/td&gt;
&lt;td&gt;动手前先挖需求：通过提问弄清你到底要什么，把理解复述给你纠正；小改动在对话里对齐，大项目产出正式设计文档&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;using-git-worktrees&lt;/td&gt;
&lt;td&gt;设计批准后开隔离工作区：新分支、跑项目初始化、验证测试基线干净&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;writing-plans&lt;/td&gt;
&lt;td&gt;把工作拆成 2–5 分钟一个的小任务，每个任务带确切文件路径、完整代码和验证步骤&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;subagent-driven-development / executing-plans&lt;/td&gt;
&lt;td&gt;执行计划：前者给每个任务派一个全新子代理、逐个审查（最彻底）；后者在当前会话内顺序执行、最后统一审查整条分支（最省钱）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;test-driven-development&lt;/td&gt;
&lt;td&gt;实现全程强制 RED-GREEN-REFACTOR：先写失败的测试，看它失败，再写最小代码，看它通过，然后提交；先写代码后补测试的，删掉重来&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;requesting-code-review&lt;/td&gt;
&lt;td&gt;任务之间对照计划审查，按严重程度报告问题，严重问题阻断进度&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;finishing-a-development-branch&lt;/td&gt;
&lt;td&gt;全部任务完成后验证测试，给出合并 / PR / 保留 / 丢弃的选项，清理工作区&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;官方的说法是：计划批准、你说了「go」之后，Agent 自主工作几个小时不偏离计划是常事。这套流程的设计假设很明确——把计划写到「一个热情但没品味、没判断、没项目上下文、还讨厌测试的初级工程师都能照着做」的程度，执行环节就可以放心交给子代理。这与 &lt;a href=&quot;/posts/ai-museai-skills/&quot;&gt;MuseAI-Skills 存档&lt;/a&gt;里那些技能文件的思路同源：把经验写成 Agent 能严格照做的规程，而不是指望模型临场发挥。&lt;/p&gt;
&lt;h2&gt;技能库里有什么&lt;/h2&gt;
&lt;p&gt;仓库内置的技能按四类组织：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类别&lt;/th&gt;
&lt;th&gt;技能&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;测试&lt;/td&gt;
&lt;td&gt;test-driven-development&lt;/td&gt;
&lt;td&gt;RED-GREEN-REFACTOR 循环，附测试反模式参考&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;调试&lt;/td&gt;
&lt;td&gt;systematic-debugging&lt;/td&gt;
&lt;td&gt;四阶段根因定位流程（含根因追溯、纵深防御、条件等待等技法）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;调试&lt;/td&gt;
&lt;td&gt;verification-before-completion&lt;/td&gt;
&lt;td&gt;宣布修好之前，先验证真的修好了&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;调试&lt;/td&gt;
&lt;td&gt;diagnosing-superpowers&lt;/td&gt;
&lt;td&gt;诊断 Superpowers 自己在某个会话里的异常行为&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;协作&lt;/td&gt;
&lt;td&gt;brainstorming、writing-plans、executing-plans&lt;/td&gt;
&lt;td&gt;需求、计划与内联执行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;协作&lt;/td&gt;
&lt;td&gt;dispatching-parallel-agents&lt;/td&gt;
&lt;td&gt;并发子代理工作流&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;协作&lt;/td&gt;
&lt;td&gt;requesting-code-review、receiving-code-review&lt;/td&gt;
&lt;td&gt;发起审查与回应审查反馈&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;协作&lt;/td&gt;
&lt;td&gt;using-git-worktrees、finishing-a-development-branch&lt;/td&gt;
&lt;td&gt;并行分支与收尾决策&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;协作&lt;/td&gt;
&lt;td&gt;subagent-driven-development&lt;/td&gt;
&lt;td&gt;子代理逐任务推进 + 两段审查（先规范合规，再代码质量）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;元技能&lt;/td&gt;
&lt;td&gt;writing-skills&lt;/td&gt;
&lt;td&gt;按最佳实践写新技能（含技能的测试方法论）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;元技能&lt;/td&gt;
&lt;td&gt;using-superpowers&lt;/td&gt;
&lt;td&gt;技能系统总引导，即前述启动指令本体&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;安装：17 种宿主，各装各的&lt;/h2&gt;
&lt;p&gt;Superpowers 是按宿主（harness）分别安装的：用几个 Agent，就装几遍。主流宿主的安装方式如下。&lt;/p&gt;
&lt;p&gt;Claude Code（官方市场）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/plugin install superpowers@claude-plugins-official
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;或用作者自己的市场（还包含其他相关插件）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;其他宿主各有自己的插件机制，命令一览：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;宿主&lt;/th&gt;
&lt;th&gt;安装方式&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Codex App&lt;/td&gt;
&lt;td&gt;侧边栏 Plugins → Coding 区找到 Superpowers 点 +&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Codex CLI&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/plugins&lt;/code&gt; 里搜 superpowers，选 Install Plugin&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cursor&lt;/td&gt;
&lt;td&gt;Agent 对话里 &lt;code&gt;/add-plugin superpowers&lt;/code&gt;，或在插件市场搜&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini CLI&lt;/td&gt;
&lt;td&gt;&lt;code&gt;gemini extensions install https://github.com/obra/superpowers&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GitHub Copilot CLI&lt;/td&gt;
&lt;td&gt;&lt;code&gt;copilot plugin marketplace add obra/superpowers-marketplace&lt;/code&gt; 后 &lt;code&gt;copilot plugin install superpowers@superpowers-marketplace&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Grok Build CLI&lt;/td&gt;
&lt;td&gt;&lt;code&gt;grok plugin install superpowers@xai-official --trust&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Kimi Code&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/plugins&lt;/code&gt; 里进 Marketplace 安装，或 &lt;code&gt;/plugins install https://github.com/obra/superpowers&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Qwen Code&lt;/td&gt;
&lt;td&gt;&lt;code&gt;qwen extensions install obra/superpowers&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Devin CLI&lt;/td&gt;
&lt;td&gt;&lt;code&gt;devin plugins install obra/superpowers&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Factory Droid&lt;/td&gt;
&lt;td&gt;&lt;code&gt;droid plugin marketplace add https://github.com/obra/superpowers&lt;/code&gt; 后 &lt;code&gt;droid plugin install superpowers@superpowers&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Antigravity&lt;/td&gt;
&lt;td&gt;&lt;code&gt;agy plugin install https://github.com/obra/superpowers&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Pi&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pi install git:github.com/obra/superpowers&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Hermes Agent&lt;/td&gt;
&lt;td&gt;&lt;code&gt;hermes plugins install obra/superpowers --enable&lt;/code&gt;，装后要重启会话&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;OpenCode&lt;/td&gt;
&lt;td&gt;让 OpenCode 拉取仓库 .opencode/INSTALL.md 并按其中说明执行&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;值得单独说的是 Muse：Superpowers 提供了原生 Muse 插件，同一套技能、同一套启动注入（SessionStart 钩子），本地检出或克隆后安装：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git clone https://github.com/obra/superpowers.git
muse plugins install ./superpowers
muse plugins approve superpowers
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;装完要重启已打开的 Muse 会话，钩子才生效。验证装没装好有个官方小窍门：新开会话，发一句「Let&apos;s make a react todo list」，正常的话 Agent 会在写任何代码之前先自动触发 brainstorming 跟你聊需求。各宿主的更新方式多为自动，或用各自的插件 update 命令重跑一遍安装流程即可。更多宿主细节可对照 &lt;a href=&quot;/posts/ai-cli-assistants/&quot;&gt;AI 编程助手&lt;/a&gt;里对各家 CLI 的介绍。&lt;/p&gt;
&lt;h2&gt;出了问题怎么办：自带诊断技能&lt;/h2&gt;
&lt;p&gt;会话行为异常——技能该触发的没触发、不该触发的乱触发、Agent 无视计划、重复劳动、token 烧得比预期多——Superpowers 给自己留了一个诊断入口：让 Agent「figure out what went wrong with superpowers in this session」，它会调用 diagnosing-superpowers 技能，读会话记录、给出带行号证据的复盘，还能把脱敏后的诊断包导出成 bug 报告材料。查更早的会话就把 session id 一起给它。这是个值得抄作业的设计：框架越大越需要自证清白的工具，否则出了问题只能靠猜。&lt;/p&gt;
&lt;h2&gt;理念：四条&lt;/h2&gt;
&lt;p&gt;Superpowers 的哲学部分只有四条，但每条都在工作流里有对应物：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;理念&lt;/th&gt;
&lt;th&gt;落地方式&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;测试先行（TDD）&lt;/td&gt;
&lt;td&gt;永远先写测试；先写实现再补测试的，删掉&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;系统化胜过临时发挥&lt;/td&gt;
&lt;td&gt;用流程代替猜测，调试有四阶段根因法&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;降低复杂度&lt;/td&gt;
&lt;td&gt;简单是首要目标，YAGNI 与 DRY 写进计划环节&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;证据胜过声明&lt;/td&gt;
&lt;td&gt;宣布完成前必须验证，审查按严重程度分级&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
两个使用前要知道的点。第一，遥测：头脑风暴的可选可视化伴侣默认会从作者网站加载 Prime Radiant 的 logo，加载请求只带 Superpowers 的版本号，不带你的项目、提示词或宿主信息；介意的话设环境变量 &lt;code&gt;SUPERPOWERS_DISABLE_TELEMETRY&lt;/code&gt; 为任意真值即可关闭（它也尊重 Claude Code 的 DISABLE_TELEMETRY 等退出开关）。第二，流程是有重量的：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;七步工作流是给正经项目准备的&amp;lt;/span&amp;gt;，改个文案、写个一次性小脚本时，全套头脑风暴加计划加子代理审查会显得杀鸡用牛刀——它适合「要做对」的事，不适合「随手试试」的事。
:::&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;技能不触发。&lt;/strong&gt; 先确认宿主的启动钩子真的生效：多数宿主要在安装后重启会话，钩子没加载，using-superpowers 就没注入，技能自然不会自动触发。用前述 react todo list 的方法验证。Hermes 还有一个已知坑：它没有压缩后钩子，超长会话一旦把第一轮压缩掉，启动指令会丢，技能停止触发——开新会话即可。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;装了多个宿主，只有一个生效。&lt;/strong&gt; 这是设计如此：每个宿主独立安装、独立更新。在 Claude Code 里装好，不等于 Codex 里也有，要逐个装。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;更新后行为变怪。&lt;/strong&gt; 先跑一遍 diagnosing-superpowers 复盘当前会话，确认是技能行为问题还是模型问题；再检查版本（各宿主用自己的插件 update 命令升级），很多「突然不好用」其实是新旧版本技能混杂。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;想贡献新技能。&lt;/strong&gt; 官方明确说一般不接受新技能贡献，且任何技能更新必须在全部支持的宿主上都能工作；Agent 代写的、修别人 issue 的 PR 也不收（除非维护者点名）。提问题走 issue 区，把复盘材料附上比直接甩 PR 更受欢迎。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Superpowers 证明了一件事：让编程 Agent 可靠干活，靠的不是更长的提示词，而是流程。它用一组技能把「先想清楚、再拆计划、测试先行、逐个审查」焊进 17 种宿主的默认行为，让不同 Agent 共享同一套工程纪律。对已经在用 Claude Code、Codex 或 Muse 的人，它是目前最值得一装的技能框架；装完用那句 react todo list 验一下，Agent 先跟你聊需求而不是先写代码，你就知道它在工作了。&lt;/p&gt;
</content:encoded></item><item><title>CloudDrive2：把各家云盘挂载成一块本地磁盘</title><link>https://www.anexns.cloudns.org/posts/clouddrive-clouddrive2/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/clouddrive-clouddrive2/</guid><description>把阿里云盘、百度网盘、115、OneDrive 等账号统一接入一台常开的 NAS 或电脑，挂载成本地磁盘并对外提供 WebDAV：含 Docker Compose 部署、FUSE 挂载要点与免费和付费的边界说明。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说场景：NAS 上躺着五个网盘账号，却没有一块「盘」&lt;/h2&gt;
&lt;p&gt;先描一个很多人都有的画面：一台 NAS 在家里 24 小时开着，上面的硬盘还空着大半；与此同时，你的文件散在各家云盘里——照片在阿里云盘，课程在百度网盘，影音收藏在 115，工作文件在 OneDrive 里同步。每个盘一个客户端、一个网页，想找个文件先要想「它到底在哪个盘里」。更别扭的是 NAS 本地的软件够不着这些文件：想让 NAS 上的播放器直接播云盘里的电影，或者让下载工具把文件存进某个云盘，都得先下载到本地、再上传回去，中转一遍。&lt;/p&gt;
&lt;p&gt;真正想要的其实很朴素：&lt;strong&gt;让这些云盘在 NAS 上看起来就是一块本地硬盘&lt;/strong&gt;，任何软件打开路径就能读、就能写，不用关心背后是哪家的账号。CloudDrive2 走的就是这条路线：它的核心服务跑在一台常开的机器上，把各家云盘账号统一接入，再挂载成本地磁盘或本地目录；顺带它自己还是一个 WebDAV 服务器，局域网里其他设备也能直接读这些云盘的内容。这一篇就把它讲清楚：怎么装、怎么挂、免费和收费的界线在哪、和 OpenList 那类工具到底有什么区别。&lt;/p&gt;
&lt;p&gt;项目地址：https://www.clouddrive2.com（官网）&lt;/p&gt;
&lt;h2&gt;先把性质说清楚：它不是开源软件&lt;/h2&gt;
&lt;p&gt;这一点必须放在最前面，免得装完才发现路线不对：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;CloudDrive2 是闭源的免费增值软件，代码不公开、没有可审计的开源仓库，把主力云盘账号的授权交给它之前，信任成本要先算清楚。&amp;lt;/span&amp;gt;它的账号接入走扫码或 OAuth 登录，官方口径是只保存密码哈希、不保存可解密的凭据，但闭源软件的这类承诺无法像开源项目那样由社区逐行验证——这是它和本系列其他工具最根本的区别，介意这一点的读者可以直接看开源路线的 &lt;a href=&quot;/posts/clouddrive-openlist/&quot;&gt;OpenList&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;作为交换，它把「挂载」这件事做成了开箱即用的成品：不用拼命令行、不用调 FUSE 参数，图形界面里点几下就能把云盘变成一块盘。所以它的定位可以一句话说清：&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;CloudDrive2 卖的不是存储，而是「把云盘变成本地磁盘」这层挂载体验——存储还是各家云盘的，它只负责让本地系统把云盘当硬盘用。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;它是怎么工作的：核心服务＋挂载层＋WebDAV&lt;/h2&gt;
&lt;p&gt;CloudDrive2 的结构分三层，理解了这三层，后面的部署和排障都有谱：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;核心服务（Core）&lt;/strong&gt;：一个常驻后台服务，跑在 Windows、Linux、macOS、NAS 或 Docker 里。它负责登录并维持各家云盘账号、处理文件的读写转发，是整套东西的心脏，机器关机它就停摆，所以要装在常开设备上。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;管理界面（Web UI）&lt;/strong&gt;：核心服务的唯一控制台，浏览器打开 &lt;code&gt;http://&amp;lt;主机&amp;gt;:19798&lt;/code&gt; 就是它。加账号、设挂载点、看传输队列、开 WebDAV、管 API Token，全在这里完成。另有一个 HTTPS 端口 &lt;code&gt;19799&lt;/code&gt;，默认关闭，需要在设置里手动开启并配置证书。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;挂载层&lt;/strong&gt;：把云盘变成本地磁盘的那一层，各平台实现不同——Linux 靠 FUSE，Windows 靠 WinFsp 挂成盘符，macOS 靠 macFUSE。挂载之后，云盘在系统里就是一个普通目录或盘符，播放器、编辑器、脚本都照常访问。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;接入范围方面，它支持的云存储包括阿里云盘、百度网盘、115、123 网盘、天翼云盘、迅雷、光鸭、OneDrive、Google Drive，以及 S3、WebDAV、SFTP、FTP、SMB 和本地文件夹。组织方式有三种：多个云盘&lt;strong&gt;合并成一棵目录树&lt;/strong&gt;（看起来像一块大盘）、每个云盘&lt;strong&gt;各挂各的&lt;/strong&gt;（各占一个目录或盘符）、或者&lt;strong&gt;只挂某个云盘里的单个文件夹&lt;/strong&gt;（比如只把「电影」目录挂出来给播放器用）。&lt;/p&gt;
&lt;p&gt;最后一个身份是 &lt;strong&gt;WebDAV 服务器&lt;/strong&gt;：地址 &lt;code&gt;http://&amp;lt;主机&amp;gt;:19798/dav&lt;/code&gt;，在 Web UI 里开启并设好账号后，局域网里的播放器、文件管理器、备份工具都能用标准 WebDAV 协议直接读所有已接入的云盘，不必在每个应用里再逐个登录各家账号。&lt;/p&gt;
&lt;h2&gt;路线一：Docker Compose 装在 NAS／Linux 上（主线）&lt;/h2&gt;
&lt;p&gt;Docker 是 NAS 和 Linux 服务器上最常见的装法，镜像为官方的 &lt;code&gt;cloudnas/clouddrive2&lt;/code&gt;。但它和普通容器有个关键区别：&lt;strong&gt;要在宿主机上产生真实的挂载点，就必须把 FUSE 设备和挂载传播打通&lt;/strong&gt;，这一节的配置都是围绕这件事。&lt;/p&gt;
&lt;p&gt;先在宿主机上确认 FUSE 可用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ls -l /dev/fuse
# 输出类似 crw-rw-rw- 1 root root 10, 229 ... /dev/fuse 即表示内核 FUSE 可用
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后写 &lt;code&gt;docker-compose.yml&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  clouddrive2:
    image: cloudnas/clouddrive2
    container_name: clouddrive2
    restart: unless-stopped
    devices:
      - /dev/fuse:/dev/fuse        # 把 FUSE 设备交给容器，挂载的前提
    cap_add:
      - SYS_ADMIN                   # 执行 mount 动作需要的权限
    security_opt:
      - apparmor:unconfined
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/CloudNAS/data       # 配置与账号数据，务必持久化
      # 挂载点目录：必须用 shared 挂载传播，容器里的挂载才能传回宿主机
      - type: bind
        source: /mnt/cloud
        target: /CloudNAS/mount
        bind:
          propagation: shared
    ports:
      - &quot;19798:19798&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动并看日志确认核心服务正常：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose logs -f clouddrive2
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;http://&amp;lt;NAS 的 IP&amp;gt;:19798&lt;/code&gt;，首次访问按提示注册管理员账号并登录，就进入控制台了。&lt;/p&gt;
&lt;p&gt;:::warning
Docker 装法最常见的坑就是挂载传播：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;宿主机上用作挂载点的目录没有开启 shared 挂载传播时，容器内部的挂载无法传回宿主机，表现就是挂载直接失败，或者 Web UI 里显示已挂载、宿主机目录里却空空如也。&amp;lt;/span&amp;gt;上面 Compose 里给挂载目录单独写 &lt;code&gt;propagation: shared&lt;/code&gt; 就是为了避开它；如果不用 Compose 的长语法，也可以在宿主机上先执行 &lt;code&gt;mount --make-shared /mnt/cloud&lt;/code&gt; 再启动容器。另外确认 &lt;code&gt;/dev/fuse&lt;/code&gt; 存在、容器拿到了 &lt;code&gt;SYS_ADMIN&lt;/code&gt;，三件套缺一件挂载都起不来。
:::&lt;/p&gt;
&lt;p&gt;顺带提醒信任层面的另一面：配置目录（上面 Compose 的 &lt;code&gt;./data&lt;/code&gt;）里存着各家云盘的登录态，它就是你所有云盘的钥匙串，备份和权限都要按敏感数据对待，不要随手打包分享出去。&lt;/p&gt;
&lt;h2&gt;路线二：Windows／macOS 桌面版（概述）&lt;/h2&gt;
&lt;p&gt;如果常开的机器是 Windows 电脑，官网提供原生桌面版：安装包内置了核心服务和 WinFsp 驱动（均为签名版本），核心服务会注册成 Windows 系统服务、随开机自启，登录与否都在后台运行；桌面 App 只是它的界面入口。装好后同样打开 &lt;code&gt;http://localhost:19798&lt;/code&gt; 管理，挂载时可以选择挂成盘符（比如 &lt;code&gt;Z:&lt;/code&gt;）或挂进一个空文件夹，也可以设为开机自动挂载、只读挂载。资源管理器里看到的云盘和本地盘没有区别，任何软件都能直接打开里面的文件。&lt;/p&gt;
&lt;p&gt;macOS 版要特别注意版本区别：&lt;strong&gt;只有官网下载的直装版带本地挂载功能&lt;/strong&gt;，它依赖 macFUSE（需提前安装，并在系统设置里按指引放行其系统扩展，Apple 芯片机型还要按官网说明走一遍恢复模式的放行流程）；&lt;strong&gt;App Store 版因为沙盒限制没有本地挂载&lt;/strong&gt;，只能在 App 内浏览。装错版本是最常见的「为什么我没有挂载按钮」的原因。&lt;/p&gt;
&lt;h2&gt;接入第一个云盘并挂载&lt;/h2&gt;
&lt;p&gt;部署完成后的操作都在 Web UI 里，流程是四步：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;添加云存储&lt;/strong&gt;：在控制台里选「添加云存储」，从列表里选云盘类型（阿里云盘、百度网盘、OneDrive 等），或选 WebDAV、S3、SMB、本地文件夹这类通用协议。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;完成授权&lt;/strong&gt;：国内网盘多为扫码登录，OneDrive、Google Drive 走 OAuth 跳转授权。授权信息只保存在本机核心服务里。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;设置挂载点&lt;/strong&gt;：在挂载管理里给这个云盘选一个挂载位置——宿主机目录（Docker 路线对应上面 Compose 里的挂载目录）、Windows 盘符或 macOS 目录；决定它和别的云盘合并成一棵树，还是独立成盘；只想暴露部分内容时，就只选某个子文件夹挂载。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;验证&lt;/strong&gt;：回到宿主机看挂载点是否出现文件：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;ls /mnt/cloud
df -h | grep cloud
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;能列出云盘里的目录、其他软件能直接打开里面的文件，挂载这一关就过了。之后在 Web UI 里还能看传输队列、给 WebDAV 设独立账号、生成 API Token 给其他程序调用。&lt;/p&gt;
&lt;h2&gt;WebDAV 用法与公网警告&lt;/h2&gt;
&lt;p&gt;把 CloudDrive2 当 WebDAV 服务器用，适合这类场景：电视上的播放器要读 115 里的电影、手机文件管理器想统一看所有云盘、备份工具要把文件写进某个云盘。在 Web UI 的 WebDAV 设置里开启服务并设好用户名密码，客户端统一填：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;服务器地址：http://&amp;lt;运行 CloudDrive2 的主机 IP&amp;gt;:19798/dav
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;各家云盘会以目录形式出现在这个 WebDAV 根下，一次登录全都能读。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;但 19798 默认是 HTTP 明文，这个管理界面和 WebDAV 只应该在局域网或自己的组网内使用，绝不要把端口直接映射到公网&amp;lt;/span&amp;gt;；确有外网访问需求，要么在设置里开启 19799 并配好证书，要么在前面套一层带 HTTPS 的反向代理。&lt;/p&gt;
&lt;h2&gt;一个必须知道的限制：流量经过本机转发&lt;/h2&gt;
&lt;p&gt;CloudDrive2 的 Web 界面和挂载读取&lt;strong&gt;不走各家云盘的官方直链&lt;/strong&gt;，数据要经过运行核心服务的那台机器转发。好处是兼容性统一、什么客户端都能读；代价是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;那台机器的带宽和性能就是全屋云盘访问的速度上限&amp;lt;/span&amp;gt;：NAS 只有千兆网口、或者机器本身性能弱，大文件拖动、4K 播放卡顿都可能出在这里，而不是云盘在限速。把它部署在网络位置好、性能够用的常开机器上，这条限制基本无感；装在一台老旧的低功耗盒子上，就要有心理预期。&lt;/p&gt;
&lt;h2&gt;免费与付费的边界&lt;/h2&gt;
&lt;p&gt;CloudDrive2 是免费增值模式，先把界线摆清楚再决定要不要用：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;功能&lt;/th&gt;
&lt;th&gt;免费可用&lt;/th&gt;
&lt;th&gt;需要付费&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;接入云盘账号、本地挂载&lt;/td&gt;
&lt;td&gt;✓&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Web UI 管理界面&lt;/td&gt;
&lt;td&gt;✓&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;基础 WebDAV 服务&lt;/td&gt;
&lt;td&gt;✓&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;媒体库服务（影视／音乐／图书库，核心 1.2.0 起）&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;App Pro＋核心订阅&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;客户端 App 连接服务器等高级用法&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;App Pro＋核心订阅&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;核心订阅分月付、年付和终身（Lifetime）几档，要注意 &lt;strong&gt;Lifetime Lite 不包含媒体库服务&lt;/strong&gt;，冲着影音库去买终身版的话别买错档位。对大多数人来说，只做「挂载成本地盘＋WebDAV 给局域网用」，免费范围已经完整够用；付费主要买的是媒体库那套海报墙、刮削与跨设备服务体验。&lt;/p&gt;
&lt;h2&gt;与 OpenList／Alist 的路线对比&lt;/h2&gt;
&lt;p&gt;本系列里的 &lt;a href=&quot;/posts/selfhost-alist/&quot;&gt;Alist&lt;/a&gt; 和 &lt;a href=&quot;/posts/clouddrive-openlist/&quot;&gt;OpenList&lt;/a&gt; 常被拿来和 CloudDrive2 比，其实三者解决的不是同一个问题：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;CloudDrive2&lt;/th&gt;
&lt;th&gt;OpenList／Alist&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;本质&lt;/td&gt;
&lt;td&gt;挂载工具：把云盘变成本地磁盘&lt;/td&gt;
&lt;td&gt;聚合站：把云盘变成一个网页文件站&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;开源情况&lt;/td&gt;
&lt;td&gt;闭源商业软件&lt;/td&gt;
&lt;td&gt;开源（AGPL），可自托管审计&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;主要入口&lt;/td&gt;
&lt;td&gt;本地文件系统（目录／盘符）＋Web UI&lt;/td&gt;
&lt;td&gt;浏览器网页＋WebDAV&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本地软件直接读写云盘&lt;/td&gt;
&lt;td&gt;✓ 挂载后任意软件可用&lt;/td&gt;
&lt;td&gt;✗ 以网页浏览、下载、分享为主&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;分享给别人&lt;/td&gt;
&lt;td&gt;弱项，不是为公开分享设计&lt;/td&gt;
&lt;td&gt;强项，直链、分享页、访客权限齐全&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;部署形态&lt;/td&gt;
&lt;td&gt;常开机器上的核心服务（桌面／Docker）&lt;/td&gt;
&lt;td&gt;Docker 或单二进制，门槛低&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;费用&lt;/td&gt;
&lt;td&gt;基础免费，高级功能订阅制&lt;/td&gt;
&lt;td&gt;免费&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一句话分工：**要让本地软件「以为云盘就是硬盘」，选 CloudDrive2；要在浏览器里浏览、整理、分享各家网盘，选 OpenList／Alist。**两者也可以叠着用——OpenList 管分享，CloudDrive2 管本地挂载，互不冲突。&lt;/p&gt;
&lt;h2&gt;排障小节&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Docker 里挂载失败或挂载点为空&lt;/strong&gt;：按顺序查三样——宿主机 &lt;code&gt;ls -l /dev/fuse&lt;/code&gt; 确认 FUSE 存在；&lt;code&gt;findmnt -o TARGET,PROPAGATION /mnt/cloud&lt;/code&gt; 确认挂载目录的传播方式是 shared；Compose 里 &lt;code&gt;SYS_ADMIN&lt;/code&gt; 和 &lt;code&gt;apparmor:unconfined&lt;/code&gt; 有没有漏。九成问题出在这三处。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Web UI 打不开&lt;/strong&gt;：先看容器是否在跑（&lt;code&gt;docker compose ps&lt;/code&gt;）、日志有没有报错，再确认 19798 端口没有被其他程序占用、防火墙放行了该端口。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;macOS 没有挂载功能&lt;/strong&gt;：基本是装成了 App Store 版。卸掉，改装官网直装版，并提前装好 macFUSE、按指引放行系统扩展。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;播放或打开大文件卡顿&lt;/strong&gt;：先想起「流量经过本机转发」这条限制——测一下 NAS 到播放设备之间的局域网速度，卡顿多半是本机网口或 Wi-Fi 的问题，不是云盘的问题。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;云盘登录失效、目录刷不出来&lt;/strong&gt;：多为授权过期，回 Web UI 对该账号重新扫码或重新 OAuth 授权即可；频繁掉授权时检查核心服务所在机器的系统时间是否准确，时间漂移会让 OAuth 令牌校验失败。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;挂载盘符／目录突然消失&lt;/strong&gt;：核心服务停止或机器休眠都会让挂载失效。确认服务随开机自启、常开机器关闭自动休眠，Docker 路线则确认容器是 &lt;code&gt;unless-stopped&lt;/code&gt; 且宿主机重启后能自动拉起。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;CloudDrive2 的路线在网盘系列里是独一份：别人做的是「网盘的网页」，它做的是「云盘的本地盘」。家里有一台常开的 NAS 或电脑、云盘账号又多，它能把这些账号收成一块随取随用的本地磁盘，再顺手用 WebDAV 喂给全屋设备，免费范围就覆盖了这套核心体验。代价也要认：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;闭源意味着信任只能给不能验，介意这一点、或更想要命令行式的完全掌控，可以看同系列的 &lt;a href=&quot;/posts/clouddrive-rclone/&quot;&gt;Rclone&lt;/a&gt; 用开源工具自己拼出同样的挂载效果。&amp;lt;/span&amp;gt;选工具先选路线，路线对了，剩下的都是配置细节。&lt;/p&gt;
</content:encoded></item><item><title>dufs：一个二进制就是一台带 WebDAV 的文件服务器</title><link>https://www.anexns.cloudns.org/posts/clouddrive-dufs/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/clouddrive-dufs/</guid><description>不装数据库、不写配置文件，一条命令把任意目录变成能上传、能搜索、能断点续传、还能当 WebDAV 用的文件站——Rust 写的单二进制 dufs 部署与权限实战。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说主线：一条命令，目录就成了文件站&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;dufs -A /srv/share
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;就这一行。&lt;code&gt;/srv/share&lt;/code&gt; 立刻变成一个带网页界面的文件站：浏览器打开能浏览、拖拽上传、打包下载，同一个地址还是一个 WebDAV 服务端，电脑和手机可以直接挂载。没有数据库要装，没有配置文件要先写，没有运行时要配——dufs 是 Rust 写的一个单二进制文件，这就是它和传统网盘最大的区别：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;别的网盘是「部署一套系统」，dufs 是「运行一个命令」&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/sigoden/dufs&lt;/p&gt;
&lt;p&gt;它适合的场景很明确：临时给同事传一批文件、把服务器上某个目录开放给自己远程取用、给下载站当静态文件源、内网里快速起一个带权限的共享盘。它不做用户注册、不做相册、不做在线文档——那些是 &lt;a href=&quot;/posts/selfhost-cloudreve/&quot;&gt;Cloudreve&lt;/a&gt; 和 Nextcloud 的活。dufs 只做文件服务本身，并且把这一件事做到了极简。&lt;/p&gt;
&lt;h2&gt;它能干什么&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;静态文件服务&lt;/strong&gt;：目录浏览、单文件分发，也可以托管静态站点。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;上传与编辑&lt;/strong&gt;：拖拽上传文件和文件夹，网页里新建、编辑、删除、重命名、搜索文件。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;打包下载&lt;/strong&gt;：整个文件夹一键打成 zip 下载。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;断点续传&lt;/strong&gt;：上传和下载都支持断点续传，传大文件断了不用重来。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;访问控制&lt;/strong&gt;：按账号、按目录粒度设置只读/读写权限，支持匿名公开指定目录。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;WebDAV&lt;/strong&gt;：同一端口直接提供 WebDAV，系统自带的文件管理器就能挂载。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;HTTPS&lt;/strong&gt;：参数直接指定证书就能上 HTTPS，不强制依赖反向代理。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;curl 友好&lt;/strong&gt;：全部功能都有对应的 HTTP 接口，脚本里一行 curl 就能上传下载。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;默认监听端口是 &lt;code&gt;5000&lt;/code&gt;。最关键的一条默认行为：&lt;strong&gt;不开任何 &lt;code&gt;--allow-*&lt;/code&gt; 参数时，dufs 是纯只读的&lt;/strong&gt;，访客只能看和下载；写操作必须显式打开，这个默认值对公网暴露非常友好。&lt;/p&gt;
&lt;h2&gt;安装：四种方式，任选其一&lt;/h2&gt;
&lt;h3&gt;方式一：下载官方二进制（最推荐）&lt;/h3&gt;
&lt;p&gt;去 GitHub Releases 下载对应平台的压缩包，解压后把 &lt;code&gt;dufs&lt;/code&gt; 放进 PATH 即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 以 Linux x86_64 为例，版本号以 Releases 页面最新为准
tar -xzf dufs-*.tar.gz
sudo install -m 755 dufs /usr/local/bin/
dufs --version
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;方式二：cargo 安装&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;cargo install dufs
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;方式三：Homebrew（macOS / Linux）&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;brew install dufs
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;方式四：Docker&lt;/h3&gt;
&lt;p&gt;官方镜像 &lt;code&gt;sigoden/dufs&lt;/code&gt;，一条命令跑起来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d --name dufs \
  -v /srv/share:/data \
  -p 5000:5000 \
  --restart unless-stopped \
  sigoden/dufs /data -A
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意容器里的数据目录是挂载进去的 &lt;code&gt;/data&lt;/code&gt;，命令最后的 &lt;code&gt;/data -A&lt;/code&gt; 是传给 dufs 的参数：服务这个目录，并打开全部操作权限。生产环境不要照抄这个 &lt;code&gt;-A&lt;/code&gt;，权限怎么收，见下面权限一节。&lt;/p&gt;
&lt;h2&gt;快速上手：从只读到可写&lt;/h2&gt;
&lt;p&gt;只读分享一个目录（最安全的起步姿势）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;dufs /srv/share
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;打开全部操作（上传、删除、搜索、新建、编辑）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;dufs -A /srv/share
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;不想一把全开，可以逐项打开，这是更推荐的粒度：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;dufs /srv/share \
  --allow-upload \
  --allow-delete \
  --allow-search \
  --allow-archive
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;常用启动参数：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;dufs /srv/share -b 127.0.0.1 -p 8080        # 只绑本机、换端口
dufs /srv/share --path-prefix /files        # 挂到 /files 前缀下，方便反代
dufs /srv/share --hidden &apos;.git,*.log,tmp&apos;   # 目录列表里隐藏这些路径
dufs /srv/share --render-index              # 目录下有 index.html 时当静态站托管
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;权限规则：-a 一条参数管全部&lt;/h2&gt;
&lt;p&gt;dufs 的访问控制全靠 &lt;code&gt;-a&lt;/code&gt;（&lt;code&gt;--auth&lt;/code&gt;）参数，格式是：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;账号:密码@路径1:权限,路径2:权限
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;@&lt;/code&gt; 前面是账号密码，匿名访客不写账号、直接写 &lt;code&gt;@/&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;路径后缀 &lt;code&gt;:rw&lt;/code&gt; 表示读写、&lt;code&gt;:ro&lt;/code&gt; 表示只读，&lt;code&gt;:ro&lt;/code&gt; 可以省略（不写后缀默认只读）。&lt;/li&gt;
&lt;li&gt;一条命令可以写多个 &lt;code&gt;-a&lt;/code&gt;，每个账号、每组路径各一条规则。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;实际例子：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 管理员全站读写，访客只能看 /public，且必须登录
dufs /srv/share -A \
  -a &apos;admin:强密码@/:rw&apos; \
  -a &apos;guest:guest123@/public&apos;

# 完全公开只读（任何人免登录浏览下载）
dufs /srv/share -a &apos;@/&apos;

# 某账号对根目录读写、但对 /private 只读
dufs /srv/share -A \
  -a &apos;alice:密码@/:rw,/private:ro&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;有一条容易踩的上下级关系必须记住：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;code&gt;--allow-*&lt;/code&gt; 全局开关是权限上限，账号规则里的 &lt;code&gt;:rw&lt;/code&gt; 突破不了它&amp;lt;/span&amp;gt;。比如你没加 &lt;code&gt;--allow-upload&lt;/code&gt;，哪怕给 admin 配了 &lt;code&gt;:rw&lt;/code&gt;，他也传不了文件——想让人能写，先开全局开关，再在账号规则里收口子。&lt;/p&gt;
&lt;h3&gt;密码用哈希，别写明文&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;-a&lt;/code&gt; 支持 sha-512 哈希密码（&lt;code&gt;$6$&lt;/code&gt; 开头），先生成再填进去：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;openssl passwd -6 &apos;你的密码&apos;
# 输出形如 $6$xxxxxxxx$yyyyyyyy....
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;dufs /srv/share -A -a &apos;admin:$6$xxxxxxxx$yyyyyyyy....@/:rw&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个注意点：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;哈希串里有 &lt;code&gt;$&lt;/code&gt;，写进命令时必须用单引号包住，防 shell 把它当变量展开&amp;lt;/span&amp;gt;；另外哈希密码下 Digest 认证不可用，客户端请走 Basic 认证。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;strong&gt;&lt;code&gt;-A&lt;/code&gt; 全开放绝对不要裸奔公网。&lt;/strong&gt; &lt;code&gt;-A&lt;/code&gt; 意味着上传、删除、编辑全部打开，如果再不配 &lt;code&gt;--auth&lt;/code&gt;，任何人扫到你的 5000 端口就能往你硬盘里写文件、删文件。公网使用只有两种正确姿势：要么 &lt;code&gt;-A&lt;/code&gt; 加完整的 &lt;code&gt;-a&lt;/code&gt; 账号规则，要么只绑 &lt;code&gt;127.0.0.1&lt;/code&gt; 再走反向代理加认证。图省事裸奔，被人当免费图床和跳板只是时间问题。
:::&lt;/p&gt;
&lt;h2&gt;参数速查表&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;默认&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-p, --port&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;监听端口&lt;/td&gt;
&lt;td&gt;&lt;code&gt;5000&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-b, --bind&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;绑定地址，可绑多个或 Unix socket&lt;/td&gt;
&lt;td&gt;全部地址&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-A, --allow-all&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;打开全部操作（上传/删除/搜索/打包等）&lt;/td&gt;
&lt;td&gt;关&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--allow-upload&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;允许上传&lt;/td&gt;
&lt;td&gt;关&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--allow-delete&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;允许删除&lt;/td&gt;
&lt;td&gt;关&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--allow-search&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;允许搜索&lt;/td&gt;
&lt;td&gt;关&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--allow-archive&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;允许文件夹打包下载&lt;/td&gt;
&lt;td&gt;关&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--allow-symlink&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;允许符号链接指向根目录外&lt;/td&gt;
&lt;td&gt;关&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-a, --auth&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;账号与路径权限规则，可多次使用&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--hidden&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;目录列表中隐藏的路径（逗号分隔，支持通配）&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--path-prefix&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;URL 路径前缀&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--tls-cert&lt;/code&gt; / &lt;code&gt;--tls-key&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;HTTPS 证书与私钥&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-c, --config&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;指定 YAML 配置文件&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--render-index&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;目录请求时返回 index.html（静态站模式）&lt;/td&gt;
&lt;td&gt;关&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--render-spa&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;单页应用模式&lt;/td&gt;
&lt;td&gt;关&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--log-file&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;访问日志写入文件&lt;/td&gt;
&lt;td&gt;输出到终端&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;所有参数都可以用 &lt;code&gt;DUFS_&lt;/code&gt; 前缀的环境变量代替（比如 &lt;code&gt;DUFS_PORT=5000&lt;/code&gt;、&lt;code&gt;DUFS_AUTH=...&lt;/code&gt;），参数多起来后更推荐写配置文件，下一节就讲。&lt;/p&gt;
&lt;h2&gt;长期运行：systemd 托管 + 配置文件&lt;/h2&gt;
&lt;p&gt;临时用用命令行足够；要常驻，按老规矩交给 systemd。先把启动参数收进一份 YAML 配置文件 &lt;code&gt;/etc/dufs/config.yaml&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;serve-path: /srv/share
bind: 127.0.0.1
port: 5000
allow-upload: true
allow-delete: true
allow-search: true
allow-archive: true
hidden: .git,*.log
auth:
  - admin:强密码@/:rw
  - guest:guest123@/public:ro
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再写 unit 文件 &lt;code&gt;/etc/systemd/system/dufs.service&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Unit]
Description=dufs file server
After=network.target

[Service]
ExecStart=/usr/local/bin/dufs -c /etc/dufs/config.yaml
Restart=on-failure
User=dufs
Group=dufs

[Install]
WantedBy=multi-user.target
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl daemon-reload
sudo systemctl enable --now dufs
systemctl status dufs
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;绑 &lt;code&gt;127.0.0.1&lt;/code&gt; 再用 Nginx/Caddy 反代出去、套上域名和 HTTPS，是自建服务的标准入口做法；dufs 自己也能直接上 HTTPS：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;dufs /srv/share --tls-cert /path/fullchain.pem --tls-key /path/privkey.pem
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;WebDAV：同一个地址直接挂载&lt;/h2&gt;
&lt;p&gt;不用额外配置，dufs 的服务地址本身就是 WebDAV 端点：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;http://你的域名:5000/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Windows 资源管理器、macOS Finder、手机文件 App 添加网络位置/服务器时填这个地址，再填 &lt;code&gt;-a&lt;/code&gt; 里配的账号密码即可。需要提醒的是，WebDAV 的读写同样受 &lt;code&gt;--allow-*&lt;/code&gt; 全局开关和账号规则约束：只读模式起的服务，挂载上去也只能读。&lt;/p&gt;
&lt;p&gt;和本系列上一篇 &lt;a href=&quot;/posts/clouddrive-davflare/&quot;&gt;Davflare&lt;/a&gt; 对比一下就有意思了：Davflare 是把 WebDAV 放在 Cloudflare 边缘、文件存 R2，零服务器但单文件有上限；dufs 是把 WebDAV 放在自己机器上，文件就在本地硬盘，没有单文件限制，代价是机器得自己开着。两者一个云上一个本地，正好互补。&lt;/p&gt;
&lt;h2&gt;curl API：脚本里传文件全靠它&lt;/h2&gt;
&lt;p&gt;dufs 对 curl 极其友好，常用操作各一行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 上传文件
curl -T local-file.zip http://127.0.0.1:5000/dir/remote-file.zip

# 下载文件
curl -O http://127.0.0.1:5000/dir/remote-file.zip

# 文件夹打包下载
curl -o dir.zip &apos;http://127.0.0.1:5000/dir?zip&apos;

# 删除文件
curl -X DELETE http://127.0.0.1:5000/dir/file.txt

# 新建目录
curl -X MKCOL http://127.0.0.1:5000/new-dir

# 移动/重命名
curl -X MOVE http://127.0.0.1:5000/old.txt -H &apos;Destination: http://127.0.0.1:5000/new.txt&apos;

# 搜索与列表
curl &apos;http://127.0.0.1:5000/?q=报告&apos;        # 按名搜索
curl &apos;http://127.0.0.1:5000/dir?json&apos;       # JSON 格式列目录

# 取文件 sha256
curl &apos;http://127.0.0.1:5000/file.iso?hash&apos;

# 带账号密码
curl -T file.zip --user admin:密码 http://127.0.0.1:5000/file.zip
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;断点续传下载用 &lt;code&gt;curl -C -&lt;/code&gt;；断点续传上传走 PATCH 加偏移头：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 先查已上传的字节数，再从断点接着传
upload_offset=$(curl -I -s http://127.0.0.1:5000/file | tr -d &apos;\r&apos; | sed -n &apos;s/content-length: //p&apos;)
dd skip=$upload_offset if=file status=none ibs=1 | \
  curl -X PATCH -H &apos;X-Update-Range: append&apos; --data-binary @- http://127.0.0.1:5000/file
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;健康检查端点是现成的，监控可以直接探：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl http://127.0.0.1:5000/__dufs__/health
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;和其他方案的分工&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;需求&lt;/th&gt;
&lt;th&gt;更合适&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;临时分享一个目录、快速起文件站&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;dufs&lt;/strong&gt;（本篇）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;长期私人网盘、分享链接、存储策略&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;/posts/selfhost-cloudreve/&quot;&gt;Cloudreve&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;给一堆既有存储（S3/WebDAV/SFTP）套统一网页界面&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;/posts/clouddrive-filestash/&quot;&gt;Filestash&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;零服务器、文件放云端对象存储&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;/posts/clouddrive-davflare/&quot;&gt;Davflare&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一句话：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;dufs 是文件服务器里的「瑞士军刀小刀」——不替代正经网盘，但任何需要「马上把目录开放出来」的场合，它都是最快的答案。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;排障清单&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;网页能看但传不了文件&lt;/strong&gt;：没开 &lt;code&gt;--allow-upload&lt;/code&gt;（或没用 &lt;code&gt;-A&lt;/code&gt;）。记住全局开关是上限，先开开关再谈账号权限。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;账号明明配了 &lt;code&gt;:rw&lt;/code&gt; 还是只读&lt;/strong&gt;：同上，多半是对应的 &lt;code&gt;--allow-*&lt;/code&gt; 没开；或者路径规则写错——路径是相对服务根目录的，且更具体的路径规则优先生效。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;登录一直失败&lt;/strong&gt;：哈希密码的命令没加单引号，被 shell 展开坏了；或者客户端在用 Digest 认证而你用的是哈希密码，改走 Basic。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;挂载 WebDAV 能连但写不进去&lt;/strong&gt;：检查 &lt;code&gt;--allow-upload&lt;/code&gt; 与账号对该路径是否有 &lt;code&gt;:rw&lt;/code&gt;；另外确认客户端填的是服务根地址而不是某个子目录的分享链接。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Docker 里挂载的目录在网页上是空的&lt;/strong&gt;：宿主机目录权限问题，或 &lt;code&gt;-v&lt;/code&gt; 路径写错；容器内以 root 运行一般能读，先 &lt;code&gt;docker exec&lt;/code&gt; 进去 &lt;code&gt;ls /data&lt;/code&gt; 确认。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;反代后上传大文件失败&lt;/strong&gt;：反向代理的请求体大小限制（Nginx 的 &lt;code&gt;client_max_body_size&lt;/code&gt;）在拦，把它调到与需求匹配或关掉。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;端口冲突/起不来&lt;/strong&gt;：&lt;code&gt;ss -tlnp | grep 5000&lt;/code&gt; 看谁占着，换 &lt;code&gt;-p&lt;/code&gt; 端口即可。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;dufs 把文件服务压缩到了极限：一个二进制、一条命令、零依赖，静态托管、上传下载、断点续传、权限规则、WebDAV、HTTPS 全都在里面。它不会取代 Cloudreve、Nextcloud 这类正经网盘，但作为「随手把目录变文件站」的工具，目前很难找到第二个这么利落的。用的时候只记一条铁律：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;开写权限必配账号规则，&lt;code&gt;-A&lt;/code&gt; 永不裸奔&amp;lt;/span&amp;gt;——守住这条，dufs 就是你可以放心常驻在服务器上的小工具。&lt;/p&gt;
</content:encoded></item><item><title>Filestash：不搬家，给现有存储换个网页门面</title><link>https://www.anexns.cloudns.org/posts/clouddrive-filestash/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/clouddrive-filestash/</guid><description>文件已经躺在 SFTP、S3、SMB 里，为什么还要再装一个网盘？Filestash 本身不存文件，它给所有已有存储套上同一个网页界面，还能反向以 WebDAV、SFTP 等协议把文件再暴露出去。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;文件明明都在服务器上，为什么还要再装一个网盘？&lt;/h2&gt;
&lt;p&gt;先问一个很实际的问题：你的文件早就躺在某台服务器的硬盘里，或者在对象存储的桶里，甚至散落在好几台机器上——它们并不缺一个「存放的地方」。真正缺的，是一个能随时随地用浏览器打开、上传下载、在线预览、还能顺手分享的入口。为了这个入口，难道要把几个 TB 的文件再搬进一个新网盘系统里，重新上传、重新整理、重新做一遍备份？&lt;/p&gt;
&lt;p&gt;Filestash 的回答是：不用搬。它的定位和本系列前面几篇都不一样——Cloudreve 是把文件存进自己的数据库和目录体系，&lt;a href=&quot;/posts/selfhost-alist/&quot;&gt;Alist&lt;/a&gt; 是把各家网盘的接口聚合起来，而 Filestash 干脆&lt;strong&gt;自己一个字节都不存&lt;/strong&gt;，只做一件事：给已经存在的存储，套上一个统一、好看、功能完整的网页门面。存储还是原来的存储，权限还是原来的权限，你只是多了一个随时能打开的网页入口。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/mickael-kerjean/filestash&lt;/p&gt;
&lt;p&gt;这个项目从 2017 年维护至今，GitHub 上约 14.9k 星，采用 AGPL-3.0 协议。它的官方称呼是「通用文件管理平台」（Universal File Management Platform），下面就沿着这条主线展开：先讲清它和传统网盘的本质区别，再用 Docker 把它跑起来，接上一个 S3 和一个 SFTP 后端，最后聊聊它真正拉开差距的插件与网关能力。&lt;/p&gt;
&lt;h2&gt;先搞清楚：它是个「门面」，不是仓库&lt;/h2&gt;
&lt;p&gt;理解 Filestash 的关键，是分清两个概念：&lt;strong&gt;存储后端&lt;/strong&gt;和&lt;strong&gt;访问界面&lt;/strong&gt;。传统网盘把两件事捆在一起——文件必须先进它的系统，才能通过它的界面访问。Filestash 把这两件事彻底拆开：文件留在原地，它只负责「翻译」——把各种存储协议翻译成一套统一的网页操作。&lt;/p&gt;
&lt;p&gt;它能对接的后端几乎覆盖了所有常见协议：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;后端类型&lt;/th&gt;
&lt;th&gt;典型场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;SFTP / FTP&lt;/td&gt;
&lt;td&gt;任何一台开了 SSH 的 Linux 服务器、老式 FTP 空间&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;S3 及兼容存储&lt;/td&gt;
&lt;td&gt;AWS S3、MinIO、Cloudflare R2、阿里云 OSS 等&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SMB / NFS&lt;/td&gt;
&lt;td&gt;局域网里的 NAS、Windows 共享目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;WebDAV&lt;/td&gt;
&lt;td&gt;已有的 WebDAV 服务，比如 Nextcloud、&lt;a href=&quot;/posts/clouddrive-davflare/&quot;&gt;Davflare&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Git&lt;/td&gt;
&lt;td&gt;把代码仓库当文件库浏览&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;IPFS&lt;/td&gt;
&lt;td&gt;分布式存储网络&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本地目录&lt;/td&gt;
&lt;td&gt;Filestash 所在机器自己的文件夹&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这意味着一种非常实用的组合：公司文件在 SMB 共享上，备份在 S3 桶里，个人文件在家里的服务器上——以前要开三个客户端、记三套地址，现在全部挂到同一个 Filestash 里，一个页面全部搞定。和 &lt;a href=&quot;/posts/clouddrive-openlist/&quot;&gt;OpenList&lt;/a&gt; 这类聚合工具相比，Filestash 聚合的不是「网盘服务」，而是「存储协议」，所以它的覆盖面落在了更底层的位置。&lt;/p&gt;
&lt;h3&gt;和 Cloudreve、Alist 到底差在哪&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;Cloudreve&lt;/th&gt;
&lt;th&gt;Alist / OpenList&lt;/th&gt;
&lt;th&gt;Filestash&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;文件存在哪&lt;/td&gt;
&lt;td&gt;自己的目录/对象存储，由它管理&lt;/td&gt;
&lt;td&gt;各家网盘里，它只做聚合&lt;/td&gt;
&lt;td&gt;原有存储里，它完全不碰&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;核心动作&lt;/td&gt;
&lt;td&gt;建仓库、存文件&lt;/td&gt;
&lt;td&gt;挂载网盘账号&lt;/td&gt;
&lt;td&gt;给存储套界面&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;用户体系&lt;/td&gt;
&lt;td&gt;自带完整用户与权限&lt;/td&gt;
&lt;td&gt;自带用户与访客控制&lt;/td&gt;
&lt;td&gt;依赖后端账号或插件做认证&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;典型用户&lt;/td&gt;
&lt;td&gt;想要一个自己的网盘&lt;/td&gt;
&lt;td&gt;网盘账号太多想统一入口&lt;/td&gt;
&lt;td&gt;存储早已就位，只缺好用的访问层&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;迁移成本&lt;/td&gt;
&lt;td&gt;要把文件搬进去&lt;/td&gt;
&lt;td&gt;授权账号即可&lt;/td&gt;
&lt;td&gt;填后端地址即可，零搬运&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;一句话记住它：别的网盘是先建仓库再请你搬家，Filestash 是站在你家门口，给你换了一扇带可视门铃的新门。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;部署：一条 Docker 命令先跑起来&lt;/h2&gt;
&lt;p&gt;Filestash 官方提供 Docker 镜像 &lt;code&gt;machines/filestash&lt;/code&gt;，默认端口 8334。用 Docker Compose 部署如下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  filestash:
    image: machines/filestash
    container_name: filestash
    restart: unless-stopped
    ports:
      - &quot;8334:8334&quot;
    volumes:
      - ./data:/app/data/state
    environment:
      - APPLICATION_URL=https://files.example.com
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose logs -f filestash
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动后浏览器打开 &lt;code&gt;http://服务器IP:8334&lt;/code&gt;，就能看到登录界面。第一次使用时先访问管理后台设置管理员密码：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;https://files.example.com/admin
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;在后台里可以完成绝大多数配置：添加存储连接、设置认证方式、开关功能模块、调整界面主题等。配置会持久化到挂载出来的 &lt;code&gt;data&lt;/code&gt; 目录里，所以上面 Compose 里的卷挂载别省——省掉的话容器一重建，所有连接配置都得重填。具体的卷路径与环境变量以官方文档（filestash.app 的安装指南）为准，不同版本可能略有差异。&lt;/p&gt;
&lt;p&gt;如果打算长期用，建议再在前面套一层反向代理和 HTTPS，形态和给其他自建服务做入口没有区别：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;server {
    listen 443 ssl;
    server_name files.example.com;

    location / {
        proxy_pass http://127.0.0.1:8334;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 0;
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;client_max_body_size 0&lt;/code&gt; 这一行：文件管理服务经常要传大文件，反向代理默认的上传大小限制是最常见的「传一半失败」元凶，索性放开，把限制交给后端存储本身去管。&lt;/p&gt;
&lt;h2&gt;接第一个后端：S3 对象存储&lt;/h2&gt;
&lt;p&gt;假设你有一个 S3 兼容的桶（AWS S3、MinIO、R2 都算），想在网页里直接管理它。在 Filestash 管理后台的 Connections（连接）里新建一个连接，类型选 S3，核心参数就这几项：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Endpoint&lt;/td&gt;
&lt;td&gt;S3 服务地址，AWS 官方可留空或填区域地址，MinIO/R2 填自己的地址&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Region&lt;/td&gt;
&lt;td&gt;桶所在区域，如 &lt;code&gt;ap-east-1&lt;/code&gt;；自建 MinIO 随便填一个即可&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Access Key / Secret Key&lt;/td&gt;
&lt;td&gt;访问密钥对，建议为 Filestash 单独建一个子账号密钥&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Bucket&lt;/td&gt;
&lt;td&gt;要挂载的桶名&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Path&lt;/td&gt;
&lt;td&gt;可选，限定只暴露桶内某个前缀目录&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;对应的连接配置结构大致长这样（后台界面里填的是同一批字段，写出来是为了让你有个整体概念，字段细节以官方文档为准）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;type&quot;: &quot;s3&quot;,
  &quot;label&quot;: &quot;备份桶&quot;,
  &quot;params&quot;: {
    &quot;endpoint&quot;: &quot;https://minio.example.com&quot;,
    &quot;region&quot;: &quot;us-east-1&quot;,
    &quot;access_key_id&quot;: &quot;filestash-ro&quot;,
    &quot;secret_access_key&quot;: &quot;********&quot;,
    &quot;bucket&quot;: &quot;archive&quot;,
    &quot;path&quot;: &quot;/shared&quot;
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;保存后回到首页，这个桶就会作为一个入口出现，点进去就能浏览、上传、下载、预览——而桶里的对象本身一动没动，原来用其他工具访问这个桶的方式也不受任何影响。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;给 Filestash 用的 S3 密钥务必走最小权限：只给目标桶的读写权限，不要图省事直接填主账号的根密钥。&amp;lt;/span&amp;gt;门面再安全，也没必要把整栋楼的钥匙挂在门上。&lt;/p&gt;
&lt;h2&gt;接第二个后端：SFTP 指向家里那台服务器&lt;/h2&gt;
&lt;p&gt;再把一台开了 SSH 的 Linux 机器接进来。新建连接，类型选 SFTP：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;type&quot;: &quot;sftp&quot;,
  &quot;label&quot;: &quot;家里的服务器&quot;,
  &quot;params&quot;: {
    &quot;host&quot;: &quot;192.168.1.10&quot;,
    &quot;port&quot;: &quot;22&quot;,
    &quot;username&quot;: &quot;files&quot;,
    &quot;password&quot;: &quot;********&quot;,
    &quot;path&quot;: &quot;/srv/files&quot;
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个实操建议：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;在被连接的服务器上&lt;strong&gt;单独建一个低权限账号&lt;/strong&gt;（如上面的 &lt;code&gt;files&lt;/code&gt;），只让它访问要共享的目录，别用 root 或自己的日常账号直连。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;path&lt;/code&gt; 参数把可见范围锁死在一个目录里，Filestash 里看到的就是这个目录的视图，跳不出去。&lt;/li&gt;
&lt;li&gt;条件允许时优先用密钥登录代替密码登录，并在服务器侧关掉该账号的密码登录。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;接完这两个后端，你的 Filestash 首页上会并排出现「备份桶」和「家里的服务器」两个入口。在网页里把文件从 SFTP 拖到 S3，或者反过来——跨存储搬运就在浏览器里完成了，而这正是「门面」模式最顺手的时刻：存储各归其位，操作只有一个界面。&lt;/p&gt;
&lt;h2&gt;进阶一：Gateways——把文件再以别的协议递出去&lt;/h2&gt;
&lt;p&gt;Filestash 不只是个「读」的界面。它有一组叫 Gateways 的能力：挂进来的存储，可以再以 SFTP、S3、FTP、WebDAV、MCP 等协议&lt;strong&gt;反向暴露&lt;/strong&gt;出去。&lt;/p&gt;
&lt;p&gt;这个能力解决的是协议不匹配的尴尬。举例：你的备份软件只认 S3 接口，但文件实际躺在一台只有 SMB 共享的老 NAS 上。以前只能换软件或者加一层转换服务，现在让 Filestash 把 SMB 接进来、再以 S3 网关递出去，备份软件无感对接。再比如某个只支持 WebDAV 的移动端 App，可以直接连 Filestash 的 WebDAV 网关，访问它背后的 SFTP 服务器——协议转换这件脏活，门面顺手就干了。&lt;/p&gt;
&lt;p&gt;:::warning
网关是把双刃剑：每多开一个对外协议，就多一个需要做认证和审计的入口。只开启真正用到的网关协议，并为每个网关单独设置访问凭据；不要为了「以后可能用」把 SFTP、FTP、WebDAV 一股脑全打开暴露在公网上。
:::&lt;/p&gt;
&lt;h2&gt;进阶二：插件驱动——它真正的护城河&lt;/h2&gt;
&lt;p&gt;Filestash 的架构理念是「除宇宙基本真理之外，一切皆插件」：存储后端是插件，认证方式是插件，授权规则是插件，连搜索、缩略图生成都是插件。除了传统的 Go 插件，它还支持运行时插件——一个 zip 包丢进插件目录即可生效，其中可以包含在沙箱里运行的 WebAssembly 代码，权限被严格收紧，不给声明之外的网络访问。&lt;/p&gt;
&lt;p&gt;对普通使用者来说，插件体系最直接的收益是这些「大网盘才有」的功能它都能补齐：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;工作流引擎&lt;/strong&gt;：文件事件触发动作链。比如「某目录新增文件 → 自动发邮件通知」「上传完成 → 触发后续处理流水线」，这类自动化不用再自己写脚本盯目录。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;认证与授权&lt;/strong&gt;：可以对接现有的账号体系做登录，用基于角色的权限控制（RBAC）决定谁能看哪个后端、哪个目录。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;版本、审计、配额、杀毒&lt;/strong&gt;：文件版本管理、操作审计日志、按用户限额、上传自动杀毒扫描，都以插件形式提供，需要哪个开哪个。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;AI 能力&lt;/strong&gt;：AI 搜索、智能文件夹、图片 OCR 识别，也在插件生态里。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这套设计的代价是：很多高级功能不是开箱全亮，而是要你去插件列表里按需启用。第一次用可能会觉得「怎么这个功能还要装插件」，但用久了会明白，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;核心保持轻量、能力按需生长，正是它能从 2017 年活到今天还没臃肿死的原因。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;进阶三：文件应用——不止是传文件，还能看文件&lt;/h2&gt;
&lt;p&gt;普通网盘的预览能力一般停留在图片、视频、PDF 和 Office 文档。Filestash 的文件应用（File Apps）覆盖面要夸张得多，光是官方列出的就包括：相机 RAW 全家桶（NEF、CR2、ARW、RAF 等）、天文图像（FITS、XISF）、GIS 数据（GeoJSON、SHP、GPX）、数据工程格式（Parquet、Arrow、HDF5、NetCDF）、3D 模型（FBX、OBJ、STL、STEP）、Adobe 系列（PSD、AI、XD）、医学影像（DICOM）……再加上按需视频转码、Chromecast 投屏这类播放能力。&lt;/p&gt;
&lt;p&gt;这意味着对特定职业用户，Filestash 的价值会陡增：摄影师把 NAS 里的 RAW 原片挂进来，出门在外用浏览器就能挑片；做数据的把结果文件丢进 S3，网页上直接预览 Parquet 而不用每次下载到本地开工具。如果你的工作流里有大量「格式特殊、在线看一眼就够了」的文件，这一节就是选它的核心理由。&lt;/p&gt;
&lt;h2&gt;排障小节&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;容器起来了，但 8334 端口打不开。&lt;/strong&gt; 先看 &lt;code&gt;docker compose logs filestash&lt;/code&gt; 有没有报错，再确认防火墙和云服务器安全组放行了 8334（或反向代理所在的 443）。本地 &lt;code&gt;curl http://127.0.0.1:8334&lt;/code&gt; 能通、外部不通，基本就是安全组问题。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;配置重启后全没了。&lt;/strong&gt; 十有八九是数据卷没挂对。确认 Compose 里的 &lt;code&gt;data&lt;/code&gt; 卷确实映射到了 Filestash 的状态目录（以官方文档为准），并且宿主机目录可写。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;S3 连接报错，连不上或列表为空。&lt;/strong&gt; 按顺序查：Endpoint 写对没有（MinIO 和 R2 必须填自己的地址，不能套 AWS 的）、Region 是否匹配、密钥子账号有没有目标桶的 &lt;code&gt;ListBucket&lt;/code&gt; 和对象读写权限、路径前缀 &lt;code&gt;path&lt;/code&gt; 是否写了一个不存在的目录。先用同一组密钥在命令行 &lt;code&gt;aws s3 ls&lt;/code&gt; 验证一遍，能省很多时间。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;SFTP 连接超时或认证失败。&lt;/strong&gt; 先在 Filestash 所在机器上手动 &lt;code&gt;ssh 用户名@主机&lt;/code&gt; 试一次：网络不通、端口不对、服务器禁用了密码登录，都会先在这里暴露。若服务器只允许密钥登录，就改用密钥方式配置连接，别硬试密码。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;上传大文件到一半失败。&lt;/strong&gt; 链条上每一层都可能有限制：反向代理的 &lt;code&gt;client_max_body_size&lt;/code&gt;、Filestash 自身的上传设置、后端存储的单文件上限。逐层放开并复现一次小文件→大文件，就能定位是哪一层在拦。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;网页能打开但预览是空白或乱码。&lt;/strong&gt; 多数是 &lt;code&gt;APPLICATION_URL&lt;/code&gt; 与实际访问地址不一致，或者反向代理没透传 &lt;code&gt;X-Forwarded-Proto&lt;/code&gt;，导致页面生成的资源链接协议错误（HTTPS 页面里混入 HTTP 资源会被浏览器拦截）。把这两个对齐后强制刷新再看。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Filestash 在本系列里是个异类：&lt;a href=&quot;/posts/selfhost-cloudreve/&quot;&gt;Cloudreve&lt;/a&gt; 是仓库，Alist 是聚合器，&lt;a href=&quot;/posts/clouddrive-davflare/&quot;&gt;Davflare&lt;/a&gt; 是把仓库建在云上，而 Filestash 是纯粹的门面——文件在哪它就在哪开窗。如果你的存储早已成型（SFTP 服务器在跑、S3 桶在用、NAS 共享开着），缺的只是一个统一、能预览、能分享、还能跨协议递送的网页入口，那 Filestash 就是成本最低的那个答案：零迁移、零搬运，一个 Docker 容器，今晚就能上线。&lt;/p&gt;
</content:encoded></item><item><title>OpenList：AList 的社区分叉版，把网盘聚合的信任重新建起来</title><link>https://www.anexns.cloudns.org/posts/clouddrive-openlist/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/clouddrive-openlist/</guid><description>OpenList 是 AList 在信任危机后由社区分叉维护的网盘聚合程序，50 多种存储驱动、WebDAV、离线下载一应俱全，本文用 Docker Compose 完整部署，并讲清它和 AList 的关系与迁移方法。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说来历：一个开源项目是怎么「换主人」的&lt;/h2&gt;
&lt;p&gt;2025 年，网盘聚合圈出了一件大事。用了好几年的 AList 突然被曝出项目已经易主：原作者把项目连同背后的公司卖给了第三方。消息传开后，社区最担心的不是功能，而是信任——AList 里存着大量用户各家网盘的授权令牌，一个天天经手你云盘钥匙的程序，一旦代码不再透明、更新不再可控，谁还敢继续用？&lt;/p&gt;
&lt;p&gt;OpenList 就是在这样的背景下诞生的。2025 年 6 月，社区维护者把 AList 分叉出来，成立 OpenListTeam 独立维护，主打两件事：&lt;strong&gt;长期治理&lt;/strong&gt;与&lt;strong&gt;代码透明&lt;/strong&gt;，许可证继续走 AGPL-3.0，代码全部公开在 GitHub 上。半年时间，它已经攒下约 2.56 万星，成为原 AList 用户迁移的主力选择。这篇就把它讲透：它和 AList 是什么关系、怎么部署、老用户怎么迁过来。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/OpenListTeam/OpenList&lt;/p&gt;
&lt;p&gt;功能上，OpenList 和 AList 基本同源：一个网页界面把 50 多种存储聚合到一起——本地目录、阿里云盘、OneDrive、天翼云盘、Google Drive、123 云盘、FTP/SFTP、PikPak、S3、Seafile、又拍云、WebDAV、百度网盘、夸克、迅雷、蓝奏云、115、SMB、Cloudreve、Dropbox、Azure Blob 等等，全都能挂进来统一浏览。文件预览（PDF、Markdown、代码、Office 文档）、图片画廊、音视频在线播放（带歌词与字幕）、直链复制、文件夹打包下载、暗色模式、多语言界面、受保护路径、WebDAV 服务、离线下载、跨存储复制、多线程下载加速，也都齐全。&lt;/p&gt;
&lt;h2&gt;OpenList 与 AList：到底差在哪&lt;/h2&gt;
&lt;p&gt;先把两者的关系用一张表说清，免得选型时纠结：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;AList&lt;/th&gt;
&lt;th&gt;OpenList&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;维护方&lt;/td&gt;
&lt;td&gt;已易主至第三方公司&lt;/td&gt;
&lt;td&gt;OpenListTeam 社区团队&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;代码透明度&lt;/td&gt;
&lt;td&gt;后续走向不确定&lt;/td&gt;
&lt;td&gt;全量开源，AGPL-3.0&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;功能与驱动&lt;/td&gt;
&lt;td&gt;原版功能集&lt;/td&gt;
&lt;td&gt;与 AList 基本同源，持续同步新驱动&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;配置与数据&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;与 AList 结构兼容，可直接迁移&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;官方渠道&lt;/td&gt;
&lt;td&gt;原 AList 仓库&lt;/td&gt;
&lt;td&gt;只认 OpenListTeam 的 GitHub 仓库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文档&lt;/td&gt;
&lt;td&gt;原 AList 文档站&lt;/td&gt;
&lt;td&gt;doc.oplist.org&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一句话概括：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;OpenList 不是另起炉灶的新软件，而是 AList 的社区接管版——功能照旧，治理换人。&amp;lt;/span&amp;gt;你之前看过本系列的 &lt;a href=&quot;/posts/selfhost-alist/&quot;&gt;Alist 篇&lt;/a&gt; 的话，里面的使用习惯九成可以原样搬过来，差的主要是部署镜像和项目归属。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;strong&gt;认准官方仓库，别下到仿冒版。&lt;/strong&gt; OpenList 官方明确声明：它与任何同名的第三方项目、付费「同名软件」都没有关系。市面上已经出现挂着 OpenList 名字的仿冒和收费版本，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;从非官方渠道下载的网盘程序，等于把各家网盘的授权令牌交给陌生人&amp;lt;/span&amp;gt;。只从 OpenListTeam 的 GitHub 仓库和官方文档 doc.oplist.org 获取程序与说明，其他来源一律不要信。
:::&lt;/p&gt;
&lt;h2&gt;部署：Docker Compose 一把梭&lt;/h2&gt;
&lt;p&gt;部署方式有官方 Docker 镜像、二进制直装等几种，本文以 Docker Compose 为主线，也是官方仓库自带 &lt;code&gt;docker-compose.yml&lt;/code&gt; 与 &lt;code&gt;Dockerfile&lt;/code&gt; 的路线。找一台能跑 Docker 的机器（VPS、NAS、家里的 Linux 小主机都行），新建一个目录放编排文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  openlist:
    image: openlistteam/openlist:latest
    container_name: openlist
    restart: unless-stopped
    volumes:
      - ./data:/opt/openlist/data
    ports:
      - &quot;5244:5244&quot;
    environment:
      - TZ=Asia/Shanghai
      - PUID=0
      - PGID=0
      - UMASK=022
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个参数的含义：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;镜像&lt;/strong&gt;：&lt;code&gt;openlistteam/openlist&lt;/code&gt;，这是官方镜像名，和 AList 时代的镜像不是同一个，别填错。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;端口&lt;/strong&gt;：默认 &lt;code&gt;5244&lt;/code&gt;，网页界面、API 与 WebDAV 都走这一个端口。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;数据目录&lt;/strong&gt;：&lt;code&gt;/opt/openlist/data&lt;/code&gt; 里放着数据库和配置，映射到宿主机的 &lt;code&gt;./data&lt;/code&gt;，升级、迁移时保住这个目录就行。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;PUID/PGID&lt;/strong&gt;：控制容器读写挂载目录时的用户身份，填 &lt;code&gt;0&lt;/code&gt; 是图省事用 root；介意的话改成你宿主机普通用户的编号。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;启动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker logs -f openlist
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;拿管理员密码：第一次登录&lt;/h2&gt;
&lt;p&gt;OpenList 首次启动时会自动生成管理员密码，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;初始密码只在第一次启动的日志里出现一次&amp;lt;/span&amp;gt;，所以启动后第一件事就是翻日志：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker logs openlist | grep -i password
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;日志里会有一行类似 &lt;code&gt;initial password is: xxxxxxxx&lt;/code&gt;，记下它，浏览器打开 &lt;code&gt;http://你的服务器IP:5244&lt;/code&gt;，用用户名 &lt;code&gt;admin&lt;/code&gt; 和这个密码登录。&lt;/p&gt;
&lt;p&gt;如果日志翻不到了（比如容器重启过几次），不用重装，直接重置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 随机生成一个新密码并打印出来
docker exec -it openlist ./openlist admin random

# 或者直接指定一个新密码
docker exec -it openlist ./openlist admin set 你的新密码
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;登录成功后，先去「个人资料」里把密码改成自己记得住的强密码，再到管理后台的「设置」里把站点标题、公告等按喜好调整一遍。至此网盘本体已经跑起来了，接下来是往里挂存储。&lt;/p&gt;
&lt;h2&gt;添加存储：本地目录先行，云盘随后&lt;/h2&gt;
&lt;p&gt;OpenList 的核心玩法是「存储驱动」。进管理后台 →「存储」→「添加」，驱动列表里能看到全部 50 多种类型。建议先加一个本地存储练手：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;驱动选「本地存储」，挂载路径填 &lt;code&gt;/&lt;/code&gt;（这是访客看到的路径，比如填 &lt;code&gt;/本地&lt;/code&gt; 就出现在根目录的「本地」文件夹里）。&lt;/li&gt;
&lt;li&gt;根文件夹路径填容器内能看到的目录。想把宿主机某个目录映射进来，先在 Compose 里加一行卷映射：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;    volumes:
      - ./data:/opt/openlist/data
      - /你的/宿主机目录:/mnt/files
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后根文件夹路径填 &lt;code&gt;/mnt/files&lt;/code&gt;，重启容器生效：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose down
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;ol&gt;
&lt;li&gt;保存后回首页，目录应该已经能浏览、能预览了。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;再挂云盘的流程都大同小异：选对应驱动（比如阿里云盘、OneDrive、百度网盘），按官方文档 doc.oplist.org 里该驱动的说明拿到授权令牌或刷新令牌，填进表单保存即可。每个驱动需要什么凭证，文档里都写得很细，本文不逐个展开。只提醒一点原则：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;令牌只填进你自己部署的 OpenList，不要填进任何在线「代挂」「代获取」网站&amp;lt;/span&amp;gt;，那些网站拿到的就是你网盘的完整访问权。&lt;/p&gt;
&lt;p&gt;挂好之后，几个日常功能顺手就有了：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;直链与分享&lt;/strong&gt;：任意文件可以复制直链发给别人，也可以把某个目录设为受保护路径，加密码才可见。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;离线下载&lt;/strong&gt;：把下载链接丢给 OpenList，它在服务器上先把文件拉回指定存储，再慢慢取——服务器带宽好时比本地直连快得多。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;跨存储复制&lt;/strong&gt;：文件可以在两个已挂载的存储之间直接搬运，比如从 OneDrive 复制到本地目录，全程在网页里点完。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;聚合其他自建网盘&lt;/strong&gt;：驱动列表里有 Cloudreve、Seafile、WebDAV，也就是说你之前搭的 &lt;a href=&quot;/posts/selfhost-cloudreve/&quot;&gt;Cloudreve&lt;/a&gt; 也能作为一个存储挂进 OpenList，当统一入口用。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;WebDAV：挂到电脑和手机上当本地盘&lt;/h2&gt;
&lt;p&gt;OpenList 自带 WebDAV 服务，和网页共用 5244 端口，地址是：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;http://你的服务器IP:5244/dav
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;用户名、密码就是 OpenList 的账号（普通用户需要在后台给它开 WebDAV 权限）。Windows 资源管理器、macOS 的 Finder、手机上的文件管理器都能直接连。更进一步，想把云存储真正「变成」本地磁盘、让所有软件都能读写，可以配合本系列后面的 &lt;a href=&quot;/posts/clouddrive-rclone/&quot;&gt;Rclone 篇&lt;/a&gt;：Rclone 能把 WebDAV 挂载成本地目录，OpenList 出存储、Rclone 出挂载，正好互补。&lt;/p&gt;
&lt;p&gt;如果你的需求其实只是临时中转几个小文件、连服务器都不想开，那是另一条路线——&lt;a href=&quot;/posts/clouddrive-davflare/&quot;&gt;Davflare&lt;/a&gt; 把网盘搭在 Cloudflare 上，零服务器成本；OpenList 则是「我有台机器，把所有盘都收拢进来」的路线，两者定位不同，不冲突。&lt;/p&gt;
&lt;h2&gt;套个域名：反向代理与 HTTPS&lt;/h2&gt;
&lt;p&gt;5244 端口直接裸奔在公网有两个问题：一是没加密，登录密码和令牌都在明文里跑；二是有些 WebDAV 客户端对非 HTTPS 地址直接拒绝连接。常规做法是前面套一层反向代理，用域名加证书访问。Nginx 的核心配置就这么几行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;server {
    listen 443 ssl;
    server_name pan.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    client_max_body_size 0;

    location / {
        proxy_pass http://127.0.0.1:5244;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;其中 &lt;code&gt;client_max_body_size 0&lt;/code&gt; 这一行别漏：不写的话 Nginx 默认只允许 1 MB 的请求体，网页上传稍大一点的文件就会报 413。反代生效后，进 OpenList 后台的「设置 → 其他」里把「站点地址」填成你的 &lt;code&gt;https://pan.example.com&lt;/code&gt;，这样复制出来的直链和 WebDAV 地址才会是正确的外网地址，而不是内网的 IP 加端口。&lt;/p&gt;
&lt;h2&gt;用户与权限：别只用管理员到处跑&lt;/h2&gt;
&lt;p&gt;OpenList 支持多用户，日常使用建议分三层，别拿管理员账号到处登录：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;管理员&lt;/strong&gt;：只用来改设置、挂存储，不参与日常浏览和 WebDAV 挂载。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;普通用户&lt;/strong&gt;：给自己日常用的账号，可以按目录限定它的可见范围——比如只让它看 &lt;code&gt;/本地&lt;/code&gt; 和 &lt;code&gt;/阿里云盘&lt;/code&gt;，其他存储对它不可见；再按需勾选 WebDAV 读取、管理等权限。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;访客（guest）&lt;/strong&gt;：未登录时能看到什么由访客账号决定。只想自己用的话，把访客的可见路径收成空，或者只放一个公开分享目录。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;再配合两个小设置，安全性会好很多：一是给敏感目录设「路径密码」，在存储或元信息（Meta）里给指定路径加访问密码，链接发出去也不怕被随便翻；二是在元信息里设置隐藏规则，把不想出现在列表里的文件藏起来。家里有孩子共用、或者要把某个目录临时公开给朋友时，这套权限组合足够用了。&lt;/p&gt;
&lt;h2&gt;从 AList 迁移：十分钟换完&lt;/h2&gt;
&lt;p&gt;老 AList 用户迁过来非常简单，因为两者数据结构兼容：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;停掉旧的 AList 容器，把它的数据目录（原 &lt;code&gt;data&lt;/code&gt; 文件夹）完整复制一份出来备份。&lt;/li&gt;
&lt;li&gt;用上面的 Compose 把 OpenList 起起来，先让它生成自己的 &lt;code&gt;data&lt;/code&gt; 目录，然后停掉。&lt;/li&gt;
&lt;li&gt;把旧 AList 的 &lt;code&gt;data&lt;/code&gt; 内容覆盖进 OpenList 的 &lt;code&gt;data&lt;/code&gt; 目录，再启动 OpenList。&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;docker compose down
cp -r /旧alist路径/data/* ./data/
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动后检查一遍：存储列表、用户、站点设置应该都在。个别驱动在新版本里字段有调整的，编辑一下重新保存即可。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;迁移的核心就一句：保住 data 目录，就保住了一切配置。&amp;lt;/span&amp;gt;所以无论用不用 OpenList，平时也要记得备份这个目录。&lt;/p&gt;
&lt;p&gt;升级 OpenList 本身同样是三行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose pull
docker compose up -d
docker image prune -f
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;排障清单&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;5244 打不开&lt;/strong&gt;：先 &lt;code&gt;docker ps&lt;/code&gt; 看容器是否在跑，再 &lt;code&gt;docker logs openlist&lt;/code&gt; 看有没有报错；云服务器还要检查安全组/防火墙有没有放行 5244 端口。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;登录时提示密码错误&lt;/strong&gt;：多半是初始密码抄错或已经被改过。直接 &lt;code&gt;docker exec -it openlist ./openlist admin random&lt;/code&gt; 重置，进后台后再改成自己的密码。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;存储添加后状态显示错误&lt;/strong&gt;：绝大多数是令牌过期或填错。回驱动表单重新走一遍该驱动文档里的授权流程；阿里云盘、OneDrive 这类用刷新令牌的，令牌失效就要重新获取。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;本地存储看不到文件&lt;/strong&gt;：检查 Compose 的卷映射有没有把宿主机目录映射进容器、根文件夹路径写的是不是容器内路径；再确认 PUID/PGID 对应的用户对该目录有读权限。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;WebDAV 连不上或 401&lt;/strong&gt;：确认地址带了 &lt;code&gt;/dav&lt;/code&gt; 后缀、端口对；再去后台看该用户是否开启了 WebDAV 读取/管理权限。有些客户端要求 HTTPS，套一层反向代理加证书后再试。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;在线播放卡、直链下载慢&lt;/strong&gt;：OpenList 本身只做聚合，流量是否经过你的服务器取决于驱动类型：本地存储和部分驱动走服务器中转，服务器带宽就是上限；302 跳转类驱动则是客户端直连网盘官方，速度与 OpenList 无关。先分清是哪种，再对症下药。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;升级后页面空白&lt;/strong&gt;：清浏览器缓存或强制刷新；还不行就看日志里有没有数据库迁移报错，必要时拿备份的 &lt;code&gt;data&lt;/code&gt; 目录回滚到旧镜像版本。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;OpenList 的故事，一半是技术，一半是信任：功能上它就是那个你熟悉的网盘聚合器——50 多种存储挂到一个网页里，预览、直链、WebDAV、离线下载全都有；来历上它把 AList 丢掉的「代码透明、社区治理」重新捡了回来。对新用户，直接从 OpenList 开始；对 AList 老用户，保住 &lt;code&gt;data&lt;/code&gt; 目录十分钟就能迁完。最后再重复一遍那句最重要的话：只认 OpenListTeam 的 GitHub 仓库，别的「同名版本」不要碰。&lt;/p&gt;
</content:encoded></item><item><title>Pingvin Share X：自建文件分享站，传几个 GB 不用注册网盘</title><link>https://www.anexns.cloudns.org/posts/clouddrive-pingvin-share/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/clouddrive-pingvin-share/</guid><description>用 Docker 部署 Pingvin Share X 自托管文件分享站：链接分享、过期与访问次数限制、密码保护、反向分享、邮件直达与 S3 存储后端，附原版归档与继任分支的来历说明和排障清单。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说主线：传一次大文件，为什么这么难&lt;/h2&gt;
&lt;p&gt;场景很常见：你要给朋友或客户传一个几个 GB 的视频工程、数据集或者系统镜像。公共网盘要注册、要装客户端、要开会员解除限速，对方还得再注册一遍才能下；聊天软件有大小上限；国外那几个临时分享站，免费版限体积、限次数，速度还看运气。说到底，「把一个大文件点对点交到另一个人手里」这件小事，一直没有顺手的解法。&lt;/p&gt;
&lt;p&gt;Pingvin Share X 就是冲着这个场景来的：一个自托管的文件分享平台，定位是 WeTransfer 的自建替代品。你把文件传到自己的服务器上，生成一个链接发给对方，对方打开链接就能下，不用注册、不用装任何东西，大小只受你自己的硬盘限制。分享可以设过期时间、访问次数上限和密码，还能反过来生成「反向分享」链接，让别人往你的服务器里传文件——收稿、收作业、收客户素材时特别好用。&lt;/p&gt;
&lt;p&gt;先把定位说清：它管的是「传一次」，不是「存长期」。文件要长期保存、随时取用，那是网盘本体的活，去看本系列的 &lt;a href=&quot;/posts/selfhost-cloudreve/&quot;&gt;Cloudreve 私人云盘&lt;/a&gt;；这一篇解决的是临时交接。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/smp46/pingvin-share-x&lt;/p&gt;
&lt;h2&gt;先讲来历：原版归档之后，X 接棒&lt;/h2&gt;
&lt;p&gt;Pingvin Share X 是 Pingvin Share 的社区分支（fork）。原版 Pingvin Share 由独立开发者维护了三年多，2025 年 6 月 29 日，作者把原仓库归档停更，说明自己精力有限，决定专注于另一个项目 Pocket ID。难得的是，作者在原版 README 里亲自推荐了这个社区继任分支——Pingvin Share X 由 smp46 维护，2025 年 9 月建仓以来保持活跃更新，已经发了 40 个版本，界面支持 34 种语言。所以现在新部署，装 X 就是正路：功能和原版一脉相承，修复和更新有人接着做。&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要再新装原版 Pingvin Share 仓库了：它已经归档，不会再有功能更新和安全修复。&amp;lt;/span&amp;gt;网上搜到的很多老教程指向的还是 stonith404 的原版仓库，照着装能跑起来，但等于把一个停更的服务放上公网。新部署一律用 Pingvin Share X；已经在跑原版的，迁移大体是换镜像、沿用数据卷，具体步骤以 X 的官方文档为准，不要凭老经验硬套。
:::&lt;/p&gt;
&lt;h2&gt;功能一览：分享这件事，它做全了&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;功能&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;链接分享&lt;/td&gt;
&lt;td&gt;上传后生成分享链接，对方免注册直接下载&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件大小&lt;/td&gt;
&lt;td&gt;不设上限，只受服务器磁盘空间限制&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;过期控制&lt;/td&gt;
&lt;td&gt;每个分享可设过期时间，到期自动失效&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;访问限制&lt;/td&gt;
&lt;td&gt;可设访问次数上限，并可加访问密码&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;邮件直达&lt;/td&gt;
&lt;td&gt;创建分享时直接填收件人邮箱，系统发邮件通知对方&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;反向分享&lt;/td&gt;
&lt;td&gt;生成专属链接，让别人上传文件到你的服务器，可设有效期与次数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;登录集成&lt;/td&gt;
&lt;td&gt;支持 OIDC 与 LDAP，团队已有账号体系时可直接接入&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;病毒扫描&lt;/td&gt;
&lt;td&gt;可集成 ClamAV，对上传文件做安全扫描&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;存储后端&lt;/td&gt;
&lt;td&gt;本地磁盘或 S3 兼容对象存储，二选一&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;对个人用户，最常用的就是前六项；OIDC、LDAP、ClamAV 是给团队和公网部署准备的，后面进阶部分会各带一句。&lt;/p&gt;
&lt;h2&gt;部署：一个 docker-compose.yml 就够了&lt;/h2&gt;
&lt;p&gt;准备一台装好 Docker 的服务器（或 NAS、家用小主机），磁盘留足——分享站的空间消耗全看你传多大的文件。官方推荐的部署方式就是 Docker Compose，X 的仓库根目录自带 &lt;code&gt;docker-compose.yml&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/pingvin-share-x &amp;amp;&amp;amp; cd ~/pingvin-share-x
# 下载 X 仓库自带的 compose 文件
curl -O https://raw.githubusercontent.com/smp46/pingvin-share-x/main/docker-compose.yml
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它的核心内容如下（时区按需改成你自己的）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  pingvin-share:
    image: smp46/pingvin-share-x
    restart: unless-stopped
    ports:
      - 3000:3000
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - &quot;./data:/opt/app/backend/data&quot;
      - &quot;./data/images:/opt/app/frontend/public/img&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;镜像有两个来源，任选其一：Docker Hub 上的 &lt;code&gt;smp46/pingvin-share-x&lt;/code&gt;，或 GitHub 容器仓库的 &lt;code&gt;ghcr.io/smp46/pingvin-share-x&lt;/code&gt;，哪个拉取顺畅用哪个。两个数据卷要留意：&lt;code&gt;data&lt;/code&gt; 存的是数据库与全部上传文件，是这个服务的命根子，备份就备它；&lt;code&gt;images&lt;/code&gt; 存站点图标等自定义图片。拉起服务：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose logs -f pingvin-share   # 看到监听日志后 Ctrl+C 退出
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;http://服务器IP:3000&lt;/code&gt;，能看到登录页就说明跑起来了。首次使用先注册一个账号——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;第一个注册的账号会自动成为管理员&amp;lt;/span&amp;gt;，之后所有站点级配置都在这个账号的后台里完成。注册完管理员，第一件事建议先去后台把「允许注册」关掉（下一节的配置项），分享站不是社区，不需要开放注册。&lt;/p&gt;
&lt;h3&gt;想尝鲜：beta 通道&lt;/h3&gt;
&lt;p&gt;X 维护着一个 beta 通道：新修复和新功能先发到 beta 镜像验证，稳定后再进正式版。把 compose 里的镜像换成带 &lt;code&gt;:beta&lt;/code&gt; 标签即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    image: smp46/pingvin-share-x:beta
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改完 &lt;code&gt;docker compose up -d&lt;/code&gt; 就会拉 beta 版。适合愿意帮忙试新功能、反馈问题的用户；正经在用的分享站建议留在稳定版，等 beta 验证过的更新自然跟进。&lt;/p&gt;
&lt;h2&gt;关键配置：后台界面与 config.yaml&lt;/h2&gt;
&lt;p&gt;Pingvin Share X 的配置有两条路：管理员登录后在后台设置页里改，或者写 &lt;code&gt;config.yaml&lt;/code&gt; 文件。文件方式的规则是：&lt;strong&gt;写进 config.yaml 的值以文件为准，后台界面里对应项会被锁定&lt;/strong&gt;，适合用 Git 管理配置、或者怕手滑改错的场景。仓库里有 &lt;code&gt;config.example.yaml&lt;/code&gt; 包含全部可配项，下面只摘日常真正要动的几组。文件放在数据目录中，改完重启容器生效：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;general:
  appName: &quot;Pingvin Share&quot;
  # 对外访问地址：分享链接和邮件里用的都是它，必须填公网能打开的地址
  appUrl: &quot;https://share.example.com&quot;
  secureCookies: true        # 走 HTTPS 时开启

share:
  allowRegistration: false   # 管理员建好后关掉开放注册
  allowUnauthenticatedShares: false  # 是否允许未登录用户创建分享，按需
  maxExpiration: &quot;0 days&quot;    # 分享最长有效期，0 表示不限制
  maxSize: &quot;10000000000&quot;     # 单个分享总大小上限（字节），这里约 10 GB
  chunkSize: &quot;10000000&quot;      # 上传分片大小（字节），默认 10 MB，别乱动

smtp:
  enabled: true              # 要用邮件发送功能必须先配 SMTP
  host: &quot;smtp.example.com&quot;
  port: &quot;587&quot;
  email: &quot;share@example.com&quot;
  username: &quot;share@example.com&quot;
  password: &quot;你的邮箱密码或授权码&quot;

email:
  enableShareEmailRecipients: true   # 允许创建分享时填写收件人邮箱

s3:
  enabled: false             # 改 true 则文件存进 S3，本地只留数据库
  endpoint: &quot;&quot;
  region: &quot;&quot;
  bucketName: &quot;&quot;
  bucketPath: &quot;&quot;
  key: &quot;&quot;
  secret: &quot;&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个配置点的取舍：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;appUrl 是最容易踩的坑&lt;/strong&gt;。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;appUrl 填错，分享链接和通知邮件里生成的全是错误地址，对方点开必然打不开。&amp;lt;/span&amp;gt;本机测试时是 &lt;code&gt;http://localhost:3000&lt;/code&gt;，一旦绑了域名走公网，第一时间把它改成正式地址。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;maxSize 与磁盘的关系&lt;/strong&gt;：maxSize 只是单分享上限，挡不住有人反复建分享把盘塞满。公网部署建议同时在系统层给 data 目录留配额或单独挂盘。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;S3 后端适合文件量大的场景&lt;/strong&gt;：本地盘只放数据库，文件本体进对象存储，服务器迁移和扩容都轻松；个人小规模用本地盘更简单，备份也直观。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;SMTP 不配也能用&lt;/strong&gt;：链接分享不受影响，只是「邮件发送给收件人」和找回密码这类功能用不了。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;日常用法：发分享、收文件&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;发一个分享&lt;/strong&gt;：登录后点新建分享，把文件拖进去（支持大文件分片上传，浏览器别关），然后设三件套——过期时间、最大访问次数、访问密码。生成链接后发给对方即可；配了 SMTP 的话，创建时直接填对方邮箱，系统会把链接邮件送过去，省得你再转述。对方打开链接看到的是干净的下载页，输密码（如果设了）就能下，次数用完或到期后链接自动失效。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;收文件用反向分享&lt;/strong&gt;：在后台创建一个反向分享链接，设好有效期和允许上传的次数，把链接发给需要给你传文件的人。对方打开链接只能上传、看不到你服务器上的其他内容，文件直接落进你的分享站，你登录后台就能取。收客户素材、收投稿、让家人传手机里的原图，都比逐个教他们装网盘客户端省事。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;团队场景的两个开关&lt;/strong&gt;：用户多、有现成账号体系时，在配置里接 OIDC 或 LDAP，成员用统一账号登录，不用在分享站里再维护一套密码；上传入口对公网开放时，建议再按官方文档给 Compose 加一个 ClamAV 服务并开启扫描，多一道病毒拦截。细节以官方文档（smp46.github.io）为准，这里不展开。&lt;/p&gt;
&lt;h2&gt;反向代理与 HTTPS：上线前把这几件事做对&lt;/h2&gt;
&lt;p&gt;正式对外用，一般会套一层反向代理加 HTTPS。以 Nginx 为例：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;server {
    listen 443 ssl;
    server_name share.example.com;

    # 必须大于上传分片大小（chunkSize 默认 10 MB），否则大文件上传会被拦腰截断
    client_max_body_size 50m;
    # 大文件传输耗时长，超时给足
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;用 Nginx Proxy Manager 这类面板同理：建代理主机指向 3000 端口，把请求体大小上限调到分片大小以上即可。代理配好后记得回头改两处：&lt;code&gt;appUrl&lt;/code&gt; 改成 &lt;code&gt;https://share.example.com&lt;/code&gt;，&lt;code&gt;secureCookies&lt;/code&gt; 打开。&lt;/p&gt;
&lt;p&gt;安全上再强调一句：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;分享站一旦对公网开放上传，就等于把一块公共硬盘挂在了网上。&amp;lt;/span&amp;gt;务必关掉开放注册、禁止未登录创建分享，给每个分享都设过期时间；长期不用时宁可停掉容器，也不要让一个无人看管的上传入口一直暴露着——被陌生人当免费图床和违规文件中转站，锅全在服务器所有者身上。&lt;/p&gt;
&lt;h2&gt;和 PsiTransfer 怎么选&lt;/h2&gt;
&lt;p&gt;同为自建临时分享，本系列还有一篇 &lt;a href=&quot;/posts/clouddrive-psitransfer/&quot;&gt;PsiTransfer&lt;/a&gt;，两者气质差别不小：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;Pingvin Share X&lt;/th&gt;
&lt;th&gt;PsiTransfer&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;定位&lt;/td&gt;
&lt;td&gt;功能完整的分享平台&lt;/td&gt;
&lt;td&gt;极简的临时文件中转&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;账号体系&lt;/td&gt;
&lt;td&gt;有注册体系，可接 OIDC / LDAP&lt;/td&gt;
&lt;td&gt;无账号，开箱即传&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;分享控制&lt;/td&gt;
&lt;td&gt;过期、访问次数、密码、邮件发送、反向分享&lt;/td&gt;
&lt;td&gt;过期、一次性下载、密码&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;存储后端&lt;/td&gt;
&lt;td&gt;本地磁盘或 S3&lt;/td&gt;
&lt;td&gt;本地磁盘&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;界面与管理&lt;/td&gt;
&lt;td&gt;现代界面，后台配置项丰富&lt;/td&gt;
&lt;td&gt;轻量界面，配置靠文件与环境变量&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;维护状态&lt;/td&gt;
&lt;td&gt;社区继任分支，活跃维护&lt;/td&gt;
&lt;td&gt;仍在持续维护&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;结论很简单：要「平台感」——多用户、正规分享管理、邮件通知、反向收文件——选 Pingvin Share X；只想给自己留一个随手传文件的极简入口，PsiTransfer 更轻、更省心。&lt;/p&gt;
&lt;h2&gt;排障清单&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;容器起来了但页面打不开&lt;/strong&gt;：先 &lt;code&gt;docker compose logs&lt;/code&gt; 看后端是否报错，再查 3000 端口是否被其他服务占用、安全组/防火墙是否放行。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;分享链接发给别人打不开&lt;/strong&gt;：九成是 &lt;code&gt;appUrl&lt;/code&gt; 还是 &lt;code&gt;localhost&lt;/code&gt; 或内网地址。改成公网正式地址后，旧链接需要重新生成。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;大文件传到一半失败&lt;/strong&gt;：先查反向代理的 &lt;code&gt;client_max_body_size&lt;/code&gt; 是否小于分片大小，再查代理超时设置；直连 3000 端口测试能过、走域名不行，问题就在代理层。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;邮件发不出去&lt;/strong&gt;：确认 &lt;code&gt;smtp.enabled&lt;/code&gt; 已开、邮箱用的是授权码而非登录密码（多数邮箱服务商要求）、&lt;code&gt;enableShareEmailRecipients&lt;/code&gt; 已开启；改完配置记得重启容器。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;后台改了配置不生效&lt;/strong&gt;：检查是否被 &lt;code&gt;config.yaml&lt;/code&gt; 里的同名值锁定——文件里写了的值，后台改不动，改文件并重启容器。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;S3 模式上传报错&lt;/strong&gt;：核对 endpoint、region、桶名与密钥，确认密钥对该桶有读写权限；先切回本地存储验证服务本身没问题，再回头查对象存储侧。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;磁盘莫名被占满&lt;/strong&gt;：多半是过期分享之外的历史文件堆积或有人反复上传。去后台清掉无用分享，并给分享设默认过期时间，养成习惯。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;升级或迁移后数据丢失&lt;/strong&gt;：这个服务的全部状态都在 &lt;code&gt;data&lt;/code&gt; 卷里，迁移就是搬 &lt;code&gt;data&lt;/code&gt; 目录加同一份 compose 文件；动手前先整目录备份。从原版迁过来的，先在测试环境验证数据卷兼容，再切生产，并以官方文档的迁移说明为准。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Pingvin Share X 把「传大文件」这件小事做成了一个完整的产品：链接分享、过期与次数、密码、邮件、反向收文件，该有的都有，部署却只要一个 Compose 文件。它接过的原版已经归档，但 X 本身在活跃维护，这条线没有断。长期公网部署时记住&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;把注册关严、过期设好&amp;lt;/span&amp;gt;，它就是一个可靠的自建分享站。如果你的需求其实是「随时能打开的常驻网盘」，那不在这一篇的范围里，去看零服务器的 &lt;a href=&quot;/posts/clouddrive-davflare/&quot;&gt;Davflare&lt;/a&gt; 或者自有服务器的 Cloudreve；只论点对点交接文件，Pingvin Share X 这一类自建分享站，仍然是比公共网盘顺手得多的答案。&lt;/p&gt;
</content:encoded></item><item><title>PsiTransfer：连账号都不要的极简文件分享站</title><link>https://www.anexns.cloudns.org/posts/clouddrive-psitransfer/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/clouddrive-psitransfer/</guid><description>无账号、无登录，打开网页就能传大文件的自托管临时分享工具 PsiTransfer 部署与使用教程，含 Docker 部署、关键环境变量、反向代理注意事项与排障。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说主线：同是临时分享，它比 Pingvin Share 还要极端&lt;/h2&gt;
&lt;p&gt;上一篇写的 &lt;a href=&quot;/posts/clouddrive-pingvin-share/&quot;&gt;Pingvin Share&lt;/a&gt; 已经是临时分享里很轻量的选手了：链接分享、过期时间、密码、访客次数限制一应俱全。但它仍然保留了一套「正经服务」的骨架——要注册账号，要登录后台，要以用户为单位管理每一个分享。&lt;/p&gt;
&lt;p&gt;PsiTransfer 的取舍更极端：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;它干脆把账号体系整个删掉了。&amp;lt;/span&amp;gt;没有注册，没有登录，没有用户管理。打开网页，把文件拖进去，设一个过期时间，拿到链接发给对方，就这么多。对方下载完，或者到了过期时间，这批文件就自动消失。它对自己的定位非常清楚：不是网盘，不是文件库，就是一个「传完即走」的中转站，是 WeTransfer、Dropbox 这类商业临时分享服务的开源自托管替代。&lt;/p&gt;
&lt;p&gt;这种极简带来两个直接结果。一是部署和维护成本几乎为零：单个 Docker 容器，没有数据库，没有外部依赖，前端用 Vue 写、gzip 之后不到 100 KB，页面打开飞快。二是安全模型完全不同：既然没有账号，防护就不能靠「谁登录了」，只能靠上传口令、内网隔离这类外围手段——这一点后面会用整整一节讲，因为它正是 PsiTransfer 用得好不好的分水岭。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/psi-4ward/psitransfer&lt;/p&gt;
&lt;h2&gt;核心概念：一切围绕「桶」&lt;/h2&gt;
&lt;p&gt;PsiTransfer 里没有目录树的概念，取而代之的是「桶」（bucket）：一次上传的所有文件装进一个桶，每个桶有自己的链接、过期时间和下载规则。日常使用只要理解四个设定：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;过期时间&lt;/strong&gt;：上传时给桶设一个有效期，到期后文件自动删除，不需要人工清理。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;一次性下载&lt;/strong&gt;：可以把桶设为「下载一次即焚」，适合传敏感文件，对方取走就没了。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;下载密码&lt;/strong&gt;：桶的下载列表可以设密码保护，密码以 AES 加密保存；链接和密码分开发送更稳妥。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;自定义桶名&lt;/strong&gt;：链接里默认是随机 ID，但可以在上传时用 &lt;code&gt;sid=&amp;lt;名字&amp;gt;&lt;/code&gt; 参数指定桶名，生成一个好记、能口头念出来的链接，发给同事时直接报名字就行。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;其他日常够用的能力：支持同时传多个文件，单个文件可以非常大（流式传输，不把整个文件读进内存）；上传和下载都基于 tus.io 协议支持断点续传，网络断了接着传，不用从头再来；下载时可以把整个桶打包成 zip 或 tar.gz 一次拿走；常见格式有弹窗式文件预览。管理方面有一个 &lt;code&gt;/admin&lt;/code&gt; 页面，能看到所有桶的信息，但它默认是关闭的，必须先设置管理员密码才启用。&lt;/p&gt;
&lt;h2&gt;部署一：一条 docker run 命令&lt;/h2&gt;
&lt;p&gt;最快的上手方式，官方镜像是 &lt;code&gt;psitrax/psitransfer&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d --name psitransfer \
  -p 3000:3000 \
  -e PSITRANSFER_ADMIN_PASS=改成你的管理员密码 \
  -v $PWD/data:/data \
  psitrax/psitransfer
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;跑完打开 &lt;code&gt;http://服务器地址:3000&lt;/code&gt; 就是上传页面。镜像标签按需选：&lt;code&gt;latest&lt;/code&gt; 跟着主干分支，&lt;code&gt;2&lt;/code&gt; 是最新的 2.x 稳定版，&lt;code&gt;1.1&lt;/code&gt; 这类是指定小版本线；长期使用建议锁一个稳定大版本，别无脑追 &lt;code&gt;latest&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;这里有一个&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;必须当场处理、否则必踩的坑：数据卷的属主&amp;lt;/span&amp;gt;。容器内进程以 UID 1000 运行，挂进去的 &lt;code&gt;data&lt;/code&gt; 目录如果不归这个 UID 所有，上传就会失败，或者数据根本写不进去。启动容器前先执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p data
sudo chown -R 1000 data
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;部署二：docker compose（长期运行推荐）&lt;/h2&gt;
&lt;p&gt;打算长期挂着用的话，用 compose 管理更顺手，顺带把关键环境变量一次写齐：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  psitransfer:
    image: psitrax/psitransfer:2
    container_name: psitransfer
    restart: unless-stopped
    ports:
      - &quot;3000:3000&quot;
    environment:
      - PSITRANSFER_ADMIN_PASS=改成你的管理员密码
      - PSITRANSFER_UPLOAD_PASS=改成上传口令
    volumes:
      - ./data:/data
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;sudo chown -R 1000 ./data
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个密码的区别一定要分清：&lt;code&gt;PSITRANSFER_ADMIN_PASS&lt;/code&gt; 是 &lt;code&gt;/admin&lt;/code&gt; 管理页的密码，决定管理功能开不开；&lt;code&gt;PSITRANSFER_UPLOAD_PASS&lt;/code&gt; 是上传口令，决定「谁能往这个站里传文件」，这是公网部署时最关键的一个开关，下一节细说。&lt;/p&gt;
&lt;h2&gt;配置方式：环境变量优先&lt;/h2&gt;
&lt;p&gt;PsiTransfer 的配置有三层：环境变量、按环境分的配置文件、默认的 &lt;code&gt;config.js&lt;/code&gt;。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;环境变量&lt;/strong&gt;：统一用 &lt;code&gt;PSITRANSFER_&lt;/code&gt; 前缀，比如 &lt;code&gt;PSITRANSFER_UPLOAD_DIR&lt;/code&gt; 改上传数据目录。容器部署时这是最方便的方式，改完重启容器即生效。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;配置文件&lt;/strong&gt;：默认配置在 &lt;code&gt;config.js&lt;/code&gt;，端口、数据目录等都在里面，官方不建议直接改它；推荐新建 &lt;code&gt;config.production.js&lt;/code&gt; 这样的文件，文件名后缀对应 &lt;code&gt;NODE_ENV&lt;/code&gt; 的值，只写要覆盖的项。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;常用环境变量速查：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;环境变量&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;建议&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;PSITRANSFER_ADMIN_PASS&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;启用 &lt;code&gt;/admin&lt;/code&gt; 管理页并设置其密码&lt;/td&gt;
&lt;td&gt;必设，否则没有管理入口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;PSITRANSFER_UPLOAD_PASS&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;上传口令，不知道口令的人不能上传&lt;/td&gt;
&lt;td&gt;公网部署必设&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;PSITRANSFER_UPLOAD_DIR&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;上传文件的存放目录&lt;/td&gt;
&lt;td&gt;默认配合 &lt;code&gt;/data&lt;/code&gt; 挂卷即可，一般不用改&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;日常使用：一次完整的传递流程&lt;/h2&gt;
&lt;p&gt;实际用起来只有四步：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;上传&lt;/strong&gt;：打开首页，把文件拖进页面（也可以点选），可以一次拖多个。上传过程中页面会显示进度；中途断网也不用慌，tus 断点续传会在网络恢复后接着传，而不是从零开始。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;设定规则&lt;/strong&gt;：给这个桶定一个期限，比如一天、一周；需要的话勾上一次性下载，再给下载列表加个密码。这一步决定了这批文件的「寿命」和「门槛」。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;发链接&lt;/strong&gt;：把桶的链接发给对方。想让链接好记一点，上传时带上 &lt;code&gt;sid=&amp;lt;名字&amp;gt;&lt;/code&gt; 指定桶名，生成的链接里就是这个名字，不用对着一串随机字符反复核对。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;收尾&lt;/strong&gt;：什么都不用做。到期自动删除，一次性下载被取走后自动销毁；想提前清掉，去 &lt;code&gt;/admin&lt;/code&gt; 里手动删桶即可。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;有一个容易忽略的细节：PsiTransfer 的桶是「一批文件一个链接」，不是「一个文件一个链接」。给同一个人发十个文件，装进同一个桶、发一条链接就行，对方还能在下载页把整个桶打包成 zip 或 tar.gz 一次拿走，比逐个文件发链接清爽得多。&lt;/p&gt;
&lt;p&gt;另外补一句数据层面的事：PsiTransfer 没有数据库，桶的信息和文件都落在数据目录里，所以备份和迁移都很原始、也很可靠——停掉容器，把 &lt;code&gt;data&lt;/code&gt; 目录整个打包带走，恢复时放回去、确认属主仍是 UID 1000 即可。反过来说，这个目录丢了就是全丢，长期运行的话，建议把它纳入你现有的服务器备份节奏里。&lt;/p&gt;
&lt;h2&gt;安全：没有账号，意味着防线只有两道&lt;/h2&gt;
&lt;p&gt;:::warning
PsiTransfer 没有任何账号体系，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;默认状态下，谁拿到网址谁就能上传文件&amp;lt;/span&amp;gt;。把默认部署直接暴露在公网，等于开了一个全世界可写的公开上传站：轻则硬盘被塞满，重则被人拿来分发违规文件，锅全在站长头上。公网使用必须二选一：设置 &lt;code&gt;PSITRANSFER_UPLOAD_PASS&lt;/code&gt; 给上传加口令，或者只放在内网、仅通过内网穿透或 VPN 访问，绝不要裸奔。另外官方明确说明：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;PsiTransfer 没有端到端加密&amp;lt;/span&amp;gt;，文件在服务器上是明文存放的，下载密码保护的只是列表的访问。它适合传「不怕被服务器管理员看到、但要控制谁能下载」的文件；真正的机密文件请先在本地加密再上传，或者改用有完整账号与权限体系的方案。
:::&lt;/p&gt;
&lt;p&gt;除此之外，常规加固同样适用：前面套一层带 HTTPS 的反向代理；定期去 &lt;code&gt;/admin&lt;/code&gt; 看有没有陌生桶；对数据目录所在磁盘的容量心里有数——临时分享站最常见的事故不是被黑，而是被当成免费图床、免费网盘刷爆磁盘。&lt;/p&gt;
&lt;h2&gt;反向代理：大文件上传的三个注意点&lt;/h2&gt;
&lt;p&gt;PsiTransfer 自己只监听 3000 端口的 HTTP，对外服务一般在前面加 Nginx 或 Caddy 做 HTTPS 和域名入口。因为它主打大文件和断点续传，反代配置有三个地方和普通站点不同：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;放开请求体大小&lt;/strong&gt;：Nginx 默认的 &lt;code&gt;client_max_body_size&lt;/code&gt; 只有 1 MB，不改的话大文件上传会直接被拦下。按实际需求调大，比如写 &lt;code&gt;client_max_body_size 0;&lt;/code&gt; 表示不限制，或者给一个明确上限如 &lt;code&gt;10g&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;关掉请求缓冲&lt;/strong&gt;：tus 断点续传是分片流式上传的，反代如果把整个请求缓冲完再转发，续传和上传进度都会出问题。Nginx 里给对应的 location 加上 &lt;code&gt;proxy_request_buffering off;&lt;/code&gt;，让分片直接透传。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;拉长超时&lt;/strong&gt;：慢速网络传几个 GB 的文件可能要几十分钟，&lt;code&gt;proxy_read_timeout&lt;/code&gt; 和 &lt;code&gt;proxy_send_timeout&lt;/code&gt; 都要给足，比如 3600s，避免传到一半被代理掐断。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Nginx 示例（关键行）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    client_max_body_size 0;
    proxy_request_buffering off;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;和 Pingvin Share 怎么选&lt;/h2&gt;
&lt;p&gt;两者都是临时分享，气质却完全不同，放一张表说清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;PsiTransfer&lt;/th&gt;
&lt;th&gt;Pingvin Share&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;账号体系&lt;/td&gt;
&lt;td&gt;完全没有，打开即用&lt;/td&gt;
&lt;td&gt;有用户注册与登录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;分享管理&lt;/td&gt;
&lt;td&gt;以「桶」为单位，过期自动删&lt;/td&gt;
&lt;td&gt;以分享为单位，功能更细&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;过期与次数&lt;/td&gt;
&lt;td&gt;过期时间、一次性下载&lt;/td&gt;
&lt;td&gt;过期时间、访客次数上限、密码&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;邮件通知收件人&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;有&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;反向分享（让别人传给你）&lt;/td&gt;
&lt;td&gt;无（它本身就是上传页）&lt;/td&gt;
&lt;td&gt;有 Reverse Share&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;第三方登录&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;支持 OIDC、LDAP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;病毒扫描&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;可集成 ClamAV&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;存储后端&lt;/td&gt;
&lt;td&gt;本地目录&lt;/td&gt;
&lt;td&gt;本地或 S3&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;上手成本&lt;/td&gt;
&lt;td&gt;一条命令，页面极简&lt;/td&gt;
&lt;td&gt;功能多，配置项也多&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合场景&lt;/td&gt;
&lt;td&gt;自己人之间快速传大文件&lt;/td&gt;
&lt;td&gt;对外发文件、需要管理和审计&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;简单说：给同事、朋友传个几 GB 的素材包，越快越好、传完拉倒，PsiTransfer 是最优解；要长期对外提供下载、需要知道谁下载过、想要品牌化页面和登录体系，选 &lt;a href=&quot;/posts/clouddrive-pingvin-share/&quot;&gt;Pingvin Share&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;上传失败、文件存不进去、容器日志报权限错误&lt;/strong&gt;
十有八九是数据卷属主不对。容器内进程是 UID 1000，在宿主机上执行 &lt;code&gt;sudo chown -R 1000 ./data&lt;/code&gt; 后重启容器即可。这也是从 docker run 换到 compose、或者迁移服务器之后最容易复发的问题：迁移数据目录时，记得连属主一起处理。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;/admin&lt;/code&gt; 打开是空白或者报错&lt;/strong&gt;
管理页默认禁用，没设 &lt;code&gt;PSITRANSFER_ADMIN_PASS&lt;/code&gt; 时它就是不存在的。给容器加上这个环境变量并重启，再访问 &lt;code&gt;/admin&lt;/code&gt;，用该密码登录，就能看到所有桶的信息。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;任何人都能往我的站里传文件&lt;/strong&gt;
这是默认行为，不是 Bug。立刻设置 &lt;code&gt;PSITRANSFER_UPLOAD_PASS&lt;/code&gt; 并重启容器；如果已经被刷了，先去 &lt;code&gt;/admin&lt;/code&gt; 清掉陌生桶，再检查数据目录的占用情况。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;大文件传到一半失败，但直连 3000 端口正常&lt;/strong&gt;
基本是反向代理的问题，按上一节逐项核对：&lt;code&gt;client_max_body_size&lt;/code&gt; 是否放开、&lt;code&gt;proxy_request_buffering&lt;/code&gt; 是否关闭、读写超时是否足够。tus 续传能救回大部分网络中断，但代理直接拒绝请求时它也无能为力。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;下载链接提示已失效&lt;/strong&gt;
先确认是不是自己设的过期时间到了，或者这个桶被设成了一次性下载、且已经被下载过一次。这两种都是按设计销毁，不是故障；桶的具体状态在 &lt;code&gt;/admin&lt;/code&gt; 里能看到。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;改了环境变量却不生效&lt;/strong&gt;
环境变量是容器启动那一刻读进去的，只修改 compose 文件、或者只在宿主机上 &lt;code&gt;export&lt;/code&gt;，都不会自动生效。改完配置后执行一次 &lt;code&gt;docker compose up -d&lt;/code&gt;，compose 会在配置变化时重建容器；如果是用 docker run 起的，就删掉旧容器按新参数重新 run。改完别凭感觉判断，去上传页实际传一个文件、再进 &lt;code&gt;/admin&lt;/code&gt; 看一眼，确认新配置真的在工作。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;想改端口或数据目录，改完重启又没了&lt;/strong&gt;
不要直接改容器里的 &lt;code&gt;config.js&lt;/code&gt;，容器重建就恢复原样。用 &lt;code&gt;PSITRANSFER_&lt;/code&gt; 前缀的环境变量覆盖，或者把 &lt;code&gt;config.production.js&lt;/code&gt; 挂载进容器，保证配置在重建之后还在。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;PsiTransfer 是那种「小而明确」的工具：它把临时分享这件事做到了减法的极致——没有账号、没有数据库、没有花哨功能，只剩下上传、过期、密码、一次性下载这几个真正高频的动作，再加上 tus 断点续传为大文件兜底。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;如果你的需求就是「给自己人快速传大文件，传完自动清」，它比任何带账号体系的方案都省心。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;在整个网盘系列里，它的位置也很清楚：长期存放、要目录树要权限，用 &lt;a href=&quot;/posts/selfhost-cloudreve/&quot;&gt;Cloudreve&lt;/a&gt; 这类正经网盘；完全不想维护服务器，用 &lt;a href=&quot;/posts/clouddrive-davflare/&quot;&gt;Davflare&lt;/a&gt; 把文件放在 Cloudflare R2 上；而 PsiTransfer 只负责一种场景——临时中转。用对地方，它就是那个装上之后你会忘记它存在的工具，这恰恰是对基础设施工具最好的评价。&lt;/p&gt;
</content:encoded></item><item><title>Rclone：云存储界的 rsync，一条命令管遍所有网盘</title><link>https://www.anexns.cloudns.org/posts/clouddrive-rclone/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/clouddrive-rclone/</guid><description>Rclone 把 S3、Google Drive、OneDrive、WebDAV 等一百多种存储统一成同一套命令行：配置 remote、copy/sync/bisync 同步、mount 挂载、crypt 加密与 serve 暴露，一次讲透。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说主线：rsync 之于本地文件，Rclone 之于云存储&lt;/h2&gt;
&lt;p&gt;老一代运维对 rsync 的感情很深：两个目录之间增量同步，一条命令、几个参数，文件就稳稳地从这台机器搬到那台机器，搬完还逐个校验哈希，出错一眼可见。但 rsync 有个天然边界——它只认本地文件系统和 SSH，管不了躺在云端的那些存储：对象存储的桶、网盘的目录、另一台服务器的 WebDAV，各家有各家的客户端、各家的同步逻辑，拼在一起就是一场灾难。&lt;/p&gt;
&lt;p&gt;Rclone 就是冲着这个边界来的。它自称「云存储界的 rsync」：把一百多种存储后端（S3、Google Drive、OneDrive、Dropbox、Backblaze B2、Cloudflare R2、WebDAV、SFTP、SMB、MEGA、Proton Drive、iCloud Drive，乃至本地文件系统）全部抽象成同一种叫 remote 的东西，然后用同一套命令在任意两个 remote 之间复制、同步、校验、挂载。你学会的不是某一家网盘的用法，而是一种「存储之间搬运文件」的通用语言。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/rclone/rclone&lt;/p&gt;
&lt;p&gt;这一篇的主线是：装好 Rclone → 配置第一个 remote → 用 copy / sync / bisync 做同步备份 → 用 mount 把网盘挂成本地目录 → 用 crypt 给云端文件加一层透明加密 → 最后用 serve 把存储反向暴露成 WebDAV 等协议。全部场景只讲一件事：&lt;strong&gt;自己文件在自己账号之间同步与备份&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;它能接什么：后端与虚拟后端&lt;/h2&gt;
&lt;p&gt;Rclone 的能力分两层。第一层是真实后端，即它能直连的存储，官方支持的数量早已过百，常见的有：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类别&lt;/th&gt;
&lt;th&gt;代表后端&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;对象存储&lt;/td&gt;
&lt;td&gt;Amazon S3、Cloudflare R2、Backblaze B2、Google Cloud Storage、Azure Blob、七牛、腾讯 COS 等 S3 兼容存储&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;个人网盘&lt;/td&gt;
&lt;td&gt;Google Drive、OneDrive、Dropbox、MEGA、Proton Drive、iCloud Drive、pCloud 等&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;协议型&lt;/td&gt;
&lt;td&gt;WebDAV、SFTP、FTP、SMB/CIFS、HTTP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本地&lt;/td&gt;
&lt;td&gt;本地文件系统（local）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;第二层是虚拟后端，它们不存文件，而是套在其他 remote 外面改变行为，这一层才是 Rclone 真正拉开差距的地方：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;虚拟后端&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;crypt&lt;/td&gt;
&lt;td&gt;透明加密：文件名和内容在上传前加密，云端看到的全是密文&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;chunker&lt;/td&gt;
&lt;td&gt;把大文件切块存储，绕开单个文件大小上限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;union / combine&lt;/td&gt;
&lt;td&gt;把多个 remote 合并成一个目录树，对外像一个大盘&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;compress&lt;/td&gt;
&lt;td&gt;透明压缩，省空间省流量&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;alias / hasher&lt;/td&gt;
&lt;td&gt;给 remote 起别名 / 专门做哈希校验&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;举个例子：你可以把「R2 的某个桶」套上 crypt，得到一个加密 remote，再套上 chunker 处理大文件——组合全部在配置里完成，命令层毫无感知。本系列上一篇把网盘搭在 R2 上的 &lt;a href=&quot;/posts/clouddrive-davflare/&quot;&gt;Davflare&lt;/a&gt; 解决的是「存」，Rclone 解决的是「搬」，两者正好互补。&lt;/p&gt;
&lt;h2&gt;安装&lt;/h2&gt;
&lt;p&gt;官方安装脚本是最省事的路线，Linux 和 macOS 通用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl https://rclone.org/install.sh | sudo bash
rclone version
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;各发行版的包管理器里一般也有，但版本往往偏旧，Rclone 迭代很快，建议优先用官方脚本或官网的预编译包。Windows 在官网下载 zip 解压即可，把 &lt;code&gt;rclone.exe&lt;/code&gt; 放进 PATH。&lt;/p&gt;
&lt;p&gt;Docker 部署用官方镜像，适合放在 NAS 或服务器上常驻跑同步任务：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run --rm -it \
  -v ~/.config/rclone:/config/rclone \
  -v ~/data:/data \
  rclone/rclone lsd remote:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意配置目录要挂出来持久化，否则容器一删，所有 remote 配置都得重配。&lt;/p&gt;
&lt;h2&gt;配置 remote：rclone config&lt;/h2&gt;
&lt;p&gt;Rclone 的全部配置存在一个配置文件里（默认 &lt;code&gt;~/.config/rclone/rclone.conf&lt;/code&gt;），管理入口是交互式命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;rclone config
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;以接一个 Cloudflare R2 桶为例，走一遍流程：选 &lt;code&gt;n&lt;/code&gt; 新建 remote，名字起为 &lt;code&gt;r2&lt;/code&gt;，存储类型选 &lt;code&gt;s3&lt;/code&gt;，提供商选 &lt;code&gt;Cloudflare&lt;/code&gt;，随后填 Access Key ID、Secret Access Key 和 R2 的 S3 端点地址，区域等其余项一路回车用默认值即可。配置完成后用两条命令验收：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;rclone lsd r2:            # 列出桶
rclone ls r2:mybucket     # 列出桶内文件
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;不想交互点选，也可以直接写配置文件，脚本化部署时更常用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[r2]
type = s3
provider = Cloudflare
access_key_id = 你的AccessKeyID
secret_access_key = 你的SecretAccessKey
endpoint = https://&amp;lt;account-id&amp;gt;.r2.cloudflarestorage.com
acl = private
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;WebDAV、SFTP 这类后端同理，&lt;code&gt;rclone config&lt;/code&gt; 里选对应类型填地址和账号即可。家里已经有 &lt;a href=&quot;/posts/selfhost-nextcloud-onlyoffice/&quot;&gt;Nextcloud&lt;/a&gt; 的话，把它作为一个 WebDAV remote 接进来，后面所有同步命令立刻就能用在它身上。&lt;/p&gt;
&lt;h2&gt;核心命令：copy、sync、bisync 别用混&lt;/h2&gt;
&lt;p&gt;这是 Rclone 最该讲清的一节。三个命令长得像，语义差别却能决定数据生死：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;行为&lt;/th&gt;
&lt;th&gt;目标端多余文件&lt;/th&gt;
&lt;th&gt;典型用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;copy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;把源端新增/变化的文件复制到目标端&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;保留，不删&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;增量备份、上传归档&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;sync&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;让目标端与源端&lt;strong&gt;完全一致&lt;/strong&gt;（单向镜像）&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;删除&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;镜像同步、发布目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;bisync&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;双向同步，两边的新变化互相合并&lt;/td&gt;
&lt;td&gt;按规则处理冲突&lt;/td&gt;
&lt;td&gt;两台设备共同编辑同一目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;check&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只校验不传输，比对哈希与数量&lt;/td&gt;
&lt;td&gt;不动&lt;/td&gt;
&lt;td&gt;同步后验收、定期巡检&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;日常命令长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 增量备份：本地文档 → R2 桶，只增不删
rclone copy ~/Documents r2:backup/Documents -P

# 镜像同步：让目标端和源端一模一样（危险，见下方警告）
rclone sync ~/Photos remote:Photos -P

# 同步完验收：核对文件数与哈希
rclone check ~/Documents r2:backup/Documents

# 双向同步：第一次必须带 --resync 建立基线
rclone bisync ~/Work workremote:Work --resync
rclone bisync ~/Work workremote:Work
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个细节值得记住：传输全程做 MD5/SHA-1 完整性校验并保留文件时间戳；&lt;code&gt;-P&lt;/code&gt; 显示实时进度；&lt;code&gt;--transfers 8&lt;/code&gt; 可以调高并发，多线程下载和分块传输对大文件很友好；过滤规则用 &lt;code&gt;--include&lt;/code&gt; / &lt;code&gt;--exclude&lt;/code&gt; 或 &lt;code&gt;--filter-from&lt;/code&gt; 文件来控制搬哪些、不搬哪些。&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;code&gt;sync&lt;/code&gt; 会删除目标端存在、但源端没有的文件&amp;lt;/span&amp;gt;，这是它「镜像」语义的一部分，不是 bug。路径写反一次，删的就是源端那份心血。所以铁律是：&lt;strong&gt;任何 sync / bisync 第一次跑之前，先加 &lt;code&gt;--dry-run&lt;/code&gt; 空跑一遍&lt;/strong&gt;，看它打印的删除清单是否符合预期，确认无误再去掉参数真跑。养成这个习惯，比任何备份策略都管用——因为 sync 本身就是最常见的「备份误删」现场。
:::&lt;/p&gt;
&lt;h2&gt;mount：把网盘挂成本地目录&lt;/h2&gt;
&lt;p&gt;同步是「批处理」式的搬运，mount 则把 remote 直接变成一个本地目录，文件随开随取。Linux 和 macOS 靠 FUSE 实现：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/mnt/drive
rclone mount gdrive: ~/mnt/drive --vfs-cache-mode full --daemon
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--vfs-cache-mode full&lt;/code&gt; 是关键参数：它让 Rclone 用本地磁盘做读写缓存，普通应用（编辑器、播放器、Office）才能像操作本地文件一样读写挂载盘；不加的话很多程序会因为不支持随机写而报错。&lt;code&gt;--daemon&lt;/code&gt; 让它在后台运行。&lt;/p&gt;
&lt;p&gt;想开机自动挂载，用 systemd 托管最稳妥，新建 &lt;code&gt;~/.config/systemd/user/rclone-drive.service&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Unit]
Description=Rclone mount Google Drive
After=network-online.target
Wants=network-online.target

[Service]
Type=notify
ExecStart=/usr/bin/rclone mount gdrive: %h/mnt/drive \
  --vfs-cache-mode full \
  --vfs-cache-max-size 10G \
  --dir-cache-time 12h
ExecStop=/bin/fusermount -u %h/mnt/drive
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;systemctl --user daemon-reload
systemctl --user enable --now rclone-drive
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;需要说明的是：mount 适合「偶尔取用、在线编辑文档」这类轻量场景，它的性能和可靠性终究受网络与缓存策略制约。真要把一堆网盘&lt;strong&gt;聚合展示&lt;/strong&gt;成一个网页文件站，那是 &lt;a href=&quot;/posts/selfhost-alist/&quot;&gt;Alist&lt;/a&gt; 的活；mount 的优势是透明——所有本地程序都能直接用，不需要任何适配。&lt;/p&gt;
&lt;h2&gt;crypt：给云端文件加一层透明加密&lt;/h2&gt;
&lt;p&gt;把文件放进第三方网盘，哪怕只是自己的照片和文档，很多人心里还是有个疙瘩：服务商理论上能看到内容。crypt 虚拟后端就是为此而生：它套在任意 remote 外面，上传前在本地加密文件名和文件内容，云端存的全是密文，下载时再解密回来。&lt;/p&gt;
&lt;p&gt;配置方式还是 &lt;code&gt;rclone config&lt;/code&gt;：新建 remote，类型选 &lt;code&gt;crypt&lt;/code&gt;，它会让你选一个已有的 remote 作为底层（比如 &lt;code&gt;r2:encrypted&lt;/code&gt; 这个路径），然后设置两组密码——加密密码和盐值密码。完成后你得到一个新 remote，比如叫 &lt;code&gt;secret:&lt;/code&gt;，之后所有命令对着它用就行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;rclone copy ~/Private secret: -P     # 上传即加密
rclone ls secret:                    # 看到的是解密后的文件名
rclone ls r2:encrypted               # 绕过 crypt 直看底层，全是密文名
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;crypt 的密码和盐值一旦丢失，云端那份数据就永远解不开了&amp;lt;/span&amp;gt;，没有任何找回通道——这正是端到端加密的另一面。配置完成后，立刻把这两组密码和整个 &lt;code&gt;rclone.conf&lt;/code&gt; 备份到密码管理器与离线介质里各一份。另外注意：配置文件本身是明文存密码的，所在机器的磁盘权限要收紧，别把 rclone.conf 随手同步到公共网盘上，那就等于把钥匙和锁放在了一起。
:::&lt;/p&gt;
&lt;h2&gt;serve：把存储反向暴露成协议服务&lt;/h2&gt;
&lt;p&gt;最后一个方向是反着来的：Rclone 不光能「消费」各种协议，还能把任意 remote 以标准协议「提供」出去：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 把某个 remote 暴露成 WebDAV 服务
rclone serve webdav r2:mybucket --addr :8080 --user admin --pass &apos;改成强密码&apos;

# 同理还有 http / ftp / sftp / dlna
rclone serve http ~/Media --addr :8081
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这一招的妙处是给老设备和老软件续命：某个播放器只认 WebDAV、某个备份工具只认 FTP，而你的文件实际躺在 R2 里——中间用 &lt;code&gt;rclone serve&lt;/code&gt; 转译一层即可。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;serve 默认没有加密传输，对外暴露时务必加账号密码，并放在反向代理之后走 HTTPS&amp;lt;/span&amp;gt;，别裸奔在公网上。&lt;/p&gt;
&lt;h2&gt;典型组合：三条现成的流水线&lt;/h2&gt;
&lt;p&gt;把上面的零件拼起来，日常最常用的组合是这三条：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;服务器定时备份到 R2。&lt;/strong&gt; 用 copy 做增量，配 cron 每天跑一次，再套一层 crypt，备份文件在云端就是密文：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# crontab -e，每天凌晨 3:30 增量备份并记录日志
30 3 * * * /usr/bin/rclone copy /srv/data secret:server-backup --log-file=/var/log/rclone-backup.log --log-level INFO
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;两个网盘之间互备。&lt;/strong&gt; 不需要先下载到本地中转，remote 对 remote 直接传：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;rclone sync gdrive:Docs onedrive:Docs-backup --dry-run   # 先空跑看清单
rclone sync gdrive:Docs onedrive:Docs-backup -P          # 确认后执行
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;本地工作目录与网盘双向同步。&lt;/strong&gt; 用 bisync，让笔记本和台式机通过网盘保持同一份工作目录；冲突时 Rclone 会保留冲突副本并报错提醒，不会静默覆盖，处理完冲突再跑一次即可。&lt;/p&gt;
&lt;p&gt;这套「一个工具接所有存储」的思路，和 &lt;a href=&quot;/posts/clouddrive-clouddrive2/&quot;&gt;CloudDrive2&lt;/a&gt; 把网盘挂载成本地盘是两种不同的解法：CloudDrive2 胜在图形界面与系统级挂载，Rclone 胜在脚本化、无人值守和加密能力，两者按场景分工并不冲突。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;报错 &lt;code&gt;didn&apos;t find section in config file&lt;/code&gt; 或找不到 remote&lt;/strong&gt;：remote 名字写错，或当前用户读的不是那份配置。用 &lt;code&gt;rclone config file&lt;/code&gt; 确认实际配置文件路径，Docker 部署则检查配置卷有没有挂对。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Google Drive 等 OAuth 后端在无桌面服务器上配不了&lt;/strong&gt;：授权需要浏览器。在本地电脑上配好同一 remote，再把 &lt;code&gt;rclone.conf&lt;/code&gt; 拷到服务器；或者用 &lt;code&gt;rclone authorize&lt;/code&gt; 在本地生成 token 粘回去。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;sync 后发现目标端少了文件&lt;/strong&gt;：多半是把源和目标写反，或者源路径指到了空目录。先停任务，用 &lt;code&gt;rclone check&lt;/code&gt; 对照两端清单，再从备份或网盘回收站里找回——这也是为什么第一节要反复强调 &amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;sync 前先 --dry-run&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;mount 后应用打不开文件 / 保存失败&lt;/strong&gt;：基本是没加 &lt;code&gt;--vfs-cache-mode full&lt;/code&gt;，或缓存盘空间不足。加上参数并用 &lt;code&gt;--vfs-cache-max-size&lt;/code&gt; 给缓存留够上限。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;传输速度慢&lt;/strong&gt;：先调 &lt;code&gt;--transfers&lt;/code&gt; 与 &lt;code&gt;--checkers&lt;/code&gt; 并发；大文件多时加 &lt;code&gt;--multi-thread-streams&lt;/code&gt;；怀疑被服务商限速时降并发反而更稳，别一味拉高。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;bisync 频繁报冲突或要求 resync&lt;/strong&gt;：通常是两边同时改了同一文件，或某次同步被强行中断破坏了基线。按提示重新 &lt;code&gt;--resync&lt;/code&gt; 建立基线，之后尽量避免双端同时编辑同一文件。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Rclone 的价值不在某个具体功能，而在于它把「在一百多种存储之间搬文件」这件事收敛成了一套统一语义：remote 是存储，copy / sync / bisync 是搬运规则，mount 是透明化，crypt 是保密层，serve 是转译层。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;只要文件还在你自己的账号之间流转，Rclone 几乎总是那个最短路径的答案。&amp;lt;/span&amp;gt;上手顺序就按本文来：先 config 接通一个 remote，用 copy 跑通第一次增量备份，把 &lt;code&gt;--dry-run&lt;/code&gt; 变成肌肉记忆，再逐步打开 mount 与 crypt——到这一步，你的网盘们就不再是各自为政的孤岛了。&lt;/p&gt;
</content:encoded></item><item><title>Docker 构建加速进阶：缓存挂载、远程缓存与并行构建</title><link>https://www.anexns.cloudns.org/posts/docker-build-acceleration/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-build-acceleration/</guid><description>CI 里改一行代码等十分钟构建，多半是缓存没用对。缓存挂载、secret 挂载、registry 远程缓存、依赖层分离与多阶段并行，把构建时间压下来。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;改一行前端代码，推上去，CI 转了十分钟才把镜像构建完——这种等待多半不是机器慢，而是构建姿势不对：依赖每次都从零下载、缓存只存在于某台机器的本地、几个互不相干的阶段排着队串行跑。层缓存的原理和基础用法在 &lt;a href=&quot;/posts/docker-buildkit-cache/&quot;&gt;BuildKit 缓存篇&lt;/a&gt; 里已经讲过，这一篇不重复，只讲进阶招：让下载的包跨构建复用、让 CI 也吃上缓存、让构建期密钥不留痕、让能并行的阶段一起跑。&lt;/p&gt;
&lt;p&gt;先说结论：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;构建加速的顺序是先定位慢在哪一段，再对症下药，盲目加机器往往没用。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;先分清：慢在哪一段&lt;/h2&gt;
&lt;p&gt;一次 &lt;code&gt;docker build&lt;/code&gt; 的耗时大致分三段，每段的解法完全不同：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;阶段&lt;/th&gt;
&lt;th&gt;慢的表现&lt;/th&gt;
&lt;th&gt;对应解法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;传上下文&lt;/td&gt;
&lt;td&gt;构建刚开始就卡在 &quot;sending build context&quot;，几十秒没动静&lt;/td&gt;
&lt;td&gt;&lt;code&gt;.dockerignore&lt;/code&gt; 砍掉大目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;装依赖&lt;/td&gt;
&lt;td&gt;每次都重新 &lt;code&gt;pip install&lt;/code&gt; / &lt;code&gt;npm install&lt;/code&gt; / &lt;code&gt;apt-get install&lt;/code&gt;，流量跑满&lt;/td&gt;
&lt;td&gt;缓存挂载、依赖层分离&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;编译与打包&lt;/td&gt;
&lt;td&gt;CPU 打满，编译型语言尤其明显&lt;/td&gt;
&lt;td&gt;多阶段并行、远程缓存复用别人的构建结果&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;先用最粗暴的方法量化一下，知道时间花在哪：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 冷构建：完全不用缓存
time docker build --no-cache -t myapp:cold .

# 热构建：改一行代码后立刻再构建一次
time docker build -t myapp:hot .

# 看每一层都是谁、多大
docker history myapp:hot
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个时间差得越多，说明缓存越值得折腾；&lt;code&gt;docker history&lt;/code&gt; 则能看出哪个层异常肥。下面逐段拆解。&lt;/p&gt;
&lt;h2&gt;缓存挂载：下载过的包不要再下第二遍&lt;/h2&gt;
&lt;p&gt;层缓存有个先天短板：只要某一层的输入变了，这一层和它之后的所有层全部重来。&lt;code&gt;pip install&lt;/code&gt; 这种命令最吃亏——&lt;code&gt;requirements.txt&lt;/code&gt; 没变还好，一旦加了个包，整层作废，几十个包全部重新下载。&lt;/p&gt;
&lt;p&gt;BuildKit 的缓存挂载（cache mount）就是来补这个短板的：把下载缓存目录挂成一个&lt;strong&gt;独立于镜像层的持久缓存&lt;/strong&gt;，构建时挂进来用，构建完卸走，缓存本身不进镜像、不会让镜像变胖，但下次构建还在。&lt;/p&gt;
&lt;p&gt;用它之前，Dockerfile 第一行先声明语法版本，这是所有 &lt;code&gt;--mount&lt;/code&gt; 玩法的总开关：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# syntax=docker/dockerfile:1
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;pip：Python 项目&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# syntax=docker/dockerfile:1
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt
COPY . .
CMD [&quot;python&quot;, &quot;app.py&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第一次构建照常下载，但 wheel 全部留在缓存里；之后哪怕 &lt;code&gt;requirements.txt&lt;/code&gt; 变了、层缓存失效，pip 也会先翻本地缓存，只下新增的那几个包。&lt;/p&gt;
&lt;h3&gt;npm：Node 项目&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# syntax=docker/dockerfile:1
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json .
RUN --mount=type=cache,target=/root/.npm \
    npm ci
COPY . .
CMD [&quot;node&quot;, &quot;server.js&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;apt：系统包&lt;/h3&gt;
&lt;p&gt;apt 比较特殊，要挂两个目录，而且得关掉 apt 自带的列表清理、并删掉 Docker 镜像里那个强制清缓存的配置，否则缓存留不住：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# syntax=docker/dockerfile:1
FROM debian:bookworm-slim
RUN rm -f /etc/apt/apt.conf.d/docker-clean \
    &amp;amp;&amp;amp; --mount=type=cache,target=/var/cache/apt,sharing=locked \
       --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \
       apt-get update \
    &amp;amp;&amp;amp; apt-get install -y --no-install-recommends curl git
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个细节：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;sharing=locked&lt;/code&gt;：多个构建并发时排队用同一份缓存。apt 的缓存被并发写容易出问题，官方示例就带 locked；pip、npm 一般可以省略，用默认的 shared。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;id=&lt;/code&gt; 命名：&lt;code&gt;--mount=type=cache,id=myname,target=...&lt;/code&gt; 可以给缓存起名字。多个项目共用一台构建机时，用 id 把缓存隔开，避免互相污染；不写 id 时默认按 target 路径区分。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code&gt;sharing&lt;/code&gt; 一共三档，按工具的脾气选：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;sharing 取值&lt;/th&gt;
&lt;th&gt;行为&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;shared&lt;/code&gt;（默认）&lt;/td&gt;
&lt;td&gt;多个构建同时读写同一份缓存&lt;/td&gt;
&lt;td&gt;pip、npm 这类自己带锁或不怕并发写的工具&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;locked&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;同一时间只允许一个构建用，其余排队等&lt;/td&gt;
&lt;td&gt;apt，以及任何并发写会损坏缓存的工具&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;private&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每个构建用自己独立的一份缓存，互不共享&lt;/td&gt;
&lt;td&gt;只想保住&quot;有缓存&quot;又怕被别人污染时&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选错的代价不对称：该 locked 的用了 shared，可能缓存损坏、构建随机失败；该 shared 的用了 private，只是没吃到共享红利，慢一点而已。拿不准工具脾气时，先按官方示例抄，跑稳了再调。&lt;/p&gt;
&lt;h2&gt;secret 挂载：构建期密钥别写进镜像&lt;/h2&gt;
&lt;p&gt;有些构建步骤必须要密钥：拉私有 npm 源、下载授权字体、调内部 API。最常见的错误写法是把它塞进构建参数：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 反面教材：千万别这样传密钥
docker build --build-arg NPM_TOKEN=xxxx .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
用 ARG 传密钥，值会被记进镜像的构建历史，任何人拿到镜像跑一遍 &lt;code&gt;docker history --no-trunc&lt;/code&gt; 就能把密钥读出来。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;ARG 传进的密钥等于明文印在镜像上，镜像推到哪，密钥泄到哪。&amp;lt;/span&amp;gt;
:::&lt;/p&gt;
&lt;p&gt;正确做法是 secret 挂载：构建时把密钥文件临时挂进构建容器，默认出现在 &lt;code&gt;/run/secrets/&amp;lt;id&amp;gt;&lt;/code&gt;，只在那一条 &lt;code&gt;RUN&lt;/code&gt; 执行期间存在，不落层、不进历史：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# syntax=docker/dockerfile:1
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json .
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) npm ci
COPY . .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;构建命令对应着给：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker build --secret id=npm_token,src=./.npm_token -t myapp .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;顺带提一句，同类还有 &lt;code&gt;--mount=type=ssh&lt;/code&gt;：构建时借用宿主机的 SSH Agent 拉私有 Git 仓库代码，私钥同样不落盘进镜像，写依赖私有仓库的项目时很顺手。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;传密钥方式&lt;/th&gt;
&lt;th&gt;密钥去向&lt;/th&gt;
&lt;th&gt;安全性&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ENV&lt;/code&gt; 写死在 Dockerfile&lt;/td&gt;
&lt;td&gt;镜像配置里明文&lt;/td&gt;
&lt;td&gt;最差，等于公开&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ARG&lt;/code&gt; 构建参数&lt;/td&gt;
&lt;td&gt;记入构建历史，&lt;code&gt;docker history&lt;/code&gt; 可读&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;差，镜像分发即泄密&amp;lt;/span&amp;gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--mount=type=secret&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只在单条 RUN 期间以文件出现&lt;/td&gt;
&lt;td&gt;好，不落层不进历史&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;远程缓存：让 CI 也吃上缓存&lt;/h2&gt;
&lt;p&gt;本地构建快不算本事——CI 每次都是全新机器，本地缓存一点用不上，这才是&quot;改一行等十分钟&quot;的主战场。解法是把缓存导出到镜像仓库里，下次构建先从仓库把缓存拉回来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker buildx build \
  --cache-from type=registry,ref=registry.example.com/myapp:cache \
  --cache-to type=registry,ref=registry.example.com/myapp:cache,mode=max \
  -t registry.example.com/myapp:latest \
  --push .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个参数分工明确：&lt;code&gt;--cache-from&lt;/code&gt; 负责拉，&lt;code&gt;--cache-to&lt;/code&gt; 负责推。关键在 &lt;code&gt;mode=max&lt;/code&gt;：默认的 &lt;code&gt;mode=min&lt;/code&gt; 只导出最终镜像用到的层，中间阶段（比如专门装依赖、做编译的 stage）的缓存不会导出，下次构建还是得重跑；&lt;code&gt;mode=max&lt;/code&gt; 把全部中间层都导出去，代价是推拉的缓存体积更大，但 CI 场景下这笔账划算。&lt;/p&gt;
&lt;p&gt;它和 &lt;a href=&quot;/posts/docker-buildx-multiarch/&quot;&gt;buildx 多架构构建&lt;/a&gt; 是同一套工具链，命令骨架完全一致，学会一个等于会了两个。在 GitHub Actions 里还有个专用后端 &lt;code&gt;--cache-to type=gha&lt;/code&gt;，直接借 Actions 自带的缓存空间、不用自备仓库，只适合它一家的环境，这里不展开，CI 流水线的完整组织见 &lt;a href=&quot;/posts/docker-cicd-pipeline/&quot;&gt;Docker CI/CD 流水线篇&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;依赖层分离：源码改动别连累依赖重装&lt;/h2&gt;
&lt;p&gt;这是性价比最高、却最常被写错的一招。反面写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 反面教材：先拷全部源码
COPY . .
RUN pip install -r requirements.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;COPY . .&lt;/code&gt; 之后随便改哪个文件，这一层的摘要就变了，紧跟其后的 &lt;code&gt;pip install&lt;/code&gt; 层缓存必然失效——明明依赖一个字没动，也要全部重装。&lt;/p&gt;
&lt;p&gt;正确顺序是先只拷依赖清单、装依赖，最后才拷源码：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# syntax=docker/dockerfile:1
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt
COPY . .
CMD [&quot;python&quot;, &quot;app.py&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这样日常改业务代码，只重跑最后那个 &lt;code&gt;COPY&lt;/code&gt; 和之后的步骤，装依赖的层稳稳命中缓存。再叠上前面讲的缓存挂载，就算依赖清单真的变了，也只是补下载新增包，双保险。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;写法&lt;/th&gt;
&lt;th&gt;改业务代码后&lt;/th&gt;
&lt;th&gt;改依赖清单后&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;先 &lt;code&gt;COPY . .&lt;/code&gt; 再装依赖&lt;/td&gt;
&lt;td&gt;依赖全部重装&lt;/td&gt;
&lt;td&gt;依赖全部重装&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;先拷清单装依赖、后拷源码&lt;/td&gt;
&lt;td&gt;只重拷源码层&lt;/td&gt;
&lt;td&gt;仅补下载新增包（有缓存挂载时）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;Dockerfile 的整体组织规范（基础镜像选择、多阶段瘦身等）见 &lt;a href=&quot;/posts/dockerfile-guide/&quot;&gt;Dockerfile 编写指南&lt;/a&gt;，本篇只聚焦顺序与缓存这一件事。&lt;/p&gt;
&lt;h2&gt;并行构建：互不依赖的阶段一起跑&lt;/h2&gt;
&lt;p&gt;多阶段构建还有一个隐藏福利：&lt;strong&gt;互不依赖的 stage，BuildKit 会自动并行构建&lt;/strong&gt;。比如一个阶段编译前端静态资源、一个阶段编译后端二进制、最后一个阶段只是把两边的产物拷进来组装——前两个阶段没有依赖关系，BuildKit 会同时开跑，吃满多核。&lt;/p&gt;
&lt;p&gt;想吃到这个红利，Dockerfile 得把阶段拆干净：每个 stage 只依赖自己真正需要的输入，别把所有事情挤在一个 stage 里串行做完。验证是否并行，看构建输出里多个 stage 是否同时在推进即可。&lt;/p&gt;
&lt;p&gt;如果一次构建要出多个镜像（比如同一个仓库的多个服务），用 &lt;code&gt;docker buildx bake&lt;/code&gt; 描述一组目标，它会统一调度、并行构建，比写一串 &lt;code&gt;docker build&lt;/code&gt; 顺序执行快得多。bake 的完整用法和 CI 集成在 CI/CD 流水线篇里展开，本篇只提醒有这么个工具。&lt;/p&gt;
&lt;p&gt;还有一个最容易被忽视的慢源：构建上下文。&lt;code&gt;docker build&lt;/code&gt; 开始之前，要先把构建目录打包发给构建器，目录里要是躺着 &lt;code&gt;node_modules&lt;/code&gt;、&lt;code&gt;.git&lt;/code&gt;、几个 GB 的日志和数据文件，光传输就先慢一步。&lt;code&gt;.dockerignore&lt;/code&gt; 写严一点：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;.git
node_modules
dist
*.log
data/
.env
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;上下文瘦身是所有加速手段里成本最低的一个，改几行文本，立竿见影。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;排障小节&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;缓存挂载没生效，每次还是全量下载。&lt;/strong&gt; 按顺序查三件事：一是 Dockerfile 第一行有没有 &lt;code&gt;# syntax=docker/dockerfile:1&lt;/code&gt;，没有这行声明或版本太老，&lt;code&gt;--mount&lt;/code&gt; 直接被忽略或报错；二是 &lt;code&gt;target&lt;/code&gt; 路径写没写对，缓存挂的是工具真实使用的缓存目录，pip 是 &lt;code&gt;/root/.cache/pip&lt;/code&gt;、npm 是 &lt;code&gt;/root/.npm&lt;/code&gt;，写错一位就挂了个空目录；三是构建是不是走了 BuildKit，老版本 Docker 或手动关掉 BuildKit 时 &lt;code&gt;--mount&lt;/code&gt; 不被支持。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;远程缓存推不上去。&lt;/strong&gt; 先确认构建机登录过目标仓库（&lt;code&gt;docker login&lt;/code&gt;），且这个账号对缓存要推的那个仓库路径有写权限——缓存 ref 本质上也是个镜像 tag，没权限就推不动；其次确认用的是 &lt;code&gt;docker buildx build&lt;/code&gt; 且加了 &lt;code&gt;--push&lt;/code&gt; 或 &lt;code&gt;--output&lt;/code&gt;，普通 &lt;code&gt;docker build&lt;/code&gt; 的本地构建不会把 &lt;code&gt;--cache-to&lt;/code&gt; 的内容真正送出去，本地驱动对远程缓存的支持也不完整，CI 里建议显式建一个 &lt;code&gt;docker-container&lt;/code&gt; 驱动的 builder。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;缓存太旧，装到了旧版本的包。&lt;/strong&gt; 缓存挂载复用的是下载缓存，包管理器的索引（比如 apt 的包列表、pip 的解析结果）过期时，可能解析出旧版本。apt 场景保证每次都执行 &lt;code&gt;apt-get update&lt;/code&gt; 且 &lt;code&gt;/var/lib/apt/lists&lt;/code&gt; 也在挂载范围内；实在被缓存坑到怀疑人生时，&lt;code&gt;docker buildx prune&lt;/code&gt; 清掉 BuildKit 缓存、或者构建时临时不挂缓存跑一次冷构建验证，别在旧缓存上反复猜。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;注意 &lt;code&gt;docker buildx prune&lt;/code&gt; 清的是构建缓存，别和删镜像、删数据卷的命令混用，生产机器上先看清楚清的是什么再回车。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;构建还是慢，但三段都查不出问题。&lt;/strong&gt; 回到开头的方法重新量化：&lt;code&gt;--no-cache&lt;/code&gt; 冷构建和热构建各跑一遍计时。如果冷热时间差不多，说明缓存根本没命中，逐层看构建输出里哪一层最先出现 CACHED 消失的位置，那一层就是断点，通常是某个 &lt;code&gt;COPY&lt;/code&gt; 把不该变的文件带了进来，或者一条 &lt;code&gt;RUN&lt;/code&gt; 前面放了每次都变的构建参数。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;构建加速没有银弹，就是把三段耗时逐个摁下去：&lt;code&gt;.dockerignore&lt;/code&gt; 管住上下文，依赖层分离加缓存挂载管住装依赖，多阶段并行和远程缓存管住编译与 CI 复用。secret 挂载顺手把构建期密钥的安全问题一并解决了。改完之后用冷、热两次构建的计时对比验收，数字不会骗人。&lt;/p&gt;
</content:encoded></item><item><title>Docker Compose 资源编排与启动优化：让服务按顺序就绪、按配额运行</title><link>https://www.anexns.cloudns.org/posts/docker-compose-optimization/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-compose-optimization/</guid><description>depends_on 三档条件与 healthcheck 调优解决启动竞速，deploy.resources 在普通 compose up 下同样能限住 CPU 与内存，再加上 profiles 按需启动、--wait 与并行调优，把一份 Compose 文件从能跑调到稳跑。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;&lt;code&gt;docker compose up -d&lt;/code&gt; 一把梭，容器全绿，应用日志里却一片 &lt;code&gt;connection refused&lt;/code&gt;：数据库进程是起来了，但还没开始接受连接，应用先冲了进去；等你手动重启应用，一切正常。另一个常见场面是几个服务挤在一台小内存机器上，平时相安无事，某个服务半夜跑批处理把内存吃满，OOM Killer 随机挑了一个倒霉蛋杀掉，偏偏挑中的是数据库。&lt;/p&gt;
&lt;p&gt;这两个问题都不是镜像的问题，而是&lt;strong&gt;编排&lt;/strong&gt;的问题：启动只管顺序不管就绪，资源只管启动不管配额。这篇就把 Docker Compose 在这两件事上的现行能力一次讲清：&lt;code&gt;depends_on&lt;/code&gt; 的三档条件、healthcheck 怎么调才不误判、&lt;code&gt;deploy.resources&lt;/code&gt; 在普通 &lt;code&gt;compose up&lt;/code&gt;（非 Swarm）下怎么落地，再加上 profiles、&lt;code&gt;--wait&lt;/code&gt;、并行与 YAML 锚点这些日常顺手优化。Compose 文件的字段全集可以先看&lt;a href=&quot;/posts/docker-compose-advanced/&quot;&gt;Docker Compose 进阶用法&lt;/a&gt;，第一次写 Compose 的先看&lt;a href=&quot;/posts/linux-docker-compose/&quot;&gt;Docker Compose 入门&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;先给结论：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;启动竞速靠「healthcheck + service_healthy」解决，资源争抢靠 deploy.resources 的 limits 与 reservations 解决，这两套机制在 Compose v2 的普通 up 模式下全部生效，不需要 Swarm。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;问题一：启动了，不等于就绪了&lt;/h2&gt;
&lt;p&gt;容器「启动」和服务「就绪」是两回事。进程拉起来了，端口可能还没监听，数据文件可能还在恢复，初始化脚本可能还没跑完。&lt;code&gt;depends_on&lt;/code&gt; 默认只保证前者，这正是应用连不上数据库的根源。&lt;/p&gt;
&lt;h3&gt;depends_on 的三档 condition&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;condition&lt;/th&gt;
&lt;th&gt;等什么&lt;/th&gt;
&lt;th&gt;典型场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;service_started&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;依赖的容器进程启动（默认行为）&lt;/td&gt;
&lt;td&gt;无就绪要求的弱依赖&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;service_healthy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;依赖通过它自己的 healthcheck&lt;/td&gt;
&lt;td&gt;应用等数据库能接受连接&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;service_completed_successfully&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;依赖容器跑完并以 0 退出&lt;/td&gt;
&lt;td&gt;等数据库迁移、初始化脚本执行完&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;写法如下，注意 &lt;code&gt;condition&lt;/code&gt; 是长语法，老的短语法（只写服务名列表）等价于 &lt;code&gt;service_started&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:1.0
    depends_on:
      db:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;healthcheck：被依赖方要先定义探针&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;service_healthy&lt;/code&gt; 的前提是被依赖的服务自己配了 &lt;code&gt;healthcheck&lt;/code&gt;，探针周期性地问一句「你真能干活了吗」。四个参数各管一件事：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;调优要点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;test&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;探针命令，&lt;code&gt;CMD&lt;/code&gt; 直接执行或 &lt;code&gt;CMD-SHELL&lt;/code&gt; 走 shell&lt;/td&gt;
&lt;td&gt;优先用服务自带的就绪探针，别用 &lt;code&gt;curl&lt;/code&gt; 硬凑&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;interval&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;两次探测的间隔&lt;/td&gt;
&lt;td&gt;30s 是常用值，太密徒增开销&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;timeout&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;单次探测超时&lt;/td&gt;
&lt;td&gt;给慢磁盘留余量，常用 5–10s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;retries&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;连续失败几次才判 unhealthy&lt;/td&gt;
&lt;td&gt;3 次起步，避免抖动误判&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;start_period&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;启动宽限期，期间失败不计数&lt;/td&gt;
&lt;td&gt;慢启动服务必配，否则刚启动就被判不健康、日志被探测刷屏&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;三大数据库都有现成的就绪探针，直接抄：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: example
    healthcheck:
      test: [&quot;CMD-SHELL&quot;, &quot;pg_isready -U postgres&quot;]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  cache:
    image: redis:7-alpine
    healthcheck:
      test: [&quot;CMD&quot;, &quot;redis-cli&quot;, &quot;ping&quot;]
      interval: 10s
      timeout: 3s
      retries: 5
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;MySQL 把探针换成 &lt;code&gt;mysqladmin ping -h localhost&lt;/code&gt; 即可。&lt;code&gt;start_period&lt;/code&gt; 的值按服务的冷启动实测给：数据库要回放日志、加载缓存的，给到 30–60s 也不夸张，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;宽限给太短，服务会在还没就绪时就被标记 unhealthy，依赖它的一方永远等不到 healthy。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;:::warning
&lt;code&gt;condition: service_healthy&lt;/code&gt; 和 healthcheck 是一对：只写 condition 不配 healthcheck，依赖方会一直卡在等待状态，既不报错也不启动。排障时先去被依赖方确认探针存在且能通过，再怀疑其他环节。
:::&lt;/p&gt;
&lt;h3&gt;--wait：让 up 等到全部就绪再返回&lt;/h3&gt;
&lt;p&gt;脚本和 CI 里还有一个顺手选项：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d --wait
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--wait&lt;/code&gt; 让命令阻塞到所有服务 running 且（配了 healthcheck 的）healthy 才返回，退出码直接反映成败，省掉脚本里自己写轮询 &lt;code&gt;compose ps&lt;/code&gt; 的循环。部署脚本最后一行接健康检查或冒烟测试时，用它最稳。&lt;/p&gt;
&lt;h2&gt;问题二：资源没人管，全靠抢&lt;/h2&gt;
&lt;p&gt;单个容器的资源参数（&lt;code&gt;--cpus&lt;/code&gt;、&lt;code&gt;--memory&lt;/code&gt; 背后的 cgroup 原理）是&lt;a href=&quot;/posts/docker-resource-tuning/&quot;&gt;容器资源与性能调优&lt;/a&gt;那篇的主题；本篇只讲在 Compose 文件里怎么把这些配额编排好。用的就是 &lt;code&gt;deploy.resources&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  db:
    image: postgres:16-alpine
    deploy:
      resources:
        limits:
          cpus: &quot;1.50&quot;
          memory: 1G
        reservations:
          cpus: &quot;0.50&quot;
          memory: 512M

  app:
    image: myapp:1.0
    deploy:
      resources:
        limits:
          cpus: &quot;1.00&quot;
          memory: 512M
        reservations:
          memory: 256M
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个字段的分工：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;limits&lt;/strong&gt; 是硬顶。CPU 到顶被限流（throttle），内存到顶触发容器级 OOM Kill——杀的是超额的那一个，而不是全机随机抽一个。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;reservations&lt;/strong&gt; 是保底预留。宿主机内存紧张时，预留量之内的部分优先保住，相当于给关键服务买了份保险。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;很多人对 &lt;code&gt;deploy&lt;/code&gt; 有个过时印象，觉得它是 Swarm 专属、普通 &lt;code&gt;compose up&lt;/code&gt; 会忽略。这个结论已经过期：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Compose v2 现行行为是 &lt;code&gt;deploy.resources&lt;/code&gt; 的 limits 与 reservations 在非 Swarm 的 &lt;code&gt;docker compose up&lt;/code&gt; 下同样生效&amp;lt;/span&amp;gt;，写在 Compose 文件里就是给本机编排用的。注意边界：&lt;code&gt;deploy&lt;/code&gt; 下的 &lt;code&gt;replicas&lt;/code&gt;、&lt;code&gt;placement&lt;/code&gt; 等 Swarm 调度字段在普通模式下仍然不生效，别把整段 Swarm 配置照搬过来指望全盘生效。&lt;/p&gt;
&lt;p&gt;配额给多少不是拍脑袋，流程是先观察再回填：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose ps        # 看每个服务的状态与健康列
docker stats             # 看 CPU / 内存的实际占用与上限
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;让服务以真实负载跑一两天，用 &lt;code&gt;docker stats&lt;/code&gt; 记下峰值，limits 给峰值留两三成余量，reservations 按常态占用给。数据库这类稳态服务可以给得贴身；跑批处理、编译型任务波动大，余量要留足，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;limits 卡着峰值给，第一次内存峰值就会把容器 OOM 掉，然后在日志里留下一串莫名其妙的 Killed。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;profiles：偶尔才用的服务别常驻&lt;/h2&gt;
&lt;p&gt;调试工具、一次性管理台、数据修复脚本这类服务，写进 Compose 文件就意味着每次 &lt;code&gt;up&lt;/code&gt; 都跟着启动，白占资源。&lt;code&gt;profiles&lt;/code&gt; 就是为此准备的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  adminer:
    image: adminer:latest
    ports:
      - &quot;8080:8080&quot;
    profiles:
      - debug
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;带了 profile 的服务默认不启动，需要时显式唤起：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose --profile debug up -d   # 连同 debug 组的服务一起拉起
docker compose up -d adminer           # 点名启动单个也可以，会自动启用它所在的 profile
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;也可以用 &lt;code&gt;COMPOSE_PROFILES&lt;/code&gt; 环境变量一次启用多个 profile，适合写进不同环境的 &lt;code&gt;.env&lt;/code&gt; 里区分。&lt;/p&gt;
&lt;h2&gt;并行：拉取与构建别串行排队&lt;/h2&gt;
&lt;p&gt;服务一多，&lt;code&gt;up&lt;/code&gt; 和 &lt;code&gt;build&lt;/code&gt; 的串行等待开始明显。两个旋钮：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;COMPOSE_PARALLEL_LIMIT&lt;/code&gt; 环境变量控制 Compose 并行操作的上限（拉取、构建等并发度），机器和网络带得动可以适当调高，默认值偏保守：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;COMPOSE_PARALLEL_LIMIT=10 docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;构建方面，&lt;code&gt;docker compose build --parallel&lt;/code&gt; 这个参数在 Compose v2 里基本是历史遗留：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;v2 的 build 默认就已经并行构建多个服务&amp;lt;/span&amp;gt;，加不加这个参数行为一致，写脚本时不用再特意带上它。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;YAML 锚点：重复配置只写一遍&lt;/h2&gt;
&lt;p&gt;多个服务共享同一套环境变量、日志配置、重启策略时，用 YAML 锚点加 &lt;code&gt;x-&lt;/code&gt; 扩展字段收拢重复，不必逐个服务复制粘贴：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;x-common: &amp;amp;common
  restart: unless-stopped
  logging:
    driver: json-file
    options:
      max-size: &quot;20m&quot;
      max-file: &quot;3&quot;

services:
  app:
    &amp;lt;&amp;lt;: *common
    image: myapp:1.0
  worker:
    &amp;lt;&amp;lt;: *common
    image: myapp:1.0
    command: [&quot;./worker&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;&amp;amp;common&lt;/code&gt; 定义锚点，&lt;code&gt;&amp;lt;&amp;lt;: *common&lt;/code&gt; 把它合并进每个服务，服务内再写同名字段即可覆盖。改一处、全员生效，这是它唯一的用途，点到为止。&lt;/p&gt;
&lt;h2&gt;组合示例：一份文件把几件事一起办了&lt;/h2&gt;
&lt;p&gt;把前面的零件拼起来，一份带迁移、带配额、带按需工具的 Compose 文件长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: [&quot;CMD-SHELL&quot;, &quot;pg_isready -U postgres&quot;]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    deploy:
      resources:
        limits:
          cpus: &quot;1.50&quot;
          memory: 1G
        reservations:
          memory: 512M

  migrate:
    image: myapp:1.0
    command: [&quot;./migrate&quot;]
    depends_on:
      db:
        condition: service_healthy

  app:
    image: myapp:1.0
    depends_on:
      db:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully
    deploy:
      resources:
        limits:
          cpus: &quot;1.00&quot;
          memory: 512M

  adminer:
    image: adminer:latest
    ports:
      - &quot;8080:8080&quot;
    profiles:
      - debug

volumes:
  db-data:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动顺序被这份文件完全钉死：&lt;code&gt;db&lt;/code&gt; 先起来并通过 &lt;code&gt;pg_isready&lt;/code&gt; 探针，&lt;code&gt;migrate&lt;/code&gt; 才开始跑迁移，迁移以 0 退出后 &lt;code&gt;app&lt;/code&gt; 才启动；&lt;code&gt;adminer&lt;/code&gt; 躲在 &lt;code&gt;debug&lt;/code&gt; profile 里不占常驻资源；数据库和应用各自有内存硬顶，谁也别想把对方挤死。部署脚本里执行 &lt;code&gt;docker compose up -d --wait&lt;/code&gt;，返回成功就意味着这条链真的全部就绪，而不是「容器都创建完了」。&lt;/p&gt;
&lt;p&gt;还有一个 healthcheck 的细节参数值得知道：&lt;code&gt;start_interval&lt;/code&gt;（Compose 规范较新版本加入）控制宽限期内的探测频率，可以比常规 &lt;code&gt;interval&lt;/code&gt; 更密，让服务一旦就绪就尽快被发现，不必干等下一个常规周期。老版本 Compose 不认识这个字段会直接报错升级提示，升级到当前 v2 再用。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. 写了 &lt;code&gt;service_healthy&lt;/code&gt;，依赖方永远不启动。&lt;/strong&gt;
十有八九是被依赖方没配 healthcheck，或者配了但探针一直失败。先单独看被依赖方的健康状态：&lt;code&gt;docker compose ps&lt;/code&gt; 里 STATUS 列会显示 &lt;code&gt;(unhealthy)&lt;/code&gt; 或一直 &lt;code&gt;(health: starting)&lt;/code&gt;；再把探针命令手动进容器执行一遍，看它到底通不通。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. healthcheck 探针命令在镜像里不存在。&lt;/strong&gt;
精简镜像（alpine、distroless）经常没有 &lt;code&gt;curl&lt;/code&gt;、&lt;code&gt;wget&lt;/code&gt;，探针每次执行都报可执行文件不存在，服务永远 unhealthy。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;探针只能用镜像里真实存在的命令&amp;lt;/span&amp;gt;：数据库优先用自带探针（&lt;code&gt;pg_isready&lt;/code&gt;、&lt;code&gt;mysqladmin&lt;/code&gt;、&lt;code&gt;redis-cli&lt;/code&gt;），没有合适工具时用 &lt;code&gt;CMD-SHELL&lt;/code&gt; 配合 shell 内置能力（如 bash 的 &lt;code&gt;/dev/tcp&lt;/code&gt; 探端口），实在不行就给镜像补一个探针工具再构建。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. limits 写在 &lt;code&gt;deploy&lt;/code&gt; 下没生效，是版本问题还是写法问题？&lt;/strong&gt;
先分清是哪种没生效：&lt;code&gt;docker inspect &amp;lt;容器名&amp;gt;&lt;/code&gt; 看 &lt;code&gt;HostConfig&lt;/code&gt; 里的 &lt;code&gt;Memory&lt;/code&gt;、&lt;code&gt;NanoCpus&lt;/code&gt; 是否落上了数值。落上了但感觉没限制，多半是看错了对象（limits 是硬顶，平时没跑满当然看不出来）；没落上，先确认用的是 Compose v2（&lt;code&gt;docker compose version&lt;/code&gt;），v1 时代的二进制对 &lt;code&gt;deploy&lt;/code&gt; 的支持口径不同，老教程里「up 会忽略 deploy」的说法就是那时候留下的。写法上注意 &lt;code&gt;cpus&lt;/code&gt; 要带引号写成字符串、&lt;code&gt;memory&lt;/code&gt; 带单位（&lt;code&gt;512M&lt;/code&gt;、&lt;code&gt;1G&lt;/code&gt;），写成纯数字容易被解析出意料之外的结果。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. &lt;code&gt;service_completed_successfully&lt;/code&gt; 的迁移容器每次都跟着重启。&lt;/strong&gt;
一次性任务容器在 &lt;code&gt;compose up&lt;/code&gt; 时会被重新拉起执行，这是它的设计行为；如果迁移已经完成、不想每次都跑，给它加 profile 隔离，或者在部署脚本里单独 &lt;code&gt;docker compose run --rm migrate&lt;/code&gt; 执行，不要把它放进常驻依赖链。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Compose 编排优化就抓两条主线：启动侧用 healthcheck 定义「就绪」、用 &lt;code&gt;depends_on&lt;/code&gt; 的三档 condition 声明「等到什么程度」，慢启动服务记得给足 &lt;code&gt;start_period&lt;/code&gt;；资源侧用 &lt;code&gt;deploy.resources&lt;/code&gt; 给每个服务划好硬顶和保底，先 &lt;code&gt;docker stats&lt;/code&gt; 观察、再回填数字。再顺手用 profiles 隔离偶尔才用的服务、用 &lt;code&gt;--wait&lt;/code&gt; 收稳部署脚本、用锚点收拢重复配置，一份 Compose 文件就从「能跑」变成了「稳跑」。&lt;/p&gt;
</content:encoded></item><item><title>daemon.json 调优：Docker 装完第一件事，先把这个总开关配对</title><link>https://www.anexns.cloudns.org/posts/docker-daemon-tuning/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-daemon-tuning/</guid><description>Docker 的日志上限、IPv6、live-restore、拉取并发、镜像加速、数据目录和默认网段，全部由 /etc/docker/daemon.json 一个文件说了算——给一份可直接抄的定版配置，再逐项讲清每个开关的取舍与迁移实战。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;Docker 装完能跑，很多人就再也没碰过它的全局配置。但有几个坑几乎人人会踩：容器日志无上限，跑几个月把系统盘吃满；dockerd 升级重启，所有容器跟着全停；默认网段 172.17 和公司内网、VPN 撞车，容器莫名其妙连不通。这些问题其实都归同一个文件管——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;/etc/docker/daemon.json 是整个 Docker 守护进程的总开关&amp;lt;/span&amp;gt;，日志、网络、存储、拉取行为全在这里定规矩。这篇给一份可以直接抄走的定版配置，再逐项拆开讲它为什么这么写，最后是数据目录迁移和改完起不来时的自救办法。&lt;/p&gt;
&lt;h2&gt;动手之前：先备份，再验语法&lt;/h2&gt;
&lt;p&gt;daemon.json 的位置固定在 &lt;code&gt;/etc/docker/daemon.json&lt;/code&gt;（部分发行版可能是 &lt;code&gt;/etc/docker/daemon.json&lt;/code&gt; 之外的路径，但绝大多数就是这里）。这个文件不存在时 Docker 用内置默认跑，文件一旦存在，里面的每一项都会覆盖默认值。&lt;/p&gt;
&lt;p&gt;改它之前先做两件事。第一，备份：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak 2&amp;gt;/dev/null || echo &quot;原本没有这个文件，直接新建即可&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第二，写完先验语法再重启。Docker 23 及以上版本可以让 dockerd 自己校验配置文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo dockerd --validate --config-file=/etc/docker/daemon.json
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;校验通过会输出 &lt;code&gt;configuration OK&lt;/code&gt;。别小看这一步：&lt;/p&gt;
&lt;p&gt;:::warning
daemon.json 是严格 JSON，多一个逗号、少一个引号，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;dockerd 会直接拒绝启动&amp;lt;/span&amp;gt;，机器上所有容器跟着一起停摆。任何时候改完这个文件，都必须先跑一遍 &lt;code&gt;--validate&lt;/code&gt; 再重启服务；校验报错就对照行号改，改不动就先把备份覆盖回去把服务拉起来，再慢慢查。
:::&lt;/p&gt;
&lt;h2&gt;定版配置：直接抄这一份&lt;/h2&gt;
&lt;p&gt;下面是本站长期在用的组合，日志封顶、关掉 userland 代理、开 IPv6 并锁定网段，再加上 live-restore 和拉取并发。逐项含义在下一节拆开讲，这里先给完整文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;log-driver&quot;: &quot;json-file&quot;,
  &quot;log-opts&quot;: {
    &quot;max-size&quot;: &quot;20m&quot;,
    &quot;max-file&quot;: &quot;3&quot;
  },
  &quot;userland-proxy&quot;: false,
  &quot;ipv6&quot;: true,
  &quot;fixed-cidr-v6&quot;: &quot;fdb::/64&quot;,
  &quot;live-restore&quot;: true,
  &quot;max-concurrent-downloads&quot;: 5,
  &quot;max-concurrent-uploads&quot;: 5,
  &quot;registry-mirrors&quot;: [],
  &quot;features&quot;: {
    &quot;buildkit&quot;: true
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;registry-mirrors&lt;/code&gt; 这里留了空数组占位，实际使用时填你自己的加速地址（原因见下文「镜像加速」一节）。写入后别急着重启，先跑上面的 &lt;code&gt;--validate&lt;/code&gt;，通过了再执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl restart docker
sudo docker info
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;逐项拆解：每个开关在管什么&lt;/h2&gt;
&lt;h3&gt;日志：json-file + 20m × 3，先把磁盘保住&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;log-driver&lt;/code&gt; 选 &lt;code&gt;json-file&lt;/code&gt; 是 Docker 的默认驱动，胜在简单、&lt;code&gt;docker logs&lt;/code&gt; 直接可用。真正的关键是后面两个 &lt;code&gt;log-opts&lt;/code&gt;：&lt;code&gt;max-size: 20m&lt;/code&gt; 表示单个日志文件长到 20 MB 就滚动切分，&lt;code&gt;max-file: 3&lt;/code&gt; 表示最多保留 3 个文件。两者相乘，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;单个容器的日志占用被硬性封顶在约 60 MB&amp;lt;/span&amp;gt;，再话痨的容器也吃不满磁盘。不设这两个参数时，json-file 是无限增长的——这是生产环境最常见的磁盘爆满原因，没有之一。日志驱动和日志查看的更多玩法，可以看日志管理那篇：&lt;a href=&quot;/posts/docker-logging/&quot;&gt;Docker 日志管理&lt;/a&gt;。&lt;/p&gt;
&lt;h3&gt;userland-proxy：关掉它，端口转发走 iptables&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;userland-proxy: false&lt;/code&gt; 关掉的是 Docker 自带的用户态端口代理。默认开启时，容器端口映射会同时走 iptables 规则和一个用户态进程转发；关掉之后转发完全由 iptables 承担，少一层中转，性能略好，也少一个出故障的环节。绝大多数场景关掉没有副作用；只有极少数 iptables 不可用的环境才需要它兜底。iptables 相关的其他配置不要在这个文件里乱动——Docker 会自己管理它的链，手改容易和它打架。&lt;/p&gt;
&lt;h3&gt;IPv6：开开关还不够，要锁定网段&lt;/h3&gt;
&lt;p&gt;光写 &lt;code&gt;ipv6: true&lt;/code&gt; 只是允许 Docker 用 IPv6，每个网络实际分到什么前缀还不确定。再配上 &lt;code&gt;fixed-cidr-v6: &quot;fdb::/64&quot;&lt;/code&gt;，把默认 bridge 的 IPv6 网段固定成 &lt;code&gt;fdb::/64&lt;/code&gt; 这段 ULA 地址，行为可预期、好排障。这套组合本站所有机器统一，省得每台分到的段都不一样。IPv6 在容器网络里的完整玩法见 &lt;a href=&quot;/posts/docker-network/&quot;&gt;Docker 网络详解&lt;/a&gt;。&lt;/p&gt;
&lt;h3&gt;live-restore：dockerd 重启，容器不陪葬&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;live-restore: true&lt;/code&gt; 是最被低估的一项。没有它时，dockerd 每次升级或重启，全部容器都会被停掉再拉起；开启后守护进程重启期间容器保持运行，进程回来再重新接管。对跑着正经服务的机器，这意味着升级 Docker 版本不再等于全站闪断。注意一个边界：live-restore 与 Swarm 模式不兼容，开了 Swarm 的节点不要启用它（排障一节还会提到）。&lt;/p&gt;
&lt;h3&gt;拉取并发：按带宽调，别照抄数字&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;max-concurrent-downloads&lt;/code&gt; 和 &lt;code&gt;max-concurrent-uploads&lt;/code&gt; 控制同时拉取、推送的镜像层数量，默认都是 3。示例里写 5 是给带宽充裕的机器：层与层并行下载，总时间更短。反过来，带宽小或者和别的业务抢出口时，把并发调低到 1–2 反而更稳，避免把链路打满导致每个层都超时重试。&lt;/p&gt;
&lt;h3&gt;镜像加速：填你可用的地址，不要迷信公共源&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;registry-mirrors&lt;/code&gt; 是给 Docker Hub 拉取配置的加速镜像列表，&lt;strong&gt;只影响 pull，不影响 push&lt;/strong&gt;。要提醒的是：&lt;/p&gt;
&lt;p&gt;:::warning
网上流传的公共加速源地址可用性随时间变化非常大，今天能用的下个月可能就停了，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把任何一个公共源地址当成长期方案写死在配置里&amp;lt;/span&amp;gt;。临时救急可以填一个你当下验证可用的；长久之计是在内网自建一个 registry 做 pull-through cache，地址稳定、速度可控。自建私有仓库的做法见 &lt;a href=&quot;/posts/docker-private-registry/&quot;&gt;Docker 私有仓库搭建&lt;/a&gt;。
:::&lt;/p&gt;
&lt;h3&gt;features.buildkit：新版默认已开，老版本显式打开&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;features: { &quot;buildkit&quot;: true }&lt;/code&gt; 是显式启用 BuildKit 构建引擎。较新的 Docker 版本已经默认开启，这项写上也无妨；还在跑老版本的机器靠它打开 BuildKit，才能用上缓存挂载、并行构建那些新特性。&lt;/p&gt;
&lt;p&gt;一张表把定版配置收一下：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;配置项&lt;/th&gt;
&lt;th&gt;定版值&lt;/th&gt;
&lt;th&gt;解决什么问题&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;log-driver / log-opts&lt;/td&gt;
&lt;td&gt;json-file + 20m × 3&lt;/td&gt;
&lt;td&gt;日志无限增长吃满磁盘&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;userland-proxy&lt;/td&gt;
&lt;td&gt;false&lt;/td&gt;
&lt;td&gt;端口转发少一层用户态中转&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ipv6 / fixed-cidr-v6&lt;/td&gt;
&lt;td&gt;true / fdb::/64&lt;/td&gt;
&lt;td&gt;IPv6 网段不确定、不可预期&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;live-restore&lt;/td&gt;
&lt;td&gt;true&lt;/td&gt;
&lt;td&gt;dockerd 重启导致容器全停&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;max-concurrent-downloads / uploads&lt;/td&gt;
&lt;td&gt;按带宽取 1–10&lt;/td&gt;
&lt;td&gt;拉取慢或抢满出口带宽&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;registry-mirrors&lt;/td&gt;
&lt;td&gt;填自有/当下可用地址&lt;/td&gt;
&lt;td&gt;Docker Hub 拉取慢&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;features.buildkit&lt;/td&gt;
&lt;td&gt;true&lt;/td&gt;
&lt;td&gt;老版本用不上 BuildKit&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;data-root 迁移：系统盘不够了，把数据搬走&lt;/h2&gt;
&lt;p&gt;镜像、容器、卷默认都存在 &lt;code&gt;/var/lib/docker&lt;/code&gt;，这个目录就是 Docker 的 &lt;code&gt;data-root&lt;/code&gt;。系统盘小、数据涨得快时，需要把它迁到大盘。迁移必须在 Docker 停机状态下做，步骤如下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl stop docker
sudo rsync -aP /var/lib/docker/ /data/docker/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;rsync -aP&lt;/code&gt; 保留全部属性并显示进度。然后在 daemon.json 里加上 &lt;code&gt;data-root&lt;/code&gt; 指向新位置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;data-root&quot;: &quot;/data/docker&quot;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;（实际写入时是把这一项并入你现有的完整配置，不要只留这一项把其他配置冲掉。）启动并确认：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl start docker
sudo docker info | grep &quot;Docker Root Dir&quot;
docker ps -a
docker images
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;docker info&lt;/code&gt; 输出的 &lt;code&gt;Docker Root Dir&lt;/code&gt; 变成 &lt;code&gt;/data/docker&lt;/code&gt;、原有容器和镜像都在、随便挑一个容器能正常启动，迁移才算成功。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;确认无误之前绝对不要删旧目录&amp;lt;/span&amp;gt;；观察几天没问题，再删 &lt;code&gt;/var/lib/docker&lt;/code&gt; 释放空间。万一新位置出问题，把 daemon.json 里的 &lt;code&gt;data-root&lt;/code&gt; 删掉、重启 Docker 就能回到旧数据，等于留了后路。&lt;/p&gt;
&lt;h2&gt;default-address-pools：默认网段和内网撞车时&lt;/h2&gt;
&lt;p&gt;Docker 每建一个自定义网络，就从默认地址池里切一段子网，默认从 172.17 开始往后分。如果你的内网、VPN 或者云厂商 VPC 恰好也用了 172.x 的某些段，就会撞车，表现是容器访问内网地址时路由走错、莫名其妙不通。&lt;/p&gt;
&lt;p&gt;解法是在 daemon.json 里用 &lt;code&gt;default-address-pools&lt;/code&gt; 换一段干净的池子：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;default-address-pools&quot;: [
    {
      &quot;base&quot;: &quot;172.30.0.0/16&quot;,
      &quot;size&quot;: 24
    }
  ]
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;意思是：所有新建网络都从 &lt;code&gt;172.30.0.0/16&lt;/code&gt; 这个大段里切，每段切 &lt;code&gt;/24&lt;/code&gt; 大小。选 base 时避开你内网和 VPN 在用的段即可。注意它只对&lt;strong&gt;新建&lt;/strong&gt;的网络生效，已有网络的网段不会变，老项目要生效得重建网络——这点在排障里也常见。&lt;/p&gt;
&lt;h2&gt;重启与验证清单&lt;/h2&gt;
&lt;p&gt;改完 daemon.json 的标准收尾动作是重启服务加逐项核对：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl restart docker
sudo docker info
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;systemctl restart docker&lt;/code&gt; 会重启守护进程：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;没开 live-restore 的机器上，所有容器会随之全部重启一遍&amp;lt;/span&amp;gt;。挑低峰期操作，别在业务正忙的时候改这个文件。
:::&lt;/p&gt;
&lt;p&gt;&lt;code&gt;docker info&lt;/code&gt; 的输出里逐项对：&lt;code&gt;Logging Driver&lt;/code&gt; 是不是 json-file、&lt;code&gt;Live Restore Enabled&lt;/code&gt; 是不是 true、&lt;code&gt;Docker Root Dir&lt;/code&gt; 是不是迁移后的路径、输出里的 IPv6 和 Registry Mirrors 是否符合预期。对不上的项，基本就是配置没被读到，回排障一节排查。整理成清单就是下面这张表，每次改完照着打勾：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;核对项&lt;/th&gt;
&lt;th&gt;在哪里看&lt;/th&gt;
&lt;th&gt;期望结果&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;配置语法&lt;/td&gt;
&lt;td&gt;&lt;code&gt;dockerd --validate&lt;/code&gt; 输出&lt;/td&gt;
&lt;td&gt;configuration OK&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;日志驱动&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker info&lt;/code&gt; 的 Logging Driver&lt;/td&gt;
&lt;td&gt;json-file&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;日志上限&lt;/td&gt;
&lt;td&gt;新建容器的 &lt;code&gt;docker inspect&lt;/code&gt; 里 LogConfig&lt;/td&gt;
&lt;td&gt;max-size 20m、max-file 3&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;live-restore&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker info&lt;/code&gt; 的 Live Restore Enabled&lt;/td&gt;
&lt;td&gt;true&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据目录&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker info&lt;/code&gt; 的 Docker Root Dir&lt;/td&gt;
&lt;td&gt;迁移后的新路径&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;镜像加速&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker info&lt;/code&gt; 末尾 Registry Mirrors&lt;/td&gt;
&lt;td&gt;与配置填写一致&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;容器存活&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker ps&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;原有容器都在且状态正常&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;补充一句生效方式：daemon.json 里只有少数几项（比如镜像加速列表、debug 开关）支持给 dockerd 发 SIGHUP 信号热重载，其余绝大多数改动都必须完整重启守护进程才生效。分不清哪项支持热重载时，不要试，直接按备份 → 校验 → 重启 → 核对的完整流程走，最稳妥。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. 改完 daemon.json，Docker 直接起不来。&lt;/strong&gt; 十有八九是 JSON 语法错误，&lt;code&gt;systemctl status docker&lt;/code&gt; 和 &lt;code&gt;journalctl -u docker -n 50&lt;/code&gt; 里能看到具体的解析报错行。先跑 &lt;code&gt;dockerd --validate --config-file=/etc/docker/daemon.json&lt;/code&gt; 定位；修不好就用备份覆盖回去：&lt;code&gt;sudo cp /etc/docker/daemon.json.bak /etc/docker/daemon.json&lt;/code&gt;，先把服务恢复，再慢慢改。更多守护进程起不来的排查思路见 &lt;a href=&quot;/posts/docker-deep-troubleshooting/&quot;&gt;Docker 深度排障&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 配置明明改了，docker info 里却没生效。&lt;/strong&gt; 先确认改的是不是 Docker 实际读的那个文件——&lt;code&gt;dockerd --validate&lt;/code&gt; 时指定的路径要和服务实际加载的一致；再查启动参数是否覆盖了文件：有些安装方式在 systemd unit 或启动脚本里给 dockerd 带了命令行参数，&lt;strong&gt;命令行参数的优先级高于 daemon.json&lt;/strong&gt;，同名项以参数为准。改 unit 的要 &lt;code&gt;systemctl daemon-reload&lt;/code&gt; 后再重启。另外，某些项（比如地址池）只影响新建对象，老对象不变，别误判成没生效。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 开了 live-restore，Docker 却报冲突或 Swarm 行为异常。&lt;/strong&gt; live-restore 与 Swarm 模式不兼容：节点一旦加入 Swarm，live-restore 就不该开，dockerd 也可能直接给出警告甚至拒绝。单机跑普通容器才用 live-restore；要组 Swarm 集群，就把这一项去掉。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 填了 registry-mirrors 还是拉不动镜像。&lt;/strong&gt; 先确认加速地址本身现在是否可用（公共源失效是常态），再确认配置已生效：&lt;code&gt;docker info&lt;/code&gt; 输出末尾有 &lt;code&gt;Registry Mirrors&lt;/code&gt; 一栏，列出的就是实际在用的。再就是记住它只管 pull，push 慢和它无关。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;daemon.json 的调优本质上就三件事：给日志这类会失控的东西加上限（20m × 3），给守护进程重启这类必然发生的事留活路（live-restore），把网段和数据目录这类环境相关的东西定死成可预期的值（fixed-cidr-v6、data-root、地址池）。改动流程永远是备份 → 写文件 → &lt;code&gt;--validate&lt;/code&gt; 验语法 → 重启 → &lt;code&gt;docker info&lt;/code&gt; 逐项核对，一步都不要省。这份配置配好之后，Docker 才算从「能跑」变成「可长期托管」。&lt;/p&gt;
</content:encoded></item><item><title>Docker 磁盘空间治理：先看账，再安全清理</title><link>https://www.anexns.cloudns.org/posts/docker-disk-governance/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-disk-governance/</guid><description>用 docker system df 把镜像、容器、数据卷和构建缓存的占用看清楚，只用安全边界明确的清理命令，守住 prune 的两条红线，再配一个只报不删的巡检脚本。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;凌晨三点，监控告警弹出来：服务器磁盘 100%，服务全停。SSH 登上去一看，业务数据没涨多少，MySQL 也好端端的，真正把盘吃干的是 Docker——几个月没管过的镜像、构建缓存和容器日志，悄无声息地堆了几十个 GB。这种场面处理起来最怕两件事：一是慌了手脚乱删，把数据删没；二是删了半天空间没回来，服务还起不来。&lt;/p&gt;
&lt;p&gt;这一篇就讲怎么稳稳地处理：先把账看清楚，再只用边界明确的安全命令清理，最后配一个只报告、不删除的巡检脚本，让磁盘水位永远提前预警，而不是等告警半夜把你叫醒。&lt;/p&gt;
&lt;h2&gt;Docker 的盘，都被谁吃了&lt;/h2&gt;
&lt;p&gt;Docker 的磁盘占用集中在 &lt;code&gt;/var/lib/docker&lt;/code&gt; 目录下，官方口径里分四类，先建立这个全景，后面的命令才看得懂：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;占用类别&lt;/th&gt;
&lt;th&gt;装的是什么&lt;/th&gt;
&lt;th&gt;能不能清&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Images（镜像）&lt;/td&gt;
&lt;td&gt;拉取和构建的镜像层，含悬空镜像&lt;/td&gt;
&lt;td&gt;悬空的可清，在用的别动&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Containers（容器）&lt;/td&gt;
&lt;td&gt;已停止容器的可写层和日志&lt;/td&gt;
&lt;td&gt;确认无用后可清&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Local Volumes（数据卷）&lt;/td&gt;
&lt;td&gt;数据库、上传文件等持久化数据本体&lt;/td&gt;
&lt;td&gt;绝不能当垃圾清&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Build Cache（构建缓存）&lt;/td&gt;
&lt;td&gt;BuildKit 构建时留下的中间层缓存&lt;/td&gt;
&lt;td&gt;可清，只是下次构建慢一点&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;除了这四类，还有一个隐形大户：容器日志。json-file 日志默认没有大小上限，归在容器名下慢慢长，经常是磁盘爆掉的真正元凶，后面单独讲。&lt;/p&gt;
&lt;h2&gt;第一步：先看账，别先动手&lt;/h2&gt;
&lt;p&gt;治理的第一原则是&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;先看账，再动手&amp;lt;/span&amp;gt;。Docker 自带了现成的账本命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker system df
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出四行，对应上面四类占用，每类给出总数、活动数、总大小和可回收量（RECLAIMABLE）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          24        9         18.42GB   11.27GB (61%)
Containers      15        11        2.316GB   845.2MB (36%)
Local Volumes   8         6         9.874GB   1.203GB (12%)
Build Cache     63        0         7.651GB   7.651GB
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;光看汇总还不够下手，加 &lt;code&gt;-v&lt;/code&gt; 看明细，每个镜像、容器、数据卷、缓存条目各占多少、可回收多少，一行行列清楚：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker system df -v
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重点看三处：哪些镜像体积大又没容器在用、哪些数据卷占着空间却没有容器挂载、构建缓存攒了多少。账看到这一步，心里就该有数了：这台机器的盘主要是被谁吃的、能安全回收的大概有多少。&lt;/p&gt;
&lt;p&gt;还有一个命令可以配合着看整机水位：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;df -h /
du -sh /var/lib/docker
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;df -h&lt;/code&gt; 看分区还剩多少，&lt;code&gt;du -sh&lt;/code&gt; 确认 Docker 目录占了多少。两个数对得上，后面的清理才有的放矢。&lt;/p&gt;
&lt;h2&gt;安全清理三件套：边界一条条写明&lt;/h2&gt;
&lt;p&gt;确认完账目，只用下面三条命令清理。它们的共同特点是删除范围明确、只碰&quot;确定没用&quot;的东西。每条都先说清删什么、不删什么，看明白再敲。&lt;/p&gt;
&lt;h3&gt;一、清悬空镜像：docker image prune&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker image prune
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;删什么：悬空镜像（dangling images），即构建新版本后留下的、没有任何标签、也没有容器引用的旧层。&lt;/li&gt;
&lt;li&gt;不删什么：所有带标签的镜像，哪怕当前没有容器在用——你留着回滚的旧版本就在其中，安然无恙。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;执行时会列出要删的镜像并要求确认，删完会打印回收了多少空间。这是最日常、最安全的一条，建议每次构建完新镜像顺手跑一次。&lt;/p&gt;
&lt;h3&gt;二、清构建缓存：docker builder prune&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker builder prune
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;删什么：BuildKit 的构建缓存条目。&lt;/li&gt;
&lt;li&gt;不删什么：镜像本体、容器、数据卷一概不碰。代价仅仅是下次构建少了缓存、慢一些而已。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;缓存别一刀切全清，可以按时间过滤，只清一周前的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker builder prune --filter &quot;until=168h&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;until=168h&lt;/code&gt; 表示只回收 168 小时（7 天）以前的缓存，近期构建还要用的热缓存留着，兼顾空间和构建速度。&lt;/p&gt;
&lt;h3&gt;三、清已停止容器：docker container prune&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker container prune
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;删什么：已经停止的容器本体，包括它的可写层。&lt;/li&gt;
&lt;li&gt;不删什么：运行中的容器不受影响；数据卷默认也不删（除非你额外加 &lt;code&gt;--volumes&lt;/code&gt;，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;千万别加&amp;lt;/span&amp;gt;，理由看下一节红线二）。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;跑之前先列出来确认一遍，别凭记忆：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker ps -a --filter &quot;status=exited&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐个核对：有没有哪个停掉的容器里还留着没导出的临时文件、没看完的日志。确认全部无用，再执行 prune。&lt;/p&gt;
&lt;h2&gt;两条红线：这两条命令不要随手跑&lt;/h2&gt;
&lt;p&gt;清理命令里有两条是&quot;能跑，但后果你未必兜得住&quot;，单独拎出来写死。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;strong&gt;红线一：绝不随手跑 &lt;code&gt;docker system prune -a&lt;/code&gt;。&lt;/strong&gt; 它会删掉所有没有被容器使用的镜像（包括你留着回滚的带标签旧版本）和未使用的网络。下次启动服务要把镜像全部重新拉一遍，网络不通时直接卡死；旧版本镜像没了，出问题想回滚都没得回。本站作者本人就吃过 &lt;code&gt;prune -a&lt;/code&gt; 误删的亏：一条命令图省事，代价是半夜重拉镜像、回滚版本找不回来。清理永远用上面三件套逐条来，不用这条&quot;全家桶&quot;。
:::&lt;/p&gt;
&lt;p&gt;:::warning
&lt;strong&gt;红线二：绝不跑 &lt;code&gt;docker volume prune&lt;/code&gt;。&lt;/strong&gt; 数据卷里装的不是缓存，是数据库的数据文件、用户上传的附件、应用的状态本体。删卷就是真删数据，没有回收站、没有后悔药。卷占用大是&quot;排查&quot;问题，不是&quot;清理&quot;问题：先按后面一节的方法定位是哪个卷、哪个应用在涨，再从应用侧处理（清历史数据、做归档、扩容），而不是从 Docker 侧把卷端掉。卷的备份与恢复方法看 &lt;a href=&quot;/posts/docker-volumes-backup/&quot;&gt;Docker 数据卷与备份&lt;/a&gt;。
:::&lt;/p&gt;
&lt;p&gt;记住这两条，磁盘治理就翻不了大车。剩下的都是耐心活。&lt;/p&gt;
&lt;h2&gt;隐形大户：容器日志吃盘&lt;/h2&gt;
&lt;p&gt;四类账目都正常、盘却还是满，多半是日志。json-file 驱动默认对单个日志文件不设上限，一个话痨容器几个月写出几十 GB 的日志毫不稀奇。&lt;/p&gt;
&lt;p&gt;先定位，按大小把日志文件排出来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;find /var/lib/docker/containers -name &quot;*-json.log&quot; -exec ls -lh {} \; | sort -k 5 -rh | head
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;或者一条命令直接算总账：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;du -sh /var/lib/docker/containers/*/*-json.log 2&amp;gt;/dev/null | sort -rh | head
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;找到大户后注意：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要直接 rm 正在写入的日志文件&amp;lt;/span&amp;gt;，删了空间也不释放（原因见排障第三节）。临时止血可以用截断：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;truncate -s 0 /var/lib/docker/containers/&amp;lt;容器ID&amp;gt;/&amp;lt;容器ID&amp;gt;-json.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;根治是给日志加上限。单容器在 &lt;code&gt;docker run&lt;/code&gt; 时加参数，或在 Compose 里写：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    logging:
      driver: json-file
      options:
        max-size: &quot;20m&quot;
        max-file: &quot;3&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;全局生效则写进 &lt;code&gt;/etc/docker/daemon.json&lt;/code&gt;，对所有新建容器统一限额：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;log-driver&quot;: &quot;json-file&quot;,
  &quot;log-opts&quot;: {
    &quot;max-size&quot;: &quot;20m&quot;,
    &quot;max-file&quot;: &quot;3&quot;
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改完 daemon.json 需要重启 Docker 生效，且只对之后新建的容器起作用，老容器要重建才吃上新配置。日志驱动与轮转的完整讲法在 &lt;a href=&quot;/posts/docker-logging/&quot;&gt;Docker 日志管理&lt;/a&gt; 里，这里只强调一句：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;日志不限额，磁盘爆掉只是时间问题&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h2&gt;数据卷占用排查：定位大户，而不是删它&lt;/h2&gt;
&lt;p&gt;卷涨得快，先定位是哪个卷、涨的是什么：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 账本视角：每个卷的大小和链接数
docker system df -v

# 文件系统视角：每个卷目录实际占用
du -sh /var/lib/docker/volumes/*/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两边对照，锁定大户卷之后，进到卷的挂载点看内容构成（只读查看，别动文件）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker volume inspect &amp;lt;卷名&amp;gt;        # 看 Mountpoint 路径
du -sh &amp;lt;Mountpoint路径&amp;gt;/* | sort -rh | head
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;常见结论无非几种：数据库没做历史数据清理、上传目录只进不出、应用把缓存写进了卷。处理都在应用侧：清过期数据、做冷数据归档、给卷扩容。再次提醒，排查的终点是&quot;知道谁在涨&quot;，不是&quot;把卷删了&quot;。&lt;/p&gt;
&lt;h2&gt;overlay2 目录：只许看，不许手工删&lt;/h2&gt;
&lt;p&gt;在 &lt;code&gt;/var/lib/docker&lt;/code&gt; 里翻找大文件时，很多人会撞见 &lt;code&gt;overlay2&lt;/code&gt; 目录占了大半，于是想进去删几个看起来没用的层目录。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;千万别动&amp;lt;/span&amp;gt;：overlay2 里是镜像层和容器可写层的实际数据，层之间的引用关系记在 Docker 的元数据里。手工删掉任何一个子目录，元数据就和实际文件对不上，轻则镜像损坏拉不起来，重则一片容器跟着报错，最后只能整体重建。&lt;/p&gt;
&lt;p&gt;这个目录只用 &lt;code&gt;du -sh /var/lib/docker/overlay2&lt;/code&gt; 看个总量就够了。它的大小应该和 &lt;code&gt;docker system df&lt;/code&gt; 里镜像加容器的账大致对得上；对不上、或者想回收，都回到 Docker 命令（image prune 等）走正规渠道，让 Docker 自己维护元数据的一致性。&lt;/p&gt;
&lt;h2&gt;巡检脚本：只报告，不删除&lt;/h2&gt;
&lt;p&gt;治理不是一次性大扫除，而是让水位永远可见。写一个巡检脚本，只做两件事：打印 Docker 账本、报告磁盘水位，绝不带任何删除命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
# /usr/local/bin/docker-disk-report.sh
# 只报告不删除：输出 Docker 磁盘账目与分区水位

echo &quot;===== $(date &apos;+%F %T&apos;) Docker 磁盘巡检 =====&quot;
docker system df
echo
df -h / /var/lib/docker 2&amp;gt;/dev/null | grep -v &apos;^Filesystem&apos;
echo

# 根分区用到 85% 以上时在输出里打醒目标记，方便配合告警
USE=$(df / --output=pcent | tail -1 | tr -dc &apos;0-9&apos;)
if [ &quot;$USE&quot; -ge 85 ]; then
  echo &quot;!! 警告：根分区已用 ${USE}%，请人工检查并清理 !!&quot;
fi
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;chmod +x /usr/local/bin/docker-disk-report.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;挂到 cron 每周跑一次，结果留档：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;30 8 * * 1 /usr/local/bin/docker-disk-report.sh &amp;gt;&amp;gt; /var/log/docker-disk-report.log 2&amp;gt;&amp;amp;1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;设计原则就一条：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;巡检只负责喊，清理永远人工确认后手动执行&amp;lt;/span&amp;gt;——脚本里不出现任何 prune 字样。这样既不会重演&quot;自动清理误删数据&quot;，又能保证你在磁盘真正爆掉之前一两周就看到趋势。手动清理时的命令速查可以配合 &lt;a href=&quot;/posts/docker-commands-troubleshooting/&quot;&gt;Docker 常用命令与排障&lt;/a&gt; 一起看。&lt;/p&gt;
&lt;h2&gt;排障小节&lt;/h2&gt;
&lt;h3&gt;df 显示可回收很多，但不敢删，怎么办&lt;/h3&gt;
&lt;p&gt;先分清&quot;可回收&quot;的构成：&lt;code&gt;docker system df -v&lt;/code&gt; 逐项看。构建缓存占大头就放心清 builder prune；悬空镜像占大头就 image prune；如果可回收主要来自&quot;有标签但没容器在用&quot;的镜像，那是 &lt;code&gt;system df&lt;/code&gt; 按&quot;未被容器引用&quot;口径算的，里面混着你的回滚版本，不要动。实在拿不准，先只清缓存和悬空镜像这两类零风险的，通常就能回收大半。&lt;/p&gt;
&lt;h3&gt;删了悬空镜像，磁盘体积没降多少&lt;/h3&gt;
&lt;p&gt;几种可能：一是悬空镜像的层和在用镜像共享底层，共享层不会被删，实际只回收了独占的那部分，看着&quot;删了很多个&quot;但体积不大；二是空间其实被日志或卷占着，镜像本来就不是大户，删完自然没感觉——回到 &lt;code&gt;docker system df -v&lt;/code&gt; 重新对账；三是文件系统层面删除还没落盘，等几秒再 &lt;code&gt;df -h&lt;/code&gt; 复查。&lt;/p&gt;
&lt;h3&gt;容器日志文件删掉了，空间却没释放&lt;/h3&gt;
&lt;p&gt;典型的&quot;进程还占着句柄&quot;：容器进程（经由 Docker 的日志驱动）还打开着那个已删除的日志文件，文件名虽然没了，inode 在进程关闭文件前不会释放，&lt;code&gt;df&lt;/code&gt; 看到的空间就下不来。处理办法：重启对应容器，句柄释放空间立刻回来；或者一开始就用 &lt;code&gt;truncate -s 0&lt;/code&gt; 截断而不是 &lt;code&gt;rm&lt;/code&gt;，截断是把文件内容清零、inode 不变，不存在句柄问题。这也是前面强调不要直接 rm 在写日志的原因。&lt;/p&gt;
&lt;h3&gt;builder prune 之后构建变慢了&lt;/h3&gt;
&lt;p&gt;正常现象：缓存被清掉，下一次构建要从头跑每一步。后续构建会重新攒起缓存。如果构建频繁，用 &lt;code&gt;docker builder prune --filter &quot;until=168h&quot;&lt;/code&gt; 只清旧缓存，别全清；也可以给 BuildKit 配缓存保留策略，把&quot;全清&quot;改成&quot;滚动过期&quot;。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Docker 磁盘治理的顺序永远是：&lt;code&gt;docker system df&lt;/code&gt; 看账 → &lt;code&gt;df -v&lt;/code&gt; 定位大户 → 三件套逐条安全清理 → 日志和卷单独排查 → 巡检脚本长期盯水位。两条红线刻在脑子里：不用 &lt;code&gt;docker system prune -a&lt;/code&gt; 图省事，不碰 &lt;code&gt;docker volume prune&lt;/code&gt; 删数据。盘是慢慢吃满的，治理也靠习惯：每次构建后顺手清悬空镜像，日志从第一天就限额，每周看一眼巡检报告——做到这三点，凌晨三点的磁盘告警就不会再找上门。&lt;/p&gt;
</content:encoded></item><item><title>镜像从 1.2 GB 瘦到 80 MB：多阶段构建、基础镜像选型与 dive 逐层验尸</title><link>https://www.anexns.cloudns.org/posts/docker-image-slimming/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-image-slimming/</guid><description>镜像胖多半不是程序大，而是把编译工具链、缓存和垃圾文件一起打了进去；用多阶段构建只留产物、选对基础镜像、再用 dive 逐层把浪费的空间找出来。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;本地随手 &lt;code&gt;docker build&lt;/code&gt; 出来的镜像 1.2 GB，推到服务器传半天，拉下来又等半天，磁盘上躺十几个版本就是十几 GB。很多人第一反应是「我的程序有这么大吗」——打开一看，程序本体可能只有 30 MB，剩下的全是编译时的工具链、包管理器缓存、文档、测试文件和构建上下文里混进去的垃圾。&lt;/p&gt;
&lt;p&gt;这篇就干一件事：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;把镜像里不属于运行时的东西全部留在构建阶段，只把产物送进最终镜像&amp;lt;/span&amp;gt;。手段是三件套：多阶段构建负责「只带产物走」，基础镜像选型决定「地板有多厚」，dive 负责逐层验尸、找出到底哪一层在浪费空间。&lt;/p&gt;
&lt;p&gt;项目地址：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;https://github.com/wagoodman/dive
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;为什么镜像会胖：先搞懂层机制&lt;/h2&gt;
&lt;p&gt;Docker 镜像是分层的。Dockerfile 里每条会产生文件变化的指令（&lt;code&gt;RUN&lt;/code&gt;、&lt;code&gt;COPY&lt;/code&gt;、&lt;code&gt;ADD&lt;/code&gt;）都会叠一层，镜像总大小约等于所有层加起来。关键规则有两条：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;层是只增不减的&lt;/strong&gt;。你在第 3 层装了 500 MB 的编译工具，第 5 层就算 &lt;code&gt;rm&lt;/code&gt; 删掉，镜像体积也不会变小——删除只是在上一层打了个「遮罩」，下面的层还实打实地占着空间。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;拉取和分发按层算账&lt;/strong&gt;。层越大、层数越多，每次推送、拉取、导出的成本越高。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;所以瘦身的核心思路不是「装完再删」，而是「胖的东西根本不要进最终镜像的层里」。这也是为什么下面所有技巧都围绕两个动作：同层清理，以及多阶段隔离。&lt;/p&gt;
&lt;p&gt;先学会看体积，心里有数再动手：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 看每个镜像的总体积
docker images

# 逐层看某个镜像每层多大、是什么命令产生的
docker history myapp:latest

# 看 Docker 整体磁盘占用（镜像 / 容器 / 卷 / 构建缓存各占多少）
docker system df
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;docker history&lt;/code&gt; 是最快的自查工具：哪一层突然多出几百 MB，基本就是那条指令把不该带的东西带进来了。&lt;/p&gt;
&lt;h2&gt;多阶段构建实战：工具链留在 builder，最终镜像只拿产物&lt;/h2&gt;
&lt;p&gt;多阶段构建（multi-stage build）是瘦身收益最大的一招。同一个 Dockerfile 里写多个 &lt;code&gt;FROM&lt;/code&gt;，每个 &lt;code&gt;FROM&lt;/code&gt; 开启一个 stage；前面的 stage 负责编译，可以放心装齐工具链，最终 stage 用 &lt;code&gt;COPY --from=&lt;/code&gt; 只把编译产物拷过来，工具链一个字节都不进最终镜像。&lt;/p&gt;
&lt;p&gt;以一个 Go 程序为例。Go 编译出的是单个静态二进制，最适合演示「产物思维」：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# ---------- 构建阶段：工具链随便装，反正不进最终镜像 ----------
FROM golang:1.23-bookworm AS builder

WORKDIR /src

# 先只拷依赖清单，利用层缓存：代码改了但依赖没变时，这层不重跑
COPY go.mod go.sum ./
RUN go mod download

COPY . .

# 静态编译，关掉 CGO，产物只有一个二进制
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags=&quot;-s -w&quot; -o /out/myapp ./cmd/myapp

# ---------- 运行阶段：只放产物 ----------
FROM scratch

COPY --from=builder /out/myapp /myapp
# scratch 里连 CA 证书都没有，调 HTTPS 接口要自己带上
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt

ENTRYPOINT [&quot;/myapp&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;golang:1.23-bookworm&lt;/code&gt; 本身接近 800 MB，但它只是 builder；最终镜像是 &lt;code&gt;scratch&lt;/code&gt; 加一个十几 MB 的二进制，总大小就是十几 MB。构建和运行的写法细节在 &lt;a href=&quot;/posts/dockerfile-guide/&quot;&gt;Dockerfile 编写指南&lt;/a&gt; 里有系统展开，这里只盯瘦身相关的点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;stage 命名&lt;/strong&gt;：&lt;code&gt;FROM ... AS builder&lt;/code&gt; 给阶段起名，后面 &lt;code&gt;COPY --from=builder&lt;/code&gt; 按名引用；不命名也能用 &lt;code&gt;--from=0&lt;/code&gt; 按序号，但可读性差很多。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;只构建某个 stage&lt;/strong&gt;：调试时不必跑完整流程，&lt;code&gt;docker build --target builder -t myapp:debug .&lt;/code&gt; 只构建到指定 stage，方便进 builder 里看中间产物。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;依赖清单先行&lt;/strong&gt;：先 &lt;code&gt;COPY go.mod go.sum&lt;/code&gt; 再 &lt;code&gt;COPY . .&lt;/code&gt;，是利用构建缓存的经典手法——源码天天改、依赖不常变，依赖下载层就能反复命中缓存。缓存机制的完整玩法见 &lt;a href=&quot;/posts/docker-buildkit-cache/&quot;&gt;BuildKit 缓存与构建加速&lt;/a&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Node.js 项目同理，思路完全一致：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;FROM node:22-bookworm AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build &amp;amp;&amp;amp; npm prune --omit=dev

FROM node:22-bookworm-slim
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package.json ./
USER node
CMD [&quot;node&quot;, &quot;dist/main.js&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;npm prune --omit=dev&lt;/code&gt; 在 builder 里先把 devDependencies 剃掉，再拷 &lt;code&gt;node_modules&lt;/code&gt;——拷过来的就已经是瘦的了。&lt;/p&gt;
&lt;p&gt;:::warning
多阶段构建最常见的翻车是「最终 stage 把整个 builder 的工作目录全拷过来」，比如 &lt;code&gt;COPY --from=builder /app ./&lt;/code&gt;，那工具链、源码、缓存又全回来了，和没分阶段一样。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;COPY --from 只拷明确列出的产物路径，不要整目录照单全收&amp;lt;/span&amp;gt;。
:::&lt;/p&gt;
&lt;h2&gt;基础镜像选型：地板厚度决定下限&lt;/h2&gt;
&lt;p&gt;多阶段决定了「带多少东西走」，基础镜像决定「起步就有多重」。同一个程序，基础镜像从完整版换到 distroless，轻松差出几百 MB：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;基础镜像&lt;/th&gt;
&lt;th&gt;体积量级&lt;/th&gt;
&lt;th&gt;包管理器&lt;/th&gt;
&lt;th&gt;有 shell&lt;/th&gt;
&lt;th&gt;适用场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;debian / ubuntu 完整版&lt;/td&gt;
&lt;td&gt;100–200 MB 起&lt;/td&gt;
&lt;td&gt;apt 齐全&lt;/td&gt;
&lt;td&gt;有&lt;/td&gt;
&lt;td&gt;构建阶段、需要大量系统工具调试时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;*-slim（如 debian-slim、node:slim）&lt;/td&gt;
&lt;td&gt;比完整版少一半左右&lt;/td&gt;
&lt;td&gt;apt 可用（精简了文档等）&lt;/td&gt;
&lt;td&gt;有&lt;/td&gt;
&lt;td&gt;通用运行镜像的稳妥选择&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;alpine&lt;/td&gt;
&lt;td&gt;约 5–10 MB&lt;/td&gt;
&lt;td&gt;apk&lt;/td&gt;
&lt;td&gt;有（sh）&lt;/td&gt;
&lt;td&gt;体积敏感、依赖简单的服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;distroless（gcr.io/distroless）&lt;/td&gt;
&lt;td&gt;20–100 MB（按语言分）&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;生产环境跑静态语言 / JVM / Node 成品&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;scratch&lt;/td&gt;
&lt;td&gt;0 MB&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;静态编译的单二进制（Go、Rust 静态产物）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选型原则很简单：&lt;strong&gt;能静态编译的语言优先 scratch 或 distroless，需要运行时解释器的选对应语言的 distroless 或 slim，alpine 不要无脑上&lt;/strong&gt;。&lt;/p&gt;
&lt;h3&gt;alpine 的三个坑&lt;/h3&gt;
&lt;p&gt;alpine 只有几 MB 很诱人，但它的 C 库是 musl libc，和主流发行版的 glibc 不是一回事，坑都出在这里：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;二进制不兼容&lt;/strong&gt;：为 glibc 编译的预编译二进制（很多官方发布的 &lt;code&gt;.tar.gz&lt;/code&gt; 成品、某些 Node 原生模块、Python 的 manylinux wheel）拷进 alpine 直接跑不起来，报的还是迷惑性的 &lt;code&gt;not found&lt;/code&gt;——文件明明在，是动态链接器找不到。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;DNS 解析差异&lt;/strong&gt;：musl 的解析器行为和 glibc 不完全一致，老问题包括不支持 DNS 搜索域的某些展开方式、并发查询行为不同，偶发「在别的镜像里能解析、在 alpine 里间歇失败」。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;时区数据缺失&lt;/strong&gt;：alpine 默认没有 tzdata，容器里时间显示成 UTC、定时任务按错时区跑，要 &lt;code&gt;apk add tzdata&lt;/code&gt; 另装，或者挂载宿主机的 &lt;code&gt;/etc/localtime&lt;/code&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要为了省几十 MB，把一个在 debian 下跑得好好的服务硬迁到 alpine&amp;lt;/span&amp;gt;。musl 兼容性问题往往在上线后才以诡异的方式爆出来，省下的体积远不抵排障的成本。先 slim，确认依赖都兼容再考虑 alpine。
:::&lt;/p&gt;
&lt;h3&gt;合并 RUN 与同层清理&lt;/h3&gt;
&lt;p&gt;不方便多阶段的老镜像，先做同层清理也能瘦一圈。原则是：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;安装和清理必须写在同一条 RUN 里，跨层删除不减小体积&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 反例：三层分开写，清理层删了也白删，前面的层照样占空间
RUN apt-get update
RUN apt-get install -y curl git
RUN rm -rf /var/lib/apt/lists/*

# 正例：一条 RUN 里装完就清，缓存只存在于构建过程，不落层
RUN apt-get update \
    &amp;amp;&amp;amp; apt-get install -y --no-install-recommends curl git \
    &amp;amp;&amp;amp; rm -rf /var/lib/apt/lists/*
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;要点：&lt;code&gt;--no-install-recommends&lt;/code&gt; 不装推荐包（往往是一大堆用不上的东西）；&lt;code&gt;apt-get clean&lt;/code&gt; 和删 &lt;code&gt;/var/lib/apt/lists/*&lt;/code&gt; 必须跟安装在同一层。其他生态同理：&lt;code&gt;npm cache clean --force&lt;/code&gt;、&lt;code&gt;pip install --no-cache-dir&lt;/code&gt;、apk 用 &lt;code&gt;--no-cache&lt;/code&gt;，都是不让缓存落层。&lt;/p&gt;
&lt;h2&gt;dive 逐层验尸：让每一层都说清楚自己装了什么&lt;/h2&gt;
&lt;p&gt;凭感觉瘦身容易漏，dive（wagoodman/dive，GitHub 开源工具）是专门干逐层分析的：它把镜像每一层的文件增、删、改列出来，还给出「浪费空间」的量化指标——比如同一文件在多层里被反复修改、删除后仍占空间的字节数，以及一个效率评分。&lt;/p&gt;
&lt;p&gt;本机交互式分析：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 直接分析本地镜像，进入终端界面逐层浏览
dive myapp:latest

# 也可以直接对着 Dockerfile 边构建边分析
dive build -t myapp:latest .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;界面里左边是层列表，右边是该层的文件树变化：新增、修改、删除的文件分开标色。重点盯两类东西：一是单层里莫名出现的大目录（多半是缓存或误拷进来的构建上下文），二是某个大文件在后面的层里被「删除」了——文件删得掉，体积删不掉，这正是分层机制产生浪费的地方。&lt;/p&gt;
&lt;p&gt;退出界面后，dive 还会给出几个汇总指标，看懂它们就知道该往哪砍：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;指标&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;怎么用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Wasted space&lt;/td&gt;
&lt;td&gt;被后续层覆盖或删除、但仍实占体积的字节数&lt;/td&gt;
&lt;td&gt;越大说明「先装后删」越多，优先改同层清理或多阶段&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Efficiency score&lt;/td&gt;
&lt;td&gt;有效内容占总体积的比例&lt;/td&gt;
&lt;td&gt;明显偏低基本都有层浪费，先查清楚再动手&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Wasted bytes 明细&lt;/td&gt;
&lt;td&gt;每个文件浪费了多少、分布在哪一层&lt;/td&gt;
&lt;td&gt;照着清单逐个处理，不用凭感觉猜&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;典型的一次验尸长这样：总体积 1.2 GB，浪费空间占了大半，其中大头是构建缓存被整目录拷进了最终镜像，其次是 apt 的包列表在独立的层里残留——两个问题分别对应多阶段隔离和同层清理，一改就见效。先量再砍，比对着经验逐条试错快得多。&lt;/p&gt;
&lt;p&gt;CI 里可以让 dive 按阈值把关，镜像太胖直接让流水线失败：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# CI=true 时 dive 不进交互界面，按规则判定通过 / 失败
CI=true dive myapp:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;阈值写在项目根目录的 &lt;code&gt;.dive-ci&lt;/code&gt; 配置里，常用的三项是最低效率、最大浪费字节数、单层最大浪费字节数，具体字段以 dive 仓库的文档为准。瘦完的镜像建议再用 &lt;a href=&quot;/posts/docker-trivy-scan/&quot;&gt;Trivy&lt;/a&gt; 扫一遍漏洞：换基础镜像、削层数都会改变漏洞面，瘦身和安全要一起验收。&lt;/p&gt;
&lt;h2&gt;.dockerignore：先把垃圾挡在构建上下文之外&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;COPY . .&lt;/code&gt; 是胖镜像的另一大源头：构建上下文里有什么，它就往镜像里搬什么。&lt;code&gt;.git&lt;/code&gt;、本地 &lt;code&gt;node_modules&lt;/code&gt;、日志、测试产物、编辑器临时文件，全都是这么混进去的。在项目根目录放一个 &lt;code&gt;.dockerignore&lt;/code&gt;，写法和 &lt;code&gt;.gitignore&lt;/code&gt; 基本一致：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;.git
node_modules
dist
*.log
.env
.DS_Store
.idea
.vscode
coverage
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;对照一张清单自查，缺哪样补哪样：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;该排除的&lt;/th&gt;
&lt;th&gt;不排除的后果&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;.git&lt;/td&gt;
&lt;td&gt;整个仓库历史进镜像，又大又泄密&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;node_modules / vendor 等本地依赖目录&lt;/td&gt;
&lt;td&gt;和镜像内重新安装的依赖叠加，体积翻倍还可能版本打架&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;日志、coverage、测试快照&lt;/td&gt;
&lt;td&gt;纯垃圾，白占层空间&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;.env、密钥文件&lt;/td&gt;
&lt;td&gt;不是体积问题，是安全事故&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本地构建产物（dist、target 等）&lt;/td&gt;
&lt;td&gt;旧产物污染新构建，结果不可复现&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;它有两个收益：一是构建上下文变小，&lt;code&gt;docker build&lt;/code&gt; 时上传上下文更快、构建更利索；二是避免无关文件变化让 &lt;code&gt;COPY&lt;/code&gt; 层缓存无谓失效——改一行日志文件就导致整层重建，是很常见的莫名其妙的慢。&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;.env 和密钥文件一定要写进 .dockerignore&amp;lt;/span&amp;gt;。它们一旦被 &lt;code&gt;COPY&lt;/code&gt; 进镜像，删层也删不干净，镜像推到任何仓库都等于把密钥公开了。真需要在构建时用密钥，走 BuildKit 的 secret 挂载，不要进上下文、更不要进层。
:::&lt;/p&gt;
&lt;h2&gt;无 shell 的镜像怎么排障&lt;/h2&gt;
&lt;p&gt;distroless 和 scratch 瘦是瘦，代价是进去之后没有 shell：&lt;code&gt;docker exec -it&lt;/code&gt; 连不进，&lt;code&gt;ls&lt;/code&gt;、&lt;code&gt;cat&lt;/code&gt;、&lt;code&gt;ps&lt;/code&gt; 全都没有。线上出问题时别慌，有三条正规路子：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;1. 把文件拷出来看。&lt;/strong&gt; 容器不用 exec 也能用 &lt;code&gt;docker cp&lt;/code&gt; 往外拷日志和配置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker cp myapp:/var/log/app.log ./app.log
docker cp myapp:/app/config.yaml ./config.yaml
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;2. 用带 shell 的调试容器共享命名空间。&lt;/strong&gt; 另起一个工具齐全的容器，加入目标容器的进程和网络命名空间，从「隔壁」看它：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 共享进程命名空间：能看到目标容器的进程、/proc 下的一切
docker run -it --rm --pid=container:myapp busybox sh

# 共享网络命名空间：在目标容器的网络视角里抓包、测连通性
docker run -it --rm --net=container:myapp nicolaka/netshoot bash
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;另外，distroless 官方还提供带 &lt;code&gt;:debug&lt;/code&gt; 标签的变体镜像，内置了 busybox shell，专门给排障留的：平时用无 shell 的正式版，真出问题时临时换成同版本的 &lt;code&gt;:debug&lt;/code&gt; 镜像跑一遍，定位完再换回去。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 临时换回带 shell 的基础镜像定位。&lt;/strong&gt; 把最终 stage 的基础镜像临时改成对应的 slim 版（其他不变）重新构建，进去把问题查清楚，修完再切回 distroless。这招笨但可靠，尤其适合「只有在无 shell 镜像里才复现」的怪问题，先确认是不是缺了某个运行时文件。&lt;/p&gt;
&lt;h2&gt;瘦完怎么验收：留一张对照表&lt;/h2&gt;
&lt;p&gt;瘦身不是改完就完，每次动完 Dockerfile，用同一组命令量一遍、留个记录，避免越改越胖或者把东西削没了：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker images myapp
docker history myapp:latest
docker system df
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;一个典型的瘦身前后对照大概是这个量级（具体数字取决于项目，这里只示意结构）：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;阶段&lt;/th&gt;
&lt;th&gt;做法&lt;/th&gt;
&lt;th&gt;体积量级&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;初始版&lt;/td&gt;
&lt;td&gt;单阶段、完整版基础镜像、整目录 COPY&lt;/td&gt;
&lt;td&gt;1 GB 以上&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;第一刀&lt;/td&gt;
&lt;td&gt;.dockerignore + 同层清理缓存&lt;/td&gt;
&lt;td&gt;砍掉一两百 MB 的垃圾和缓存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;第二刀&lt;/td&gt;
&lt;td&gt;多阶段构建，只拷产物&lt;/td&gt;
&lt;td&gt;工具链整段消失，通常是最大的一刀&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;第三刀&lt;/td&gt;
&lt;td&gt;基础镜像换 slim / distroless / scratch&lt;/td&gt;
&lt;td&gt;摸到下限，几十 MB 级&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;验收时除了看体积，还要把容器真正跑起来过一遍核心流程：体积达标但程序起不来，等于白干。尤其是换基础镜像和削层之后，缺库、缺证书、缺时区数据这类问题只会在运行时暴露。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;h3&gt;1. 瘦身后程序起不来，报缺库&lt;/h3&gt;
&lt;p&gt;多阶段构建只拷了二进制，却漏了它运行时依赖的动态库（&lt;code&gt;.so&lt;/code&gt;）。排查：先在 builder 阶段用 &lt;code&gt;ldd &amp;lt;二进制&amp;gt;&lt;/code&gt; 列出它依赖哪些库，再确认这些库在最终镜像里有没有。对策按顺序选：能静态编译就静态编译（Go 用 &lt;code&gt;CGO_ENABLED=0&lt;/code&gt;、Rust 选 musl 目标）；不能静态的，最终镜像选带齐基础库的 distroless 对应变体或 slim，把缺的库随产物一起 &lt;code&gt;COPY --from&lt;/code&gt; 过去。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;最忌讳的是图省事把整个 builder 的 /usr/lib 全拷过去&amp;lt;/span&amp;gt;，那等于把瘦身成果又还回去大半。&lt;/p&gt;
&lt;h3&gt;2. 二进制在 alpine 里跑不起来，报 not found&lt;/h3&gt;
&lt;p&gt;文件明明存在、权限也没问题，却报 &lt;code&gt;No such file or directory&lt;/code&gt;——这是 musl 与 glibc 不兼容的经典症状：缺的不是二进制本身，而是它要的 glibc 动态链接器（&lt;code&gt;/lib64/ld-linux-x86-64.so.2&lt;/code&gt;），alpine 里根本没有。用 &lt;code&gt;file &amp;lt;二进制&amp;gt;&lt;/code&gt; 看它是不是 dynamically linked、链的是哪个解释器就能确认。对策：要么在 alpine 里重新编译出 musl 版本，要么给它装 glibc 兼容层（不推荐，坑更多），要么干脆换回 glibc 系的 slim / distroless 基础镜像——多数情况下第三条最省事。&lt;/p&gt;
&lt;h3&gt;3. 清理缓存写了，体积却没降&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;rm -rf /var/lib/apt/lists/*&lt;/code&gt; 写在单独一层里，是最常见的原因：删除只产生一个遮罩层，下面的层纹丝不动，&lt;code&gt;docker history&lt;/code&gt; 里能清楚看到安装层还是那么大。对策是把安装、clean、删列表合并进同一条 &lt;code&gt;RUN&lt;/code&gt;（见前面同层清理的正例），重构后逐层对照 &lt;code&gt;docker history&lt;/code&gt; 验证。另外注意构建缓存的假象：改完 Dockerfile 如果命中了旧缓存层，体积当然不变，必要时 &lt;code&gt;docker build --no-cache&lt;/code&gt; 强制全量重建再量。&lt;/p&gt;
&lt;h3&gt;4. 换了 distroless 之后调不通 HTTPS&lt;/h3&gt;
&lt;p&gt;程序一调外部 HTTPS 接口就报证书错误。scratch 和部分 distroless 变体里没有预置 CA 根证书，TLS 校验无从下手。对策：从 builder 镜像里把证书文件拷进最终镜像（前面 Go 的例子里那行 &lt;code&gt;COPY --from=builder /etc/ssl/certs/ca-certificates.crt ...&lt;/code&gt; 干的就是这件事）；Java、Node 等语言的 distroless 变体一般自带证书，选型时先查对应变体的说明再动手。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;镜像瘦身没有玄学，就是三件事：&lt;strong&gt;多阶段构建&lt;/strong&gt;让工具链和源码留在构建阶段，最终镜像只拿产物；&lt;strong&gt;基础镜像选型&lt;/strong&gt;决定地板厚度，能静态编译的走 scratch / distroless，需要运行时的用 slim，alpine 先想清楚 musl 的坑；&lt;strong&gt;dive 逐层验尸&lt;/strong&gt;负责验收和防反弹，浪费在哪一层、占多少字节，全都量得出来。再加上 &lt;code&gt;.dockerignore&lt;/code&gt; 挡住上下文垃圾、同层清理不让缓存落层，一个 1.2 GB 的镜像瘦到几十 MB 是常态。瘦完别忘了代价那一面：无 shell 镜像排障要提前练好 &lt;code&gt;docker cp&lt;/code&gt; 和共享命名空间这两招，别等线上出事才现学。镜像瘦下来之后，推送和拉取快了，磁盘省了，攻击面也跟着小了——这笔账怎么算都划算。&lt;/p&gt;
</content:encoded></item><item><title>Docker 日志与存储驱动的性能账：选错一个，慢的是整个服务</title><link>https://www.anexns.cloudns.org/posts/docker-logging-storage-perf/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-logging-storage-perf/</guid><description>json-file、local、journald 三个日志驱动的性能与代价对比，blocking 与 non-blocking 的取舍，再加上 overlay2 与 vfs 的存储驱动账本：查清自己在用什么，换驱动要付出什么代价。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;同一个服务，镜像没变、代码没变，只是把日志驱动从默认值换掉，写入吞吐能差出一截；存储驱动选错更夸张，镜像层不再共享，每起一个容器都是一次整文件复制。这两笔账平时不显眼，因为默认配置对大多数场景够用；可一旦服务开始高频打日志、容器数量上了规模，或者宿主机磁盘开始吃紧，驱动选型就是绕不过去的一课。&lt;/p&gt;
&lt;p&gt;日志那边怎么配轮转、怎么查日志，&lt;a href=&quot;/posts/docker-logging/&quot;&gt;Docker 日志管理&lt;/a&gt;那篇已经讲过，本篇不重复，只算性能与代价这笔账：每个驱动快在哪、慢在哪、丢日志的风险藏在哪。&lt;/p&gt;
&lt;h2&gt;先查清：自己到底在用什么驱动&lt;/h2&gt;
&lt;p&gt;动手之前先看现状，两个命令就够：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker info | grep -E &quot;Storage Driver|Logging Driver&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出大致是这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt; Storage Driver: overlay2
 Logging Driver: json-file
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这是 daemon 级的默认值。单个容器实际用的驱动可能被 &lt;code&gt;--log-driver&lt;/code&gt; 单独覆盖过，查某个容器要用 inspect：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker inspect -f &apos;{{.HostConfig.LogConfig.Type}}&apos; 容器名
docker inspect -f &apos;{{.Driver}}&apos; 容器名
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;先确认现状再谈优化，是驱动调优的第一原则&amp;lt;/span&amp;gt;：很多人以为自己在用 json-file，实际上老容器是当年用别的驱动起的，daemon 改了默认值也影响不到它们。&lt;/p&gt;
&lt;h2&gt;日志驱动五方对比&lt;/h2&gt;
&lt;p&gt;Docker 的日志驱动决定容器 stdout/stderr 写到哪里、以什么代价写。下面是五个常用驱动的官方口径对比：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;驱动&lt;/th&gt;
&lt;th&gt;日志去向&lt;/th&gt;
&lt;th&gt;轮转&lt;/th&gt;
&lt;th&gt;docker logs 能否读&lt;/th&gt;
&lt;th&gt;性能与代价&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;json-file&lt;/td&gt;
&lt;td&gt;宿主机 JSON 文件&lt;/td&gt;
&lt;td&gt;无自动轮转，必须配 max-size/max-file&lt;/td&gt;
&lt;td&gt;能，直接读文件&lt;/td&gt;
&lt;td&gt;默认选项，简单可靠；高频写入时序列化与落盘开销明显&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;local&lt;/td&gt;
&lt;td&gt;宿主机二进制文件&lt;/td&gt;
&lt;td&gt;自带轮转与压缩，有默认上限&lt;/td&gt;
&lt;td&gt;能&lt;/td&gt;
&lt;td&gt;官方为高性能场景推荐，写入路径更短&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;journald&lt;/td&gt;
&lt;td&gt;systemd journal&lt;/td&gt;
&lt;td&gt;由 journal 自身策略管理&lt;/td&gt;
&lt;td&gt;能（较新版本）&lt;/td&gt;
&lt;td&gt;带容器元数据标签，用 journalctl 查；依赖宿主机跑 systemd&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;syslog&lt;/td&gt;
&lt;td&gt;syslog 设施（本地或远程）&lt;/td&gt;
&lt;td&gt;由 syslog 服务管理&lt;/td&gt;
&lt;td&gt;不能&lt;/td&gt;
&lt;td&gt;适合已有日志集中收集体系的环境&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;none&lt;/td&gt;
&lt;td&gt;丢弃&lt;/td&gt;
&lt;td&gt;不适用&lt;/td&gt;
&lt;td&gt;不能&lt;/td&gt;
&lt;td&gt;零开销最快，但出事时两眼一抹黑&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;逐个说清：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;json-file&lt;/strong&gt; 是默认驱动，日志以 JSON 格式逐行落盘，&lt;code&gt;docker logs&lt;/code&gt; 直接读这个文件。它的问题不在功能而在两点：一是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;它没有自动轮转，不配 max-size/max-file 日志文件会无限长大&amp;lt;/span&amp;gt;，把磁盘吃满只是时间问题；二是每行日志都要做 JSON 序列化，高频输出的服务这笔开销实打实。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;local&lt;/strong&gt; 是 Docker 官方专门为性能做的驱动：内部格式更紧凑，自带轮转和压缩，默认上限是 max-size 20m、max-file 5，也就是单个容器最多留约 100 MB 日志，不用再操心爆盘。它同样支持 &lt;code&gt;docker logs&lt;/code&gt;，日常使用习惯和 json-file 没有区别。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;journald&lt;/strong&gt; 把日志送进 systemd 的 journal，好处是天然带上容器名、镜像等元数据标签，运维可以用熟悉的 &lt;code&gt;journalctl&lt;/code&gt; 按单元、按时间过滤：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;journalctl CONTAINER_NAME=容器名 -f
journalctl -u docker --since &quot;1 hour ago&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;代价是宿主机必须跑 systemd，且日志多了一道转发。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;syslog&lt;/strong&gt; 适合已经有集中日志体系（比如统一收集到日志服务器）的环境，容器日志直接进现有管道；但 &lt;code&gt;docker logs&lt;/code&gt; 读不到它，排障时要去日志系统里捞。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;none&lt;/strong&gt; 直接丢弃所有日志，写入开销为零。只适合那种日志另有出口（应用自己写文件、自己上报）的服务，普通服务用它等于主动放弃唯一的排障线索。&lt;/p&gt;
&lt;h2&gt;local 为什么是认真选项&lt;/h2&gt;
&lt;p&gt;很多人对 local 的印象还停留在「新驱动、不敢用」。实际上它的定位很明确：当你不需要把日志转发到外部系统、只想在宿主机上留一份能查的日志时，local 就是比 json-file 更优的默认。&lt;/p&gt;
&lt;p&gt;两者的取舍可以这样算：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;json-file&lt;/th&gt;
&lt;th&gt;local&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;轮转&lt;/td&gt;
&lt;td&gt;必须手动配 max-size/max-file&lt;/td&gt;
&lt;td&gt;自带，默认 20m × 5&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;压缩&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;自带压缩，省磁盘&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;写入开销&lt;/td&gt;
&lt;td&gt;JSON 逐行序列化&lt;/td&gt;
&lt;td&gt;二进制格式，开销更低&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;docker logs&lt;/td&gt;
&lt;td&gt;支持&lt;/td&gt;
&lt;td&gt;支持&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;日志文件可读性&lt;/td&gt;
&lt;td&gt;文本，可直接 cat/grep&lt;/td&gt;
&lt;td&gt;二进制，需 docker logs 读取&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;唯一的实质让步是日志文件不再是纯文本，没法直接用 &lt;code&gt;grep&lt;/code&gt; 翻宿主机上的文件。但说实话，查容器日志本来就该用 &lt;code&gt;docker logs&lt;/code&gt;，直接翻文件的场景少之又少。给 json-file 补上轮转配置是这样的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d \
  --log-driver json-file \
  --log-opt max-size=20m \
  --log-opt max-file=5 \
  镜像名
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;而 local 连这份配置都可以省掉，或者按需调大：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d \
  --log-driver local \
  --log-opt max-size=50m \
  --log-opt max-file=5 \
  镜像名
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
不要被「高性能」三个字冲昏头：如果你的日志本来就要进集中收集系统（journald、syslog 或外部采集器在读文件），换 local 反而会打断现有管道。驱动选型先看日志最终要去哪，再看快不快。
:::&lt;/p&gt;
&lt;h2&gt;被忽略的代价：日志的双写与阻塞模式&lt;/h2&gt;
&lt;p&gt;还有一笔账藏在日志驱动的投递模式里。容器进程写 stdout，看起来是写给「管道」，实际上 Docker 要把这份输出再投递给日志驱动落盘或转发——这就是所谓的双写。投递模式有两种：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;blocking（阻塞，默认）&lt;/strong&gt;：日志驱动处理慢时，容器的写操作会被卡住等它。日志系统一卡顿，应用跟着卡顿。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;non-blocking（非阻塞）&lt;/strong&gt;：日志先进内存缓冲，缓冲满了就丢弃新日志，应用永远不等。&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;docker run -d \
  --log-driver json-file \
  --log-opt mode=non-blocking \
  --log-opt max-buffer-size=10m \
  镜像名
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;取舍很清楚：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;blocking 模式下，日志管道的延迟就是应用的延迟&amp;lt;/span&amp;gt;，一个写日志的网络驱动抖一下，高并发服务能被拖到超时；non-blocking 保住了应用吞吐，代价是极端情况下日志会缺斤少两。对绝大多数业务服务，日志完整性的优先级低于服务可用性，non-blocking + 一个够大的缓冲是更合理的组合；只有审计类、计费类这种「一行都不能丢」的日志，才值得用 blocking 并接受它的代价。&lt;/p&gt;
&lt;h2&gt;存储驱动：overlay2 的地位与 vfs 的真实用途&lt;/h2&gt;
&lt;p&gt;存储驱动决定镜像层和容器可写层怎么落在磁盘上。这一项的选择空间其实很小：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;overlay2&lt;/strong&gt; 是当前默认、也是官方推荐的存储驱动，基于内核的 OverlayFS，镜像层共享、容器只写差异层，空间和速度都在线。它对底层文件系统有要求：宿主机文件系统须是 ext4，或者 xfs 且 &amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;xfs 必须以 ftype=1 格式化&amp;lt;/span&amp;gt;，否则 overlay2 起不来。查 xfs 的 ftype：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;xfs_info /var/lib/docker | grep ftype
# 输出里应有 ftype=1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;vfs&lt;/strong&gt; 是另一个极端：它不用任何联合文件系统，每一层都是实打实的目录拷贝，不共享、不写时复制。起一个容器就是把镜像文件整份复制一遍，慢且费盘。它存在的意义只有排障——当内核或文件系统环境特殊到 overlay2 实在跑不起来时，vfs 能让 Docker 至少能工作，用来验证「问题是不是出在存储驱动上」。生产环境长期用 vfs，等于自愿放弃镜像层共享的全部好处。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;btrfs 与 zfs&lt;/strong&gt; 驱动各自绑定对应文件系统，有自己的快照与校验场景，但它们不是官方默认推荐路线，宿主机没在用这两个文件系统就不用考虑，不要为了「看起来高级」去换。&lt;/p&gt;
&lt;p&gt;关于层数有个常见误解：层越多，overlay 查找文件时要穿透的层数越多，理论开销确实存在；但在现代内核下这点差距小到很难测出来，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;真正吃掉 IO 的大头，通常是日志写入和数据卷里的应用数据，而不是镜像层数&amp;lt;/span&amp;gt;。为省两层去大改 Dockerfile，收益远不如先把日志驱动和数据卷理顺。&lt;/p&gt;
&lt;p&gt;overlay2 的层数据落在宿主机的这个目录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;du -sh /var/lib/docker/overlay2
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这个目录只许看、&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝不许手工进去删文件&amp;lt;/span&amp;gt;——层之间的引用关系由 Docker 自己维护，手删一层，依赖它的镜像和容器全会损坏。空间治理要用 Docker 自己的命令，方法在 &lt;a href=&quot;/posts/docker-disk-governance/&quot;&gt;Docker 磁盘空间治理&lt;/a&gt;那篇里。&lt;/p&gt;
&lt;h2&gt;换驱动的操作与代价&lt;/h2&gt;
&lt;p&gt;日志驱动可以在两个级别设置。daemon 级写进 &lt;code&gt;/etc/docker/daemon.json&lt;/code&gt;，影响之后新建的容器：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;log-driver&quot;: &quot;local&quot;,
  &quot;log-opts&quot;: {
    &quot;max-size&quot;: &quot;20m&quot;,
    &quot;max-file&quot;: &quot;5&quot;
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改完重启 Docker 生效：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl restart docker
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;容器级则在启动时用 &lt;code&gt;--log-driver&lt;/code&gt; 单独指定，优先级高于 daemon 默认。&lt;/p&gt;
&lt;p&gt;必须知道的代价是：&lt;strong&gt;已经在跑的容器不会跟着变&lt;/strong&gt;。驱动是容器创建时定下来的配置，改 daemon.json、甚至重启 Docker，老容器依然用旧驱动继续写。想让某个容器换驱动，只能删掉重建：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker rm -f 容器名
docker run -d --log-driver local ... 镜像名
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
重建容器前先确认数据在数据卷或绑定挂载里，不在容器可写层——可写层会随容器删除一起消失。无状态服务随便重建，有状态服务先做备份再动。
:::&lt;/p&gt;
&lt;p&gt;存储驱动的切换代价更大：它同样写在 daemon.json 的 &lt;code&gt;storage-driver&lt;/code&gt; 字段里，但切换之后，旧驱动下已有的镜像和容器在新驱动视角里等于不存在（数据还躺在磁盘上，但 Docker 不再认）。所以存储驱动只适合在新装机器、或明确打算清空重来的机器上动，老机器维持 overlay2 现状就是最优解。daemon 级的其他调优项（镜像加速、并发、数据根目录等）集中在 &lt;a href=&quot;/posts/docker-daemon-tuning/&quot;&gt;Docker 守护进程调优&lt;/a&gt;那篇。&lt;/p&gt;
&lt;h2&gt;排障小节&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. &lt;code&gt;docker logs&lt;/code&gt; 读不到日志，怀疑驱动选错&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;先查这个容器实际的驱动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker inspect -f &apos;{{.HostConfig.LogConfig.Type}}&apos; 容器名
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果驱动是 syslog 或 none，&lt;code&gt;docker logs&lt;/code&gt; 本来就读不到，去日志系统里查或直接放弃这条线；如果是 journald，较新版本的 Docker 是支持 &lt;code&gt;docker logs&lt;/code&gt; 读取的，读不到时优先怀疑版本太老或 journal 服务异常，改用 &lt;code&gt;journalctl CONTAINER_NAME=容器名&lt;/code&gt; 直接查。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 服务一打日志 CPU 就飙升&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;大概率是 blocking 模式在拖后腿：应用每次写 stdout 都在等日志落盘。先看驱动与模式：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker inspect -f &apos;{{json .HostConfig.LogConfig}}&apos; 容器名
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;处理方向：换 local 降低单次写入开销，或给驱动加 &lt;code&gt;mode=non-blocking&lt;/code&gt; 与合理的 &lt;code&gt;max-buffer-size&lt;/code&gt;，重建容器生效。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. Docker 起不来，日志报 overlay2 相关错误&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;在 xfs 宿主机上最常见的原因是格式化时没带 ftype=1：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;xfs_info / | grep ftype
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;若是 ftype=0，overlay2 无法工作，这个参数不能在线修改，只能备份数据、重新格式化文件系统（mkfs.xfs 默认已带 ftype=1，老镜像装的系统容易踩）。临时验证可以用 vfs 驱动把 Docker 拉起来确认其余部分正常，但 vfs 只作诊断，别当长期方案。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 换了 daemon 默认驱动，老容器日志还是老样子&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;这不是没生效，而是机制如此：驱动在容器创建时固化。逐个确认哪些容器还在用旧驱动，排期重建即可，别反复重启 Docker 浪费时间。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;驱动这笔账的结论并不复杂：日志侧，没有外部收集需求时 local 是比 json-file 更省心的默认，自带轮转压缩、写入更轻；保留 json-file 就必须配 max-size/max-file。投递模式上，业务服务优先 non-blocking 保可用性，审计日志才用 blocking 换完整性。存储侧，overlay2 就是答案，保持底层 ext4 或 xfs ftype=1 即可，vfs 只留给排障验证。最后记住两条操作纪律：换日志驱动要重建容器，&lt;code&gt;/var/lib/docker/overlay2&lt;/code&gt; 只看不删。&lt;/p&gt;
</content:encoded></item><item><title>Docker 网络性能优化：把转发路径上的每一层账算清</title><link>https://www.anexns.cloudns.org/posts/docker-network-performance/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-network-performance/</guid><description>同一个服务跑在容器里，吞吐只有宿主机的一半，问题出在哪？这篇只算性能的账：端口发布的 NAT 与 userland-proxy 两层转发、host 模式的速度与代价、MTU 分片这个隐形坑、容器 DNS 慢的排查，再用 iperf3 把优化前后的差距测出来。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;先说一个很多人都遇到过的场景：同一个服务，直接跑在宿主机上测速能跑满千兆网卡，装进 Docker 容器、映射好端口再测，吞吐只剩一半，延迟还高了一截。代码没动、网卡没换，性能就这么凭空蒸发了。蒸发到哪去了？答案在转发路径上——数据包从网卡进到容器，中途过的每一层手，都要收一点「过路费」。&lt;/p&gt;
&lt;p&gt;上一篇 &lt;a href=&quot;/posts/docker-network/&quot;&gt;《Docker 网络详解：从 bridge 到 IPv6》&lt;/a&gt; 讲的是连通性：有哪些网络模式、端口怎么映射、容器怎么互访。这篇换个角度，只算性能的账：转发路径上到底有几层、哪一层最贵、能关的怎么关、关不了的怎么绕开，最后用 iperf3 把每一步优化的实际收益测出来。网络不通是功能问题，网络慢是性能问题，排查思路完全不同，别混着来。&lt;/p&gt;
&lt;h2&gt;转发路径上到底有几层&lt;/h2&gt;
&lt;p&gt;以最常见的场景为例：外部请求访问宿主机的 8080 端口，转发给 bridge 网络里容器的 80 端口。数据包的完整旅程是这样的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;外部请求 → 宿主机网卡 → iptables NAT（DNAT 改写目标地址）→ docker0 网桥 → veth 网卡对 → 容器网卡 → 容器内服务
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里面真正收「过路费」的是两层：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;转发层&lt;/th&gt;
&lt;th&gt;做什么&lt;/th&gt;
&lt;th&gt;性能代价&lt;/th&gt;
&lt;th&gt;能不能去掉&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;iptables NAT&lt;/td&gt;
&lt;td&gt;改写数据包的目标/源地址，做端口映射与出网伪装&lt;/td&gt;
&lt;td&gt;每个连接首包要查规则链，后续包走 conntrack 表；规则多了、连接数大了开销可观，但总体可控&lt;/td&gt;
&lt;td&gt;bridge 模式下端口发布离不开它；想彻底绕开只能换网络模式&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;userland-proxy（docker-proxy）&lt;/td&gt;
&lt;td&gt;一个用户态进程，在特定场景下代替内核做端口转发&lt;/td&gt;
&lt;td&gt;数据要在内核态和用户态之间来回拷贝，高并发下是实打实的瓶颈&lt;/td&gt;
&lt;td&gt;可以，daemon.json 里关掉（见下一节）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;先把概念分清：&lt;strong&gt;端口发布的默认路径是 iptables NAT&lt;/strong&gt;，也就是内核里的 netfilter 直接改写地址，这是主力通道。userland-proxy 是个兜底进程（你会在宿主机上看到名为 &lt;code&gt;docker-proxy&lt;/code&gt; 的进程），它主要在 NAT 不方便处理的场景顶上，最典型的是 hairpin 场景——容器经由宿主机发布的端口回头访问自己或同伴发布的端口，这条回环路径 NAT 处理起来别扭，就交给 docker-proxy 在用户态转发。另外从宿主机本机经 localhost 访问发布端口时，也可能走它。&lt;/p&gt;
&lt;p&gt;问题在于，docker-proxy 是用户态程序，转发一个包要把数据从内核拷到用户态、再拷回去，上下文切换和内存拷贝的成本比内核 NAT 高一个量级。连接数少的时候感觉不到，一旦是高并发短连接或者大流量持续传输，这一层就是肉眼可见的瓶颈。所以优化的第一刀，先砍它。&lt;/p&gt;
&lt;h2&gt;关掉 userland-proxy：收益与前提&lt;/h2&gt;
&lt;p&gt;在 daemon.json 里加一行就能关掉它：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;userland-proxy&quot;: false
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改完重启 Docker 生效：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl restart docker
docker info | grep -i proxy
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;关掉之后，端口发布完全走 iptables NAT，少一层用户态拷贝，吞吐和连接处理能力都会有可感知的提升——尤其是代理类、网关类这种转发密集的服务，收益最明显。本站的定版配置就是关掉它的，这个选择在 &lt;a href=&quot;/posts/docker-security-resources/&quot;&gt;《Docker 安全与资源限制》&lt;/a&gt; 里也提到过，性能和 attack surface 两头都划算。&lt;/p&gt;
&lt;p&gt;但关之前要把前提说清楚：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;userland-proxy 关掉的前提是内核与 iptables 环境正常&amp;lt;/span&amp;gt;。NAT 路径依赖内核的 netfilter、conntrack 模块和 iptables 规则链完整可用；如果宿主机是某些阉割过的内核、云厂商魔改系统，或者 iptables 被其他工具（比如某些面板、防火墙管理工具）搅乱过，关掉兜底进程之后端口发布可能直接出问题。判断方法很简单：改之前先确认现状正常，改之后立刻实测一遍已发布端口的连通性（方法见排障小节），没问题再让它常驻。&lt;/p&gt;
&lt;p&gt;还有一个边界要知道：关掉 userland-proxy 后，hairpin 这类回环访问改由 NAT 环回处理，绝大多数场景没问题，但如果你的服务强依赖「容器经宿主机公网 IP 访问自己发布的端口」这类刁钻路径，上线前务必单独验一遍，别默认它和以前一样。&lt;/p&gt;
&lt;p&gt;daemon.json 里和网络性能相关的其他字段（比如全局 MTU），在 &lt;a href=&quot;/posts/docker-daemon-tuning/&quot;&gt;《Docker 守护进程调优》&lt;/a&gt; 里有集中讲解，这篇只说和转发路径直接相关的部分。&lt;/p&gt;
&lt;h2&gt;host 模式：最快，但代价要付清&lt;/h2&gt;
&lt;p&gt;如果说关 userland-proxy 是「少走一层」，那 host 模式就是「一层都不走」：容器直接使用宿主机的网络命名空间，没有独立网卡、没有网桥、没有 NAT、没有端口映射，容器里监听 80 端口，就是宿主机在监听 80 端口。吞吐和延迟最接近原生裸跑，任何一层转发开销都不存在。对于延迟敏感、吞吐吃满型的服务——比如软路由、流媒体转发、高频行情推送——host 模式的性能账是最划算的。&lt;/p&gt;
&lt;p&gt;启动方式也很简单：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d --network host nginx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意此时 &lt;code&gt;-p&lt;/code&gt; 参数会被直接忽略，因为根本没有「映射」这回事，容器进程监听什么端口，宿主机就开放什么端口。&lt;/p&gt;
&lt;p&gt;代价同样要付清，而且是三笔：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;代价&lt;/th&gt;
&lt;th&gt;具体影响&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;端口隔离没了&lt;/td&gt;
&lt;td&gt;容器端口就是宿主机端口，两个服务抢同一个端口直接冲突，起不来；端口规划要自己当回事&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;命名空间隔离没了&lt;/td&gt;
&lt;td&gt;容器能看到宿主机全部网卡和连接信息，网络层面的隔离边界基本消失&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Compose 编排变味&lt;/td&gt;
&lt;td&gt;端口冲突在部署期才暴露，多实例部署同一个服务几乎不可能&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
host 模式是用隔离换速度，只适合你完全信任、且性能确实卡在网络这一层的服务。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不可信的服务、要对外提供访问的服务，别图快用 host&amp;lt;/span&amp;gt;——它等于把服务的监听面直接摊在宿主机网络上，一旦服务本身被打穿，攻击者所处的位置和直接在宿主机上没区别。先用后面的 iperf3 方法测清楚瓶颈到底在不在转发层，别凭感觉上 host。
:::&lt;/p&gt;
&lt;p&gt;经验法则：先关 userland-proxy、先查 MTU，这两步做完还不够快、且测出来转发层确实是瓶颈，再考虑 host；而且只给单个明确的服务开，不要整个 Compose 工程一股脑全改 host。&lt;/p&gt;
&lt;h2&gt;MTU：小请求正常、大响应卡死，多半是它&lt;/h2&gt;
&lt;p&gt;这是网络性能问题里最阴的一个坑，因为它的症状特别有迷惑性：ping 通、端口通、小请求秒回，但一传大文件、拉大响应就卡死或超时。很多人会去怀疑带宽、怀疑服务性能，查一圈没结果——其实是 MTU 对不上，包在半路上被分片甚至被丢弃了。&lt;/p&gt;
&lt;p&gt;原理一句话：以太网默认 MTU 是 1500，Docker 默认 bridge 网络也用 1500。但如果你的链路中间隔着一层封装——VPN 隧道、PPPoE 拨号、某些云厂商的内网隧道、GRE/WireGuard 之类——封装本身要占几十字节，实际能承载的 MTU 就小于 1500。这时一个 1500 的大包到了隧道口，要么被分片（性能损耗），要么因为带了 DF（不分片）标志被直接丢弃（连接卡死）。小包没到上限，畅通无阻；大包一超限，就卡在那儿了——症状和成因严丝合缝。&lt;/p&gt;
&lt;p&gt;确认方法，先看各段的 MTU：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 宿主机物理网卡
ip link show eth0 | grep mtu
# Docker 默认网桥
ip link show docker0 | grep mtu
# 容器内网卡
docker exec &amp;lt;容器名&amp;gt; ip link show eth0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再用 ping 测路径上到底能过多大的包（&lt;code&gt;-M do&lt;/code&gt; 表示禁止分片，&lt;code&gt;-s&lt;/code&gt; 是包体大小，加上 IP 头和 ICMP 头共 28 字节，测 1500 的 MTU 就用 -s 1472）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ping -M do -s 1472 &amp;lt;目标地址&amp;gt;   # 通：路径 MTU 至少 1500
ping -M do -s 1372 &amp;lt;目标地址&amp;gt;   # 只有这个通：路径 MTU 约 1400
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;解法是把 Docker 网络的 MTU 降到和路径一致。两种设法，作用域不同，别搞混：&lt;/p&gt;
&lt;p&gt;第一种，给单个自定义网络设，只影响这个网络：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker network create --opt com.docker.network.driver.mtu=1400 mynet
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Compose 里对应写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;networks:
  mynet:
    driver_opts:
      com.docker.network.driver.mtu: &quot;1400&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第二种，在 daemon.json 里设全局默认值，影响之后新建的网络：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;mtu&quot;: 1400
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意区分：daemon 级的字段名就是 &lt;code&gt;&quot;mtu&quot;&lt;/code&gt;，而单个网络走的是 &lt;code&gt;--opt com.docker.network.driver.mtu&lt;/code&gt; 这个驱动参数，两者不是同一个写法，别互相抄。改 daemon.json 需要重启 Docker，且只对新建网络生效，已有网络要重建。经验上，WireGuard 隧道环境常用 1400 甚至更低，PPPoE 一般是 1492——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;具体填多少，以你自己链路 ping 测出来的值为准，不要抄别人的数字&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h2&gt;容器 DNS 慢：先分清是发现慢还是解析慢&lt;/h2&gt;
&lt;p&gt;「容器里打开网页慢」「容器里拉镜像、调 API 总要先卡几秒」——这类问题有一半出在 DNS 上。Docker 自定义网络里内置了一个 DNS 服务器，地址是 127.0.0.11，它干两件事：一是服务发现，让容器能用容器名、服务名互相解析到对方的容器 IP；二是把解析不了的外部域名转发给上游 DNS（默认跟随宿主机的 resolv.conf 配置）。&lt;/p&gt;
&lt;p&gt;所以容器里域名解析慢，要先分清是哪一段慢：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 在容器里分别测：解析同伴容器名（走服务发现）
docker exec &amp;lt;容器名&amp;gt; getent hosts &amp;lt;同伴容器名&amp;gt;
# 解析外部域名（走 127.0.0.11 转发到上游）
time docker exec &amp;lt;容器名&amp;gt; nslookup registry-1.docker.io
# 同一个外部域名，在宿主机上测一遍做对比
time nslookup registry-1.docker.io
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;判断口径很直接：如果容器名解析就慢，问题在 Docker 内置 DNS 或网络本身；如果容器名快、外部域名慢、且宿主机上测同一个域名也慢，那是上游 DNS 的问题，容器只是背锅——去换 resolv.conf 里的上游或者给 Docker 指定 DNS。如果宿主机快、只有容器慢，才需要盯 127.0.0.11 这条转发路径继续深挖。&lt;/p&gt;
&lt;p&gt;给单个容器或整个 daemon 指定 DNS 的方法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d --dns 223.5.5.5 --dns 1.1.1.1 &amp;lt;镜像&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;dns&quot;: [&quot;223.5.5.5&quot;, &quot;1.1.1.1&quot;]
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;一个容易忽略的细节：如果宿主机的 resolv.conf 指向 127.0.0.53 这类本机 stub 解析器（systemd-resolved），Docker 会自动改用其他上游并打一条警告日志，这时容器里用的 DNS 可能和你以为的不一样，排查时先 &lt;code&gt;docker logs&lt;/code&gt; 看有没有这条警告，再看容器内的 /etc/resolv.conf 确认实际配置，别凭宿主机配置文件想当然。&lt;/p&gt;
&lt;h2&gt;macvlan/ipvlan：绕开网桥的另一条路&lt;/h2&gt;
&lt;p&gt;除了 host，还有一种「绕开转发层」的思路：macvlan/ipvlan。它让容器直接拿到一个局域网里的真实 IP，像一台独立设备一样挂在物理网络上，流量不走 docker0 网桥、不用 NAT，性能接近原生，同时又保留了独立的网络命名空间，比 host 模式体面。适合需要给容器分配局域网固定 IP、或者对 NAT 有洁癖的场景。&lt;/p&gt;
&lt;p&gt;代价一句带过：出于安全设计，宿主机与 macvlan 容器默认不互通，要互访得在宿主机侧再配一个 macvlan 接口专门打通——这一步配置不难但容易漏，第一次用时先把这条记在心里。选型细节在 &lt;a href=&quot;/posts/docker-network/&quot;&gt;《Docker 网络详解：从 bridge 到 IPv6》&lt;/a&gt; 里有完整展开，这篇只给它一个定位：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;它是 bridge 和 host 之间的一档：接近原生的性能，保留命名空间隔离，代价是组网复杂度&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;顺带说一句 IPv6 的性能相关点：启用 IPv6 时本站定版用 ULA 段 &lt;code&gt;fdb::/64&lt;/code&gt; 做 fixed-cidr-v6，好处是地址段私有、不与公网段冲突，路由表干净，不会因为地址规划撞车出现莫名其妙的绕路。开启方法同样在网络详解篇里，这篇不重复。&lt;/p&gt;
&lt;h2&gt;iperf3 实测：优化有没有用，数字说了算&lt;/h2&gt;
&lt;p&gt;前面所有优化，都不该凭感觉验收。网络性能的实测工具就用 iperf3，一端起服务端、一端当客户端，测出来的就是纯粹的网络吞吐，不掺业务代码的因素。对比测三组：宿主机直连（基准线）、bridge + 端口发布（默认路径）、host 模式（优化上限），差距一目了然。&lt;/p&gt;
&lt;p&gt;服务端用容器起一个（测 bridge 路径时它就跑在 bridge 网络里）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d --name iperf-s -p 5201:5201 networkstatic/iperf3 -s
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;客户端在另一台机器（或同机另一容器）上打：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run --rm networkstatic/iperf3 -c &amp;lt;服务端地址&amp;gt; -P 4 -t 20
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个参数：&lt;code&gt;-P 4&lt;/code&gt; 是开 4 条并行流，单流测不满万兆/千兆时用它把带宽吃干；&lt;code&gt;-t 20&lt;/code&gt; 测 20 秒，时间太短数字不稳。测 host 模式时，把服务端换成 &lt;code&gt;--network host&lt;/code&gt; 再跑一遍同样的命令即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d --name iperf-h --network host networkstatic/iperf3 -s
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;看数字的方法：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;看什么&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;sender / receiver 的 Bitrate 平均值&lt;/td&gt;
&lt;td&gt;这就是吞吐，两组模式对比它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Retr（重传）列&lt;/td&gt;
&lt;td&gt;数字大说明链路在丢包，吞吐再高也不健康，先查 MTU 和物理链路&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;多轮结果的波动&lt;/td&gt;
&lt;td&gt;每组至少跑 3 轮取中位数，单轮数字容易受瞬时负载干扰&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;如果 bridge 模式和 host 模式测出来差距在个位数百分比，那你的瓶颈根本不在转发层，别再折腾网络模式了，去看 CPU、磁盘和业务本身；如果差出 30% 以上，转发层的优化就是实打实的收益。具体能差多少&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;以你机器实测为准&amp;lt;/span&amp;gt;——网卡、内核版本、CPU 单核性能都会影响结果，网上的任何数字都只能当参考，不能当验收标准。延迟的测法类似，用 ping 看往返时延在两种模式下的差值，方法一致，就不展开命令了。&lt;/p&gt;
&lt;h2&gt;排障小节&lt;/h2&gt;
&lt;h3&gt;1. 关掉 userland-proxy 后，本机 localhost 访问发布端口异常&lt;/h3&gt;
&lt;p&gt;症状：改完 daemon.json、重启 Docker 后，外部访问正常，但从宿主机本机用 &lt;code&gt;curl 127.0.0.1:8080&lt;/code&gt; 访问发布的端口不通或行为怪异。原因多半是本机回环这条路径之前正是走 docker-proxy 的，关掉之后改由 NAT 环回处理，个别环境的 iptables 规则或 rp_filter 设置会把这条路堵住。排查顺序：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 先看规则在不在
sudo iptables -t nat -L DOCKER -n | head
# 用宿主机网卡 IP 而不是 127.0.0.1 再试一次，能通就坐实是回环路径的问题
curl http://&amp;lt;宿主机网卡IP&amp;gt;:8080
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;临时要恢复旧行为，把 &lt;code&gt;&quot;userland-proxy&quot;&lt;/code&gt; 改回 true 重启 Docker 即可；长期则建议让本机调试走容器名或网卡 IP，别依赖回环发布端口。&lt;/p&gt;
&lt;h3&gt;2. 大文件传输卡死、小请求一切正常&lt;/h3&gt;
&lt;p&gt;这是 MTU 的经典症状，按前面 MTU 小节的顺序走：&lt;code&gt;ping -M do -s&lt;/code&gt; 逐段测出路径真实 MTU → 给出问题的网络加 &lt;code&gt;--opt com.docker.network.driver.mtu&lt;/code&gt; 重建网络 → 复测大包能过、iperf3 重传数归零或明显下降。注意只改容器网络没用的一类情况：如果卡点在宿主机出网的隧道上，宿主机网卡或隧道接口的 MTU 也得一起对齐，两边取更小的那个为准。&lt;/p&gt;
&lt;h3&gt;3. 容器里解析域名明显比宿主机慢&lt;/h3&gt;
&lt;p&gt;按 DNS 小节的方法三分：容器名慢查内置 DNS 与容器网络；外部域名慢且宿主机也慢，是上游 DNS 的问题，换上游或给 daemon 配 &lt;code&gt;&quot;dns&quot;&lt;/code&gt;；只有容器慢、宿主机快，检查容器 /etc/resolv.conf 的实际内容和 Docker 日志里关于 resolv.conf 的警告（宿主机 stub 解析器会被 Docker 自动替换上游）。还有一种隐蔽情况：配了多个 DNS 时第一个不可达，每次解析都要等它超时才轮到第二个，表现就是「每次都慢几秒」——把不可达的那个从配置里删掉立刻见效。&lt;/p&gt;
&lt;h3&gt;4. 开了 host 模式反而起不来：端口被占用&lt;/h3&gt;
&lt;p&gt;host 模式下容器端口即宿主机端口，&lt;code&gt;bind: address already in use&lt;/code&gt; 就是有人先占了——可能是宿主机上另一个进程，也可能是另一个 host 模式的容器。用 &lt;code&gt;ss -tlnp | grep &amp;lt;端口&amp;gt;&lt;/code&gt; 在宿主机上查占用者，再决定改谁的端口。规划上，host 模式的服务要建一份端口清单单独管理，别和映射端口的容器混着记。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Docker 网络性能的账，其实就记在转发路径上：iptables NAT 是主力、成本可控；userland-proxy 是用户态兜底、高并发下最贵，环境允许就关掉（本站定版就是关的）；host 模式一层不走、最快，但隔离和端口的代价必须付清，只给可信且实测卡在网络层的服务用；MTU 是最容易漏查的隐形坑，小请求正常、大响应卡死先查它；DNS 慢要先分清服务发现还是上游解析。最后，所有优化都用 iperf3 对照测一遍再下结论——测出来没差距，就说明瓶颈不在网络，别在这儿继续耗时间。&lt;/p&gt;
</content:encoded></item><item><title>Docker 容器资源与性能调优：内存、CPU 限制与配比实战</title><link>https://www.anexns.cloudns.org/posts/docker-resource-tuning/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-resource-tuning/</guid><description>从半夜 OOM 的惨案讲起：内存四参数辨析、CPU 三种控制方式、pids 与 ulimit、Compose 资源落地写法，以及先观察一周峰值再定 limit 的配比方法。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;凌晨三点，监控报警把你叫醒：某个容器进程没了，服务返回 502。你登上服务器看日志，应用日志干干净净，最后一行还是正常处理请求的记录，进程像是凭空蒸发。再看 &lt;code&gt;dmesg&lt;/code&gt;，一行 &lt;code&gt;Out of memory: Killed process&lt;/code&gt; 躺在那里——容器把内存吃穿，被内核的 OOM Killer 直接处决了。&lt;/p&gt;
&lt;p&gt;更糟的剧本是第二个：容器没被杀，宿主机先死了。内存被一个容器慢慢吃光，内核在全机范围内回收、换页，SSH 都连不进去，所有容器一起陪葬。这两种惨案的根源是同一个：&lt;strong&gt;容器没设资源限制&lt;/strong&gt;。这一篇就把内存、CPU、进程数、文件句柄这四类限制的每个参数讲清楚，再给出在 Compose 里落地的方法和定标的思路。&lt;/p&gt;
&lt;p&gt;关于安全边界（比如容器逃逸、权限收敛）不在本篇范围，那是 &lt;a href=&quot;/posts/docker-security-resources/&quot;&gt;Docker 安全与资源限制&lt;/a&gt; 那篇的主题；本篇只谈性能配比：每个参数是什么意思、设多少合适、设错了会发生什么。&lt;/p&gt;
&lt;h2&gt;资源不设限的三种死法&lt;/h2&gt;
&lt;p&gt;很多人对 Docker 有个误解：以为容器天然就是隔离的、有限的。其实恰恰相反，&lt;strong&gt;默认情况下，一个容器可以使用宿主机的全部内存和全部 CPU&lt;/strong&gt;，和裸跑的进程没有区别。资源隔离是你要主动打开的功能，不设就是没有。不设限的容器通常有三种死法：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一种：容器被 OOM Kill。&lt;/strong&gt; 容器内存用量超过宿主机可用内存，内核 OOM Killer 挑选牺牲品——它按内存占用和 oom_score 挑，往往挑中的就是最能吃的那个，也就是肇事者本人。进程被 SIGKILL，没有优雅退出，没有日志收尾，数据写一半就断。表面看是&quot;应用崩了&quot;，实际是被内核杀了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二种：宿主机被拖死。&lt;/strong&gt; 如果容器里的程序不是猛吃内存，而是缓慢泄漏、或者疯狂触发换页（swap 抖动），内核会把大量时间花在内存回收上，整机负载飙升，所有容器和宿主机进程一起变卡。这种死法最难查：每个容器看起来都&quot;没超限&quot;，但机器就是不行了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三种：CPU 被一个容器吃干。&lt;/strong&gt; 某个容器里跑了个死循环或者编译任务，把多核 CPU 全部占满，其他容器的请求开始排队、超时。没有 CPU 限制时，Linux 的 CFS 调度器只按进程数大致公平分配，一个容器里开几十个线程，就能在争抢中占尽便宜。&lt;/p&gt;
&lt;p&gt;这三种死法对应三类限制：内存限制防前两种，CPU 限制防第三种。再加上进程数和文件句柄两类&quot;防滥用&quot;限制，就是本篇的全部内容。&lt;/p&gt;
&lt;h2&gt;内存四参数辨析&lt;/h2&gt;
&lt;p&gt;内存相关的参数有四个，名字长得像，作用完全不同，先用一张表对齐：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--memory&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器可用内存的硬上限&lt;/td&gt;
&lt;td&gt;硬限制&lt;/td&gt;
&lt;td&gt;超过后容器内进程被 OOM Kill；最小值 6m&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--memory-swap&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;内存 + 交换空间（swap）的总和上限&lt;/td&gt;
&lt;td&gt;硬限制&lt;/td&gt;
&lt;td&gt;需先设 &lt;code&gt;--memory&lt;/code&gt; 才有意义；设为 -1 表示 swap 不限量&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--memory-reservation&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;内存软限制&lt;/td&gt;
&lt;td&gt;软限制&lt;/td&gt;
&lt;td&gt;宿主机内存吃紧时，超过此值的容器优先被回收内存；平时可以超&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--memory-swappiness&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器内存被换出到 swap 的倾向&lt;/td&gt;
&lt;td&gt;调优参数&lt;/td&gt;
&lt;td&gt;取值 0–100，越小越倾向于留在内存里；仅 cgroup v1 或特定条件下生效&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;硬上限：--memory 与 --memory-swap&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;--memory&lt;/code&gt; 是最常用的一个，它决定了容器最多能用多少物理内存：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d --name app \
  --memory 512m \
  --memory-swap 512m \
  myapp:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里有个最容易踩的坑：&lt;code&gt;--memory-swap&lt;/code&gt; 限制的不是 swap 本身的大小，而是&lt;strong&gt;内存加 swap 的总和&lt;/strong&gt;。上面把两个都设成 512m，意思是总和不超过 512m，也就是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;完全不允许用 swap&amp;lt;/span&amp;gt;。如果只设 &lt;code&gt;--memory 512m&lt;/code&gt; 而不设 &lt;code&gt;--memory-swap&lt;/code&gt;，Docker 的默认行为是容器最多能用 512m 内存再加 512m swap，总和是内存限制的两倍——很多人的容器&quot;设了限制还是把机器拖慢&quot;，就是因为多出来的这部分 swap 在疯狂换页。&lt;/p&gt;
&lt;p&gt;几个典型组合：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 组合一：内存 512m，最多再借 256m swap（总和 768m）
docker run -d --memory 512m --memory-swap 768m myapp:latest

# 组合二：内存 1g，禁止使用 swap（总和等于内存）
docker run -d --memory 1g --memory-swap 1g myapp:latest

# 组合三：内存 1g，swap 不限量（-1，谨慎使用）
docker run -d --memory 1g --memory-swap -1 myapp:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;容器内存打满之后的命运是确定的：内核在容器对应的 cgroup 范围内触发 OOM，杀掉容器里的进程（通常是内存占用最高的那个）。这听起来残忍，但这正是我们想要的——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;宁可让肇事容器单独死，也不要让它拖着整台宿主机一起死&amp;lt;/span&amp;gt;。容器死了，重启策略会把它拉起来，监控会报警，影响范围就这一个服务。&lt;/p&gt;
&lt;h3&gt;软限制：--memory-reservation&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;--memory-reservation&lt;/code&gt; 是软限制：平时容器可以用超过这个值的内存，但当宿主机内存开始吃紧、内核需要回收时，超过 reservation 的部分会被优先回收（先换出、再挤压）。它适合用来表达&quot;这个服务平时给它留这么多，闲时可以多用，忙时先让它让路&quot;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d --name cache \
  --memory 2g \
  --memory-reservation 512m \
  redis:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 reservation 必须小于 &lt;code&gt;--memory&lt;/code&gt; 才有意义。另外它在 cgroup v2 下对应的是 &lt;code&gt;memory.low&lt;/code&gt; 语义（尽力保护之外的部分优先回收），行为细节和 v1 略有差别，排障一节会再提到。&lt;/p&gt;
&lt;h3&gt;换页倾向：--memory-swappiness&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;--memory-swappiness&lt;/code&gt; 控制这个容器的内存被换出到 swap 的积极程度，取值 0 到 100，数值越小越倾向于把数据留在内存里、优先回收文件缓存。这个参数只建议在明确知道自己在干什么时调整，一般保持默认即可。它还有个历史包袱：在 cgroup v2 环境下该参数基本不起作用（v2 移除了 per-cgroup 的 swappiness 控制），所以不要指望靠它解决所有版本的换页问题。&lt;/p&gt;
&lt;h3&gt;一条红线：--oom-kill-disable&lt;/h3&gt;
&lt;p&gt;Docker 还有个参数叫 &lt;code&gt;--oom-kill-disable&lt;/code&gt;，作用是禁止内核 OOM Kill 容器里的进程。听起来像&quot;保命符&quot;，实际是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把单点故障升级成整机故障的开关&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;strong&gt;慎用 &lt;code&gt;--oom-kill-disable&lt;/code&gt;&lt;/strong&gt;：容器内存打满又不允许杀进程时，内核只能反复回收、换页直至彻底卡死，容器不死、宿主机先死，其他所有容器跟着陪葬。它只在极特殊场景下才考虑——比如容器内进程自己实现了严格的内存管理、且配合 &lt;code&gt;--memory-swap&lt;/code&gt; 等参数做了完整兜底。99% 的场景下，正确答案是让容器被杀、被重启策略拉起、被监控报警，而不是关掉 OOM Kill。
:::&lt;/p&gt;
&lt;h2&gt;CPU 三种控制方式&lt;/h2&gt;
&lt;p&gt;CPU 的控制思路和内存不同：内存是&quot;用到顶就杀&quot;，CPU 是&quot;按规则分时间片&quot;。Docker 提供三种方式，对应三种管理粒度：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方式&lt;/th&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;适用场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;总量上限&lt;/td&gt;
&lt;td&gt;&lt;code&gt;--cpus&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;最常用：直接说&quot;最多用几个核&quot;，可写小数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;相对权重&lt;/td&gt;
&lt;td&gt;&lt;code&gt;--cpu-shares&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;多个容器争抢时按权重比例分配，默认 1024&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;周期配额&lt;/td&gt;
&lt;td&gt;&lt;code&gt;--cpu-period&lt;/code&gt; / &lt;code&gt;--cpu-quota&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;CFS 底层参数，老式精细控制，现多被 &lt;code&gt;--cpus&lt;/code&gt; 换算替代&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;绑核&lt;/td&gt;
&lt;td&gt;&lt;code&gt;--cpuset-cpus&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;把容器钉在指定核心上，低延迟场景用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;总量上限：--cpus&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;--cpus&lt;/code&gt; 是日常首选，它就是 &lt;code&gt;--cpu-period&lt;/code&gt; 与 &lt;code&gt;--cpu-quota&lt;/code&gt; 的语法糖：&lt;code&gt;--cpus 1.5&lt;/code&gt; 等价于在 100ms 的周期里给 150ms 的配额。可以写小数，含义直观：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 最多用满 2 个核
docker run -d --name worker --cpus 2 myapp:latest

# 最多用半个核，适合后台小任务
docker run -d --name agent --cpus 0.5 myapp:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;--cpus&lt;/code&gt; 是上限不是预留：容器闲的时候不占用，忙的时候最多用到这个数。它不会&quot;保证&quot;容器一定能分到这么多——如果宿主机本身超卖严重，实际可用算力还是要靠抢。&lt;/p&gt;
&lt;h3&gt;相对权重：--cpu-shares&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;--cpu-shares&lt;/code&gt; 是相对权重，默认值 1024。它只在 CPU 发生争抢时才起作用：两个容器 shares 分别是 1024 和 512，争抢时按 2:1 分配 CPU 时间。宿主机 CPU 空闲时，设了 shares 的容器照样可以用满所有核心——这是它最反直觉的地方，排障一节还会回来讲。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 核心服务权重拉高，批处理任务权重压低
docker run -d --name api --cpu-shares 2048 myapi:latest
docker run -d --name batch --cpu-shares 256 mybatch:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;shares 是无量纲的相对值，只有同机容器之间的比值有意义，单独看一个数字说明不了任何事。&lt;/p&gt;
&lt;h3&gt;绑核：--cpuset-cpus&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;--cpuset-cpus&lt;/code&gt; 把容器限定在指定的 CPU 核心上运行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 只允许在 0、1 号核心上运行
docker run -d --name rt --cpuset-cpus &quot;0,1&quot; myapp:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;绑核的收益是缓存亲和性和延迟稳定性，代价是灵活性——核心被占满时容器不会溢出到空闲核心上去。一般业务用不上，它属于对延迟极其敏感的场景（实时音视频处理、高频交易类服务）才会考虑的手段，通常还会配合 &lt;code&gt;--cpus&lt;/code&gt; 一起限制总量。&lt;/p&gt;
&lt;h2&gt;进程数与文件句柄：pids 和 ulimit&lt;/h2&gt;
&lt;p&gt;这两类限制平时存在感低，但缺了它们，某些事故会非常难看。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;--pids-limit&lt;/code&gt; 限制容器内能创建的最大进程（线程）数，防的是 fork 炸弹：一旦某个程序失控疯狂 fork，进程数瞬间打满，宿主机的 PID 空间和内存会被迅速耗尽，&lt;code&gt;docker stop&lt;/code&gt; 都可能执行不了。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 最多 200 个进程/线程，绝大多数单体服务绰绰有余
docker run -d --name app --pids-limit 200 myapp:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 Java、Go 这类运行时默认会开不少线程，设之前先用 &lt;code&gt;docker stats&lt;/code&gt; 或 &lt;code&gt;ps&lt;/code&gt; 看一眼实际峰值，别把正常服务卡死。一般 Web 服务设 200–500 是个安全的起点；设为 -1 表示不限制，也就是默认行为。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;--ulimit&lt;/code&gt; 调整容器内进程的资源上限，最常用的是文件句柄数 &lt;code&gt;nofile&lt;/code&gt;。高并发服务（网关、WebSocket 长连接、文件服务）默认的 1024 句柄很容易撞墙，表现是莫名其妙的 &lt;code&gt;too many open files&lt;/code&gt; 报错：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d --name gateway \
  --ulimit nofile=65535:65535 \
  --ulimit nproc=4096:4096 \
  mygateway:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;nofile&lt;/code&gt; 的值写成 &lt;code&gt;软限制:硬限制&lt;/code&gt; 两个数，简单起见可以设成一样。也可以在 &lt;code&gt;/etc/docker/daemon.json&lt;/code&gt; 里用 &lt;code&gt;default-ulimits&lt;/code&gt; 给所有容器统一兜底，免得逐个容器写。&lt;/p&gt;
&lt;h2&gt;cgroup v2 的现状&lt;/h2&gt;
&lt;p&gt;上面所有限制最终都落在 Linux 的 cgroup 上。cgroup 有 v1 和 v2 两个版本，查看当前环境用哪版：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker info | grep -i &quot;cgroup&quot;
# 输出类似： Cgroup Driver: systemd
#           Cgroup Version: 2
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Docker 从 20.10 起支持 cgroup v2，前提是宿主机本身启用了 v2（统一层级）且配合 systemd 的 cgroup 驱动。现在主流发行版的新版本（Debian 12、Ubuntu 22.04 以后等）默认就是 v2。对使用者的影响主要是两点：一是少数 v1 的参数在 v2 下语义变化或失效（前面提到的 &lt;code&gt;--memory-swappiness&lt;/code&gt; 就是例子）；二是查看容器实际用量时，文件路径从 v1 的多个子目录变成了 v2 的统一目录。&lt;/p&gt;
&lt;p&gt;查看某个容器实时的资源用量，最顺手的还是 &lt;code&gt;docker stats&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker stats --no-stream
# CONTAINER ID   NAME    CPU %     MEM USAGE / LIMIT     MEM %    ...
# a1b2c3d4e5f6   app     45.20%    380MiB / 512MiB       74.22%   ...
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;想看 cgroup 层面的原始计数（比如 OOM 次数），可以进 &lt;code&gt;/sys/fs/cgroup&lt;/code&gt; 下对应容器的目录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# cgroup v2 下查看容器的内存事件（oom_kill 计数在这里）
cat /sys/fs/cgroup/system.slice/docker-&amp;lt;容器ID&amp;gt;.scope/memory.events
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;另外 &lt;code&gt;docker inspect&lt;/code&gt; 能把容器的限制配置完整打出来，排查&quot;限制到底生效没有&quot;时先看它：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker inspect app --format &apos;{{json .HostConfig}}&apos; | python3 -m json.tool | grep -i -E &quot;memory|cpu|pids&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;在 Compose 里落地&lt;/h2&gt;
&lt;p&gt;生产环境基本都是 Compose 管理，资源限制写在 &lt;code&gt;deploy.resources&lt;/code&gt; 下。需要先说清一个历史包袱：&lt;code&gt;deploy&lt;/code&gt; 段原本是 Swarm 的语法，但在现在的 Docker Compose（v2）里，&lt;code&gt;resources&lt;/code&gt; 部分的 limits 和 reservations 在普通的 &lt;code&gt;docker compose up&lt;/code&gt; 下同样生效，不需要 Swarm 模式。下面是一个完整的落地示例：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  api:
    image: myapi:latest
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: &quot;2.0&quot;
          memory: 1G
          pids: 300
        reservations:
          cpus: &quot;0.5&quot;
          memory: 256M
    ulimits:
      nofile:
        soft: 65535
        hard: 65535

  worker:
    image: myworker:latest
    restart: unless-stopped
    mem_swappiness: 30
    deploy:
      resources:
        limits:
          cpus: &quot;1.0&quot;
          memory: 512M
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个细节：&lt;code&gt;limits.memory&lt;/code&gt; 对应 &lt;code&gt;--memory&lt;/code&gt;；如果想同时控制 swap 总量，Compose 里用顶层的 &lt;code&gt;memswap_limit&lt;/code&gt; 字段（对应 &lt;code&gt;--memory-swap&lt;/code&gt;）。&lt;code&gt;reservations.memory&lt;/code&gt; 对应 &lt;code&gt;--memory-reservation&lt;/code&gt;。&lt;code&gt;mem_swappiness&lt;/code&gt; 是 Compose 的扩展字段。改完配置后 &lt;code&gt;docker compose up -d&lt;/code&gt; 会按新限制重建容器，验证还是用 &lt;code&gt;docker inspect&lt;/code&gt; 看 HostConfig 是否和文件里写的一致。&lt;/p&gt;
&lt;p&gt;顺带提一句重启策略：上面示例用了 &lt;code&gt;unless-stopped&lt;/code&gt;，它和 &lt;code&gt;always&lt;/code&gt; 的区别是手动停掉的容器在宿主机重启后不会被自动拉起，而 &lt;code&gt;always&lt;/code&gt; 会。这一处点到为止，重启策略与容器生命周期管理的完整话题不在本篇展开。&lt;/p&gt;
&lt;h2&gt;观察与定标：limit 不是拍脑袋填的&lt;/h2&gt;
&lt;p&gt;参数都懂了，最难的问题反而是：数字填多少？填错的两个方向都有代价——填小了容器天天被 OOM Kill，填大了等于没设限，宿主机超卖。所以定标要靠观察，不要靠猜。&lt;/p&gt;
&lt;p&gt;推荐的做法是分两步。第一步，先不设硬限制（或设一个明显宽松的值），让服务正常跑起来，用 &lt;code&gt;docker stats&lt;/code&gt; 持续观察。手动看一眼只能抓到瞬时值，正经做法是把指标接进监控系统长期记录，&lt;a href=&quot;/posts/docker-monitoring-prometheus/&quot;&gt;用 Prometheus 监控 Docker&lt;/a&gt; 那篇讲过完整的采集方案，至少攒一周的数据，覆盖工作日高峰和夜间低谷。&lt;/p&gt;
&lt;p&gt;第二步，按观察到的峰值定标：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;内存 limit&lt;/strong&gt;：取一周峰值的 1.2–1.5 倍。留的余量是给突发流量和内存碎片的，超过这个倍数就说明你的服务内存波动本身不正常，该去查程序而不是放大限制。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;内存 reservation&lt;/strong&gt;：取日常均值略高一点即可，它决定的是&quot;内存紧张时谁先被回收&quot;，按常态占用定。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CPU limit&lt;/strong&gt;：按业务能接受的延迟反推。高峰时段 CPU 长期顶在 limit 上，说明不是限制的问题，是容量的问题，该加副本或升配置。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这里有个反直觉的结论要说清：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;limit 不是越大越安全&amp;lt;/span&amp;gt;。把每个容器的内存 limit 都设成宿主机总量，看起来谁都不会被杀，实际上等于把 OOM 的决策权还给了内核的全局挑选——真出事时，被杀的可能不是肇事者，而是隔壁无辜的大内存服务。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;限制的本质是提前决定好&quot;谁先死&quot;&amp;lt;/span&amp;gt;，把这个决定权握在自己手里，而不是留给内核临场发挥。&lt;/p&gt;
&lt;p&gt;另外，调完限制后要回看一眼监控：被限流（CPU throttling）和 OOM 次数都是应该长期盯着的指标。cgroup v2 下 CPU 限流次数在容器的 &lt;code&gt;cpu.stat&lt;/code&gt; 里（&lt;code&gt;nr_throttled&lt;/code&gt; 字段），这个数持续增长说明 CPU limit 卡得太紧，服务在被&quot;掐脖子&quot;，要么放宽，要么扩容。&lt;/p&gt;
&lt;h2&gt;排障小节&lt;/h2&gt;
&lt;h3&gt;设了 --cpu-shares，感觉完全没生效&lt;/h3&gt;
&lt;p&gt;先别怀疑参数写错了，大概率是预期错了：&lt;code&gt;--cpu-shares&lt;/code&gt; &amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;只在 CPU 争抢时才分配权重&amp;lt;/span&amp;gt;，宿主机 CPU 没跑满时，所有容器都能用满空闲算力，权重再低也不会被限速。验证方法：把宿主机 CPU 人为压满（比如同时跑几个压测容器），再看各容器的实际 CPU 占用比例是否接近 shares 的比值。如果你想要的是&quot;无论如何最多用 X 个核&quot;，该用的是 &lt;code&gt;--cpus&lt;/code&gt;，不是 shares。&lt;/p&gt;
&lt;h3&gt;容器频繁 OOM：limit 太小还是程序内存泄漏？&lt;/h3&gt;
&lt;p&gt;这是最常见的灵魂拷问。区分方法看曲线形状：把容器的内存用量按时间画出来（监控系统里看一周曲线），如果是&lt;strong&gt;锯齿形&lt;/strong&gt;——涨上去、被杀、重启、再涨上去，且每次涨满的周期差不多——那基本是泄漏或无节制的缓存增长，放大 limit 只是把被杀的周期拉长，不解决问题。如果是&lt;strong&gt;台阶形&lt;/strong&gt;——某次发版或流量上涨后稳定地贴在 limit 附近，偶尔尖峰被杀——那是 limit 定小了，按定标方法重新观察峰值后上调。同时结合 &lt;code&gt;memory.events&lt;/code&gt; 里的 &lt;code&gt;oom_kill&lt;/code&gt; 计数确认确实是内存杀，不要把应用自己崩溃误判成 OOM。&lt;/p&gt;
&lt;h3&gt;同一套参数，在 cgroup v1 和 v2 的机器上行为不一样&lt;/h3&gt;
&lt;p&gt;确实会不一样，这是已知差异而不是你的错觉。典型例子：&lt;code&gt;--memory-swappiness&lt;/code&gt; 在 v2 下不起作用；&lt;code&gt;--memory-reservation&lt;/code&gt; 在 v1 对应 &lt;code&gt;memory.soft_limit_in_bytes&lt;/code&gt;、v2 对应 &lt;code&gt;memory.low&lt;/code&gt;，回收语义有细微差别；查看用量的路径也不同（v1 分散在各子系统的目录，v2 是统一目录）。排查跨机器不一致问题时，第一步永远是 &lt;code&gt;docker info&lt;/code&gt; 确认两边的 Cgroup Version 和驱动是否一致，再谈参数。长期方案是把舰队内的宿主机发行版和 Docker 版本尽量统一，混版本运行迟早要在这种细节上交学费。&lt;/p&gt;
&lt;h3&gt;改了 Compose 的资源配置，容器却没变化&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;docker compose up -d&lt;/code&gt; 对未变更的服务不会重建，而资源限制属于需要重建才生效的配置。如果确认文件改对了却没生效，先 &lt;code&gt;docker inspect&lt;/code&gt; 看 HostConfig 里的实际值，再试 &lt;code&gt;docker compose up -d --force-recreate &amp;lt;服务名&amp;gt;&lt;/code&gt; 强制重建一次。另外注意一个坑：如果你用的是老版本 Compose 或某些第三方编排工具，&lt;code&gt;deploy.resources&lt;/code&gt; 可能被直接忽略，这时要退回到在 &lt;code&gt;docker run&lt;/code&gt; 参数或 Compose 的 &lt;code&gt;mem_limit&lt;/code&gt;、&lt;code&gt;cpus&lt;/code&gt; 等顶层兼容字段上写限制。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;容器资源调优的全部要领，可以收成三句话。第一，默认无限制等于把宿主机的命运交给运气，内存和 CPU 的硬上限是每个生产容器的必修课。第二，参数分清硬软：内存看 &lt;code&gt;--memory&lt;/code&gt; 与 &lt;code&gt;--memory-swap&lt;/code&gt; 的总和关系，CPU 用 &lt;code&gt;--cpus&lt;/code&gt; 定总量、&lt;code&gt;--cpu-shares&lt;/code&gt; 只管争抢时的比例，&lt;code&gt;--pids-limit&lt;/code&gt; 和 &lt;code&gt;--ulimit&lt;/code&gt; 补上防滥用的短板。第三，数字靠观察不靠猜：先跑一周拿到峰值曲线，再按倍数定标，并把 OOM 次数和 CPU 限流纳入长期监控——限制不是设完就结束的，它和 &lt;a href=&quot;/posts/docker-compose-advanced/&quot;&gt;Compose 进阶用法&lt;/a&gt; 里的编排配置一样，是需要随业务增长反复回看的东西。&lt;/p&gt;
</content:encoded></item><item><title>BBR 深度长文：从 v1 的带宽建模到 BBRv3 的十年演进</title><link>https://www.anexns.cloudns.org/posts/linux-bbr-deep-dive/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-bbr-deep-dive/</guid><description>一篇把 BBR 讲透的长文：v1 如何用 BtlBw 与 RTprop 显式建模、四状态机如何运转、它对丢包型算法的不公平从何而来，v2 与 v3 又如何逐代修正，以及 BBRv3 至今未进主线内核的真实状态与部署路径。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;先说清这篇的定位。站内 &lt;a href=&quot;/posts/linux-kernel-tuning/&quot;&gt;Linux 内核调优&lt;/a&gt; 那篇末尾有一节 BBR，只讲「是什么、怎么开」，够日常用；这篇是它的完全展开版：把 BBR 从 2016 年的论文一路讲到 2023 年发布的 BBRv3——模型怎么建、状态机怎么转、每一代改了什么、为什么改、改完还剩什么问题，以及最关键的一条事实核对：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;BBRv3 至今没有进入 Linux 主线内核，你在任何发行版里开的 &lt;code&gt;bbr&lt;/code&gt;，都是 2016 年的 v1。&lt;/strong&gt;&amp;lt;/span&amp;gt;全文的版本参数与状态结论均以 Google 的 google/bbr 仓库、IETF 会议材料与草案、以及独立学术评测为准，不采信二手博客的转述。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/google/bbr&lt;/p&gt;
&lt;h2&gt;一、背景：丢包型拥塞控制的困境&lt;/h2&gt;
&lt;p&gt;要理解 BBR 为什么出现，先要理解它要替代的东西有什么毛病。&lt;/p&gt;
&lt;p&gt;以 CUBIC、Reno 为代表的传统拥塞控制算法，核心信号只有一个：&lt;strong&gt;丢包&lt;/strong&gt;。它们的逻辑是不断加大发送窗口，直到网络开始丢包，就认为「满了」，退一步再继续试探。这套逻辑在浅缓冲的年代工作得不错，但它有一个结构性缺陷：丢包发生时，瓶颈链路的缓冲区往往已经被填满。也就是说，这类算法的稳态工作点，恰恰是「队列排满、延迟最高」的那一点。缓冲区越大，排队延迟越夸张，这就是后来被称为 bufferbloat（缓冲膨胀）的现象：带宽明明跑满了，延迟却难看得像网络在堵车。&lt;/p&gt;
&lt;p&gt;更麻烦的是反面：链路上只要有非拥塞原因的丢包——无线干扰、跨境链路的随机损耗——丢包型算法都会误判为拥塞而降速。在高带宽、高时延的长肥管道上，CUBIC 的窗口增长又偏慢，一次降速之后要爬很久才能重新填满管道。结果就是很多海外 VPS 用户熟悉的画面：带宽标称很大，单线程下载却跑不满，延迟还忽高忽低。&lt;/p&gt;
&lt;p&gt;Google 的判断是：问题出在信号本身。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;丢包是拥塞的结果，不是拥塞的度量；真正该测的，是瓶颈链路的带宽和传播时延本身。&lt;/strong&gt;&amp;lt;/span&amp;gt;BBR（Bottleneck Bandwidth and Round-trip propagation time）就是按这个思路设计的：不看丢包，直接建模。&lt;/p&gt;
&lt;h2&gt;二、BBRv1：把瓶颈链路建成两个数&lt;/h2&gt;
&lt;p&gt;2016 年 10 月，Neal Cardwell 等人在 ACM Queue 发表《BBR: Congestion-Based Congestion Control》（2017 年 2 月在 Communications of the ACM 重刊）。BBR 的全部精巧，都建立在两个估计量上：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;BtlBw（瓶颈带宽）&lt;/strong&gt;：数据包交付速率的最大值滤波，取最近 10 个 RTT 内的最大交付速率，代表「这条路径最快能送多快」；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;RTprop（往返传播时延）&lt;/strong&gt;：RTT 的最小值滤波，取最近 10 秒窗口内的最小 RTT，代表「路径上没有排队时，一来一回要多久」。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;两者相乘，就是这条路径的 BDP（带宽时延积）——管道里同时能容纳多少在途数据。BBR 的两个控制量直接由模型给出：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pacing_rate = pacing_gain × BtlBw        发送速率：按瓶颈带宽匀速发包
cwnd        = cwnd_gain × BDP            窗口上限：在途数据不超过管道容量的倍数
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意第一个式子：BBR 不是「有窗口就一口气把包全扔出去」，而是按 pacing_rate &lt;strong&gt;匀速&lt;/strong&gt;发包（pacing）。这一点后面讲 fq 时还会回来。&lt;/p&gt;
&lt;h3&gt;四个状态：BBR 的一生&lt;/h3&gt;
&lt;p&gt;BBR 用一个四状态机在这两个估计量周围运转：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;状态&lt;/th&gt;
&lt;th&gt;在干什么&lt;/th&gt;
&lt;th&gt;关键参数&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Startup&lt;/td&gt;
&lt;td&gt;指数加速探带宽&lt;/td&gt;
&lt;td&gt;pacing/cwnd 增益约 2.885（即 2/ln2，速率每 RTT 翻倍）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Drain&lt;/td&gt;
&lt;td&gt;排空 Startup 冲过头排起的队&lt;/td&gt;
&lt;td&gt;增益约 0.35（2.885 的倒数），持续约 1 个 RTT&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ProbeBW&lt;/td&gt;
&lt;td&gt;稳态运行，周期性上下探测带宽&lt;/td&gt;
&lt;td&gt;8 段增益循环，见下文&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ProbeRTT&lt;/td&gt;
&lt;td&gt;周期性让出管道，重测 RTprop&lt;/td&gt;
&lt;td&gt;窗口砍到 4 个包，至少维持 200 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;Startup&lt;/strong&gt;：连接刚建立时 BBR 对路径一无所知，于是以每 RTT 翻倍的速度往上冲，直到交付速率连续 3 个 RTT 增长不足 25%——说明撞到了瓶颈带宽的平台期——才退出。这个退出条件是「速率不再增长」，不是「开始丢包」，这是 BBR 与慢启动最本质的区别。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Drain&lt;/strong&gt;：翻倍冲刺必然冲过头，多发的数据在瓶颈处排成队。Drain 用约 0.35 的增益发一个 RTT，把队列排空，让管道回到「刚好装满、没有积压」的工作点。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;ProbeBW&lt;/strong&gt;：稳态。BBR 大部分时间停在这里，用一段 8 步的增益循环轻轻推拉：&lt;code&gt;[1.25, 0.75, 1, 1, 1, 1, 1, 1]&lt;/code&gt;，每步持续 1 个 RTprop。先用 1.25 倍速探一步（看带宽有没有变大），再用 0.75 倍速退一步（把探出来的队列排掉），其余 6 步以模型速率平稳巡航。整个循环下来净探测为零，但带宽一有变化就能跟上。此状态的 cwnd_gain 固定为 2，即在途数据上限是 &lt;strong&gt;2 倍 BDP&lt;/strong&gt;——记住这个 2，它是后面所有公平性争议的源头。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;ProbeRTT&lt;/strong&gt;：RTprop 是最小值滤波，如果 10 秒内没测到更小的 RTT，旧值可能已经过期（比如路径变了）。BBR 每约 10 秒进入一次 ProbeRTT，把窗口砍到只剩 4 个包、维持至少 200 ms，人为制造一个「管道近乎空载」的瞬间来重新测量纯传播时延，测完回到 ProbeBW。&lt;/p&gt;
&lt;h2&gt;三、进入主线，以及 pacing 与 fq 的真实关系&lt;/h2&gt;
&lt;p&gt;BBR 于 2016 年 9 月提交 netdev 邮件列表，随 &lt;strong&gt;Linux 4.9&lt;/strong&gt; 进入主线，模块名 &lt;code&gt;tcp_bbr&lt;/code&gt;，配置项 &lt;code&gt;CONFIG_TCP_CONG_BBR&lt;/code&gt;。Google 同步把它部署到了 google.com、YouTube 与 Google Cloud Platform 的流量上。此后近十年，主线里的 BBR 就是这一个版本——后面讲 v2、v3 时请记住：&lt;strong&gt;它们从未替换过主线里的这一份。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;关于 fq，有一段流传极广的说法需要纠正：很多人以为「BBR 必须配 fq 队列调度」。历史真相是：BBR 依赖 pacing 匀速发包，而早期内核里 pacing 只能由 fq qdisc 提供，所以那个年代 fq 确实是硬性要求。但 TCP 层内置 pacing 在 4.13-rc1 就已加入，4.20 的一处修复之后才对 BBR 真正可用——&lt;strong&gt;此后 fq 不再是严格必需&lt;/strong&gt;。Google 官方快速开始文档的现行口径是：高负载服务器上仍建议用 fq，效果更好。站内调优篇里「fq 与 BBR 成对出现」的写法，作为稳妥的部署习惯没有问题，但把它说成硬性前提是不准确的。&lt;/p&gt;
&lt;h2&gt;四、v1 的三个硬伤&lt;/h2&gt;
&lt;p&gt;BBRv1 在 Google 自家可控的环境里表现优异，但放到公共互联网上与全世界的 CUBIC 流竞争，三个问题逐渐暴露，它们正是 v2、v3 存在的全部理由。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一，对丢包完全无感知。&lt;/strong&gt; v1 的模型里只有带宽与时延，没有给丢包留位置。Google 在 IETF 104 的报告里直言：当瓶颈队列小于约 1.5 倍 BDP 时，v1 会打出很高的丢包率——它探带宽的方式是把管道灌到溢出，而浅缓冲的瓶颈装不下这种灌法。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二，对 ECN 无感知。&lt;/strong&gt; 显式拥塞通知（ECN）本可以让路由器在丢包之前就发出「要堵了」的信号，v1 对这个信号视而不见。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三，也是最受诟病的：对丢包型算法不公平。&lt;/strong&gt; 稳态时 2 倍 BDP 的在途上限意味着，BBR 流会在瓶颈队列里常驻一份可观的排队数据；CUBIC 流一丢包就退让，BBR 却不为丢包所动，此消彼长之下 BBR 会抢占远超其份额的带宽。浅缓冲场景下这个效应最严重。此外，不同意流之间还存在 RTT 公平性问题：RTprop 测得偏大的流，其 BDP 估计更大、窗口更大，会在竞争中占便宜。&lt;/p&gt;
&lt;p&gt;这三条里，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;最危险的是把 v1 的不公平误读成「BBR 速度快」&lt;/strong&gt;&amp;lt;/span&amp;gt;：在与他人的 CUBIC 流共享瓶颈的链路上，v1 的一部分「快」，是靠不退让从别人嘴里抢来的。在自家服务器独占的链路上这无所谓，在共享出口、公司网络这类环境里，它会真实地挤压其他人的流量。&lt;/p&gt;
&lt;h2&gt;五、BBRv2：把拥塞信号请回来&lt;/h2&gt;
&lt;p&gt;2019 年 3 月，Google 在 IETF 104 正式报告 BBR v2，同年 7 月在 IETF 105 给出 alpha 代码。v2 的设计哲学是承认 v1 的教训：&lt;strong&gt;纯模型不够，丢包与 ECN 这些拥塞信号必须重新进入决策&lt;/strong&gt;，但要以受控的方式进入，而不是退回丢包型的老路。&lt;/p&gt;
&lt;p&gt;主要改动有六处：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;1. 丢包有了明确的上限目标。&lt;/strong&gt; v2 设定 LossThresh = 2%：每个 RTT 内若丢包率超过 2%，就下调一个叫 &lt;code&gt;inflight_hi&lt;/code&gt; 的上限——即「上次出现过量丢包时的在途量」，此后在途数据不许再超过它。丢包第一次从「忽略」变成了「硬约束」。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. ECN 被纳入响应。&lt;/strong&gt; v2 支持 DCTCP 风格的 ECN 以及 RFC 3168 ECN，按标记率控制队列长度，在丢包发生之前就开始收敛。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 模型从一组界变成长短期两组界。&lt;/strong&gt; v2 同时维护 &lt;code&gt;{bw, inflight}_hi&lt;/code&gt;（长期界：拥塞信号出现之前观测到的最大值）与 &lt;code&gt;{bw, inflight}_lo&lt;/code&gt;（短期界：按最新丢包/ECN 信号下调后的值）。在途目标取 BDP 与 inflight_hi 的约束结果，还要再留出一份 headroom（余量）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 主动留余量给其他流。&lt;/strong&gt; 稳态巡航（Cruise）阶段，v2 刻意维持 &lt;code&gt;inflight ≤ (1 − headroom) × inflight_hi&lt;/code&gt;，headroom 取 0.15——主动空出约 15%，就是为了与 CUBIC、Reno 和平共处。这是针对 v1 公平性问题最直接的回应。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. ProbeBW 拆成四个子阶段。&lt;/strong&gt; v1 那套固定的 8 段增益循环被废弃，改为 Down（退让排队）→ Cruise（巡航）→ Refill（补回在途）→ Up（上探带宽）的自适应节奏，探测间隔也改为随机化的数秒量级，不再机械地按 RTT 拍点。带宽估计的窗口也变了：不再取最近 10 个 RTT 的最大值，而是取最近 2 次带宽探测尝试中的最大值，反应更快、也更不容易被旧样本拖住。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;6. ProbeRTT 温和化，Startup 也听丢包的话。&lt;/strong&gt; ProbeRTT 不再把窗口砍到 4 个包，而是只降到 BDP 的 50%，周期从 10 秒缩短到 5 秒——重测时延的代价小了很多。Startup 的退出条件也增加了拥塞版本：丢包或 ECN 标记率达到 2% 阈值，同样提前退出加速。&lt;/p&gt;
&lt;p&gt;但 v2 有一个决定其命运的事实：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;它从未进入任何受支持的主线内核版本。&lt;/strong&gt;&amp;lt;/span&amp;gt;它只存在于 Google 的补丁集、内核分支，以及 QUIC 实现（google/quiche 里的 bbr2_sender）中。普通用户在发行版里永远没有见过它——这也是为什么市面上大量「BBRv2 一键脚本」基本都是误解或误导：它们装的要么还是主线 v1，要么是来路不明的树外内核。&lt;/p&gt;
&lt;h2&gt;六、BBRv3：小步修复，公网验证&lt;/h2&gt;
&lt;p&gt;2023 年 7 月 26 日，IETF 117（旧金山），Google 报告《BBRv3: Algorithm Bug Fixes and Public Internet Deployment》，正式把版本升到 v3 并开源其 Linux TCP 实现。Google 对 v3 的自我定性非常克制，值得原样转述：&lt;strong&gt;BBRv3 = BBRv2 + 算法 bug 修复与性能调优&lt;/strong&gt;。不是重写，是在 v2 的框架上修问题。Google 还特意提醒：v2 的多数测试结果不适用于 v3——升版的主因正是两个带宽收敛 bug：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;有丢包/ECN 标记时&lt;/strong&gt;，v2 的带宽估计收敛有问题；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;无丢包/ECN 时&lt;/strong&gt;，带宽估计同样存在收敛问题。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;两个方向的收敛都修过之后，估计器在「该跟上时跟得上、该收手时收得住」上才达到 Google 愿意推上公网的程度。除此之外还有一处醒目的参数调整：&lt;strong&gt;Startup 的 cwnd 增益由 2.89 降到 2.0&lt;/strong&gt;（Google 称有解析推导支撑），慢启动式的冲刺明显收敛，对短连接占多数的 Web 流量更友好；Startup 因丢包退出所需的丢包轮次阈值，也由 v2 的 8 轮降到 6 轮，反应更快。v2 引入的 LossThresh = 2% 与 ECN 响应机制则完整保留。现行草案（draft-ietf-ccwg-bbr-06）还写入了一个叫 Precautionary Bandwidth Probing（预防性带宽探测）的机制：一次上探若打出过量丢包，下次上探只探到长期安全上限就先停下排空队列再继续——据 IETF 126 会议纪要，这个机制自 2019 年起就已经在开源的 Linux BBRv3 代码里运行。&lt;/p&gt;
&lt;p&gt;部署口径（2023 年 7 月，Google 在 IETF 117 的原文）：BBRv3 当时已是 &lt;strong&gt;Google 全部内部 WAN 流量的 TCP 拥塞控制&lt;/strong&gt;，并且覆盖 &lt;strong&gt;google.com 的全部公网流量&lt;/strong&gt;；YouTube 的 TCP 以及 YouTube/Google 的 QUIC 正在做 BBRv3 的 A/B 测试。换句话说，v3 不是实验室玩具，它在 Google 自己的网络上经过了真实规模验证——只是这个验证发生在 Google 的树外内核里。&lt;/p&gt;
&lt;h3&gt;代码在哪，基于什么内核&lt;/h3&gt;
&lt;p&gt;BBRv3 的 Linux 实现放在 google/bbr 仓库的 &lt;code&gt;v3&lt;/code&gt; 分支，形态是&lt;strong&gt;一整棵 Linux 内核树&lt;/strong&gt;（不是一个可以随手打在任意内核上的小补丁）。该分支顶层 Makefile 显示其当前基线为 &lt;strong&gt;Linux 6.13.7&lt;/strong&gt;，历史上这个分支会随时间 rebase 到更新的内核。Google 在该分支 README 里对这份发布的定位是「intended to enable research collaboration and wider testing」——供研究协作与更广泛的测试。这个定位要读懂：它是官方代码，但官方没把它定位成「给生产服务器的一键升级包」。&lt;/p&gt;
&lt;p&gt;v3 还附带了两样周边：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;iproute2 补丁&lt;/strong&gt;：给 &lt;code&gt;ss&lt;/code&gt; 命令增加 BBRv3 的诊断输出字段。不打这个补丁，你在 v3 内核上看到的 &lt;code&gt;ss&lt;/code&gt; 输出是不完整的；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;路由级特性 &lt;code&gt;ecn_low&lt;/code&gt;&lt;/strong&gt;：通过 &lt;code&gt;ip route&lt;/code&gt; 给某条路由声明「对端是 DCTCP/L4S 式的低时延 ECN 环境」，BBRv3 会据此换一套方式解读 ECN 信号。官方给的启用示例是先开 &lt;code&gt;net.ipv4.tcp_ecn=1&lt;/code&gt;，再给路由加 &lt;code&gt;features ecn_low&lt;/code&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;七、标准化进程与主线状态：截至 2026 年 11 月&lt;/h2&gt;
&lt;p&gt;这一节是全篇最需要说准的地方，因为中文互联网上流传着大量「BBRv3 已经合并主线」的错误说法。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;标准化这边在稳步走。&lt;/strong&gt; BBR 的规范文本最初是 ICCRG 的个人草案（draft-cardwell-iccrg-bbr-congestion-control）。2024 年 7 月 IETF 120，它以 draft-cardwell-ccwg-bbr-00 的形式进入拥塞控制工作组（CCWG）视野；2024 年 10 月被 CCWG 正式采纳为工作组条目，更名 &lt;strong&gt;draft-ietf-ccwg-bbr&lt;/strong&gt;，编辑为 Neal Cardwell、Ian Swett（Google）与 Joseph Beshay（Meta），目标状态是 Experimental RFC。截至本文写作，最新修订为 &lt;strong&gt;-06&lt;/strong&gt;（2026 年 7 月，IETF 126 仍在讨论）——还不是 RFC，也还没有送 IESG 审批。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;主线这边则一直没动。&lt;/strong&gt; 证据链是完整的：IETF 117 上 Google 曾表示计划在 2023 年 8 月把补丁发到 netdev 提议纳入主线；2025 年 3 月，Neal Cardwell 本人在 bbr-dev 邮件列表里回复确认：net-next 与主线「still have BBR 1.x」；2026 年 10 月的独立深度分析复核主线 &lt;code&gt;tcp_bbr.c&lt;/code&gt; 源码，仍是 v1，只有历年累积的增量修复。所以结论再强调一遍：&lt;/p&gt;
&lt;p&gt;:::warning
**截至 2026 年 11 月，Linux 主线内核的 &lt;code&gt;tcp_bbr&lt;/code&gt; 仍然是 BBRv1。**任何宣称「某发行版/某内核版本已经自带 BBRv3」的说法，若非指 XanMod 这类明确集成树外补丁的第三方内核，基本都不可靠。判断版本不能看 sysctl 输出——v1 与 v3 在 &lt;code&gt;net.ipv4.tcp_congestion_control&lt;/code&gt; 里都显示为 &lt;code&gt;bbr&lt;/code&gt;，只能看你的内核来自哪里。
:::&lt;/p&gt;
&lt;p&gt;为什么迟迟不合并，公开材料没有给出单一的官方理由；学术界的一个共识性背景是：与 CUBIC 的公平性争议尚未完全平息（见下一节的独立评测）。把「未合并」归因于某一个具体原因，都属于推测，本文不采。&lt;/p&gt;
&lt;h2&gt;八、三代参数对照&lt;/h2&gt;
&lt;p&gt;把三代放在一张表里，演进的方向一目了然——每一代都在给上一代的「激进」打补丁：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;BBRv1（2016）&lt;/th&gt;
&lt;th&gt;BBRv2（2019）&lt;/th&gt;
&lt;th&gt;BBRv3（2023）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;核心信号&lt;/td&gt;
&lt;td&gt;带宽/时延模型，忽略丢包与 ECN&lt;/td&gt;
&lt;td&gt;模型 + 丢包 + ECN&lt;/td&gt;
&lt;td&gt;同 v2，修带宽收敛 bug&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;丢包处理&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;LossThresh 2%，超限下调 inflight_hi&lt;/td&gt;
&lt;td&gt;保留 2%&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ECN 处理&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;DCTCP 风格 + RFC 3168&lt;/td&gt;
&lt;td&gt;保留，另支持路由级 ecn_low&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Startup 增益&lt;/td&gt;
&lt;td&gt;pacing/cwnd 约 2.885&lt;/td&gt;
&lt;td&gt;增益体系调整，丢包/ECN 达阈值也退出&lt;/td&gt;
&lt;td&gt;cwnd 增益降至 2.0；丢包退出轮次 8 → 6&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;稳态探测&lt;/td&gt;
&lt;td&gt;ProbeBW 固定 8 段增益循环&lt;/td&gt;
&lt;td&gt;Down/Cruise/Refill/Up 四子阶段，自适应节奏&lt;/td&gt;
&lt;td&gt;沿用 v2 框架，加预防性带宽探测&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;在途上限&lt;/td&gt;
&lt;td&gt;2 × BDP（固定）&lt;/td&gt;
&lt;td&gt;受 inflight_hi 约束，Cruise 留 15% headroom&lt;/td&gt;
&lt;td&gt;沿用 v2 约束&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ProbeRTT&lt;/td&gt;
&lt;td&gt;每约 10 秒，窗口砍到 4 个包，≥200 ms&lt;/td&gt;
&lt;td&gt;每 5 秒，只降到 50% BDP&lt;/td&gt;
&lt;td&gt;草案口径：在途降到估计 BDP 的 50%，200 ms，至多每 5 秒一次&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;带宽估计窗口&lt;/td&gt;
&lt;td&gt;最近 10 个 RTT 的最大值&lt;/td&gt;
&lt;td&gt;最近 2 次探测的最大值&lt;/td&gt;
&lt;td&gt;沿用并修收敛问题&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;发布形态&lt;/td&gt;
&lt;td&gt;Linux 4.9 起主线内置&lt;/td&gt;
&lt;td&gt;从未进主线，仅补丁集与 QUIC&lt;/td&gt;
&lt;td&gt;google/bbr v3 分支整棵内核树（基线 6.13.7）；未进主线&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;九、今天在 Linux 上到底怎么用&lt;/h2&gt;
&lt;h3&gt;路径一：主线 v1（绝大多数人应该停在这里）&lt;/h3&gt;
&lt;p&gt;任何 ≥ 4.9 的内核都能直接开，这也是站内调优篇给过的方法，这里补全验证环节：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo modprobe tcp_bbr
sysctl net.ipv4.tcp_available_congestion_control
# 输出里有 bbr 才说明模块可用

sudo tee /etc/sysctl.d/99-bbr.conf &amp;gt; /dev/null &amp;lt;&amp;lt;&apos;EOF&apos;
net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr
EOF
sudo sysctl --system
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;验证连接级的 BBR 状态用 &lt;code&gt;ss -tin&lt;/code&gt;，输出里能看到 &lt;code&gt;bbr&lt;/code&gt; 字样及 &lt;code&gt;bw&lt;/code&gt;、&lt;code&gt;mrtt&lt;/code&gt;、&lt;code&gt;pacing_gain&lt;/code&gt; 等字段——&lt;code&gt;bw&lt;/code&gt; 是当前 BtlBw 估计，&lt;code&gt;mrtt&lt;/code&gt; 是最小 RTT 估计，拿它们和你的链路实测对照，能判断模型有没有测准。注意主线 v1 的 tcp_bbr &lt;strong&gt;没有提供运行时可调的 sysctl 参数&lt;/strong&gt;：增益、循环这些都是 &lt;code&gt;tcp_bbr.c&lt;/code&gt; 里的编译期常量，网上流传的各种「BBR 优化参数」绝大多数并不存在或并不作用于 BBR 本身。v3 的官方文档里同样未见 tcp_bbr 专属 sysctl，它的可调面主要是 &lt;code&gt;net.ipv4.tcp_ecn&lt;/code&gt; 与路由级 &lt;code&gt;ecn_low&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;路径二：真要用 v3，只有两条正经路&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;自编 google/bbr 的 v3 分支内核&lt;/strong&gt;：整棵树拉下来按常规流程编译。代价很明确：你从此运行一棵树外内核，安全更新、驱动兼容、发行版工具链适配都要自己跟，Google 给它的定位也是研究与测试，不是生产升级包；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;用明确集成 BBRv3 的第三方内核&lt;/strong&gt;：目前有明确官方特性列表依据的是 &lt;strong&gt;XanMod&lt;/strong&gt;，其特性/补丁集里明确列有「Google&apos;s BBRv3 TCP congestion control」。其余发行内核是否携带 v3，未经其官方文档证实的不要凭博客文章下单。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;还有一个命名陷阱值得单独提醒：某些第三方（Android 内核圈）的补丁集把 v3 注册成独立算法名 &lt;code&gt;bbr3&lt;/code&gt;（CONFIG_TCP_CONG_BBR3），与 v1 并存、可以分别选用——那是第三方的适配方式，&lt;strong&gt;不是 Google 的发布方式&lt;/strong&gt;。在服务器语境里看到 &lt;code&gt;bbr3&lt;/code&gt; 字样，先问代码出处。&lt;/p&gt;
&lt;p&gt;:::warning
无论走哪条路，先想清楚收益归属：BBR 的收益集中在高时延、有随机丢包的跨境/跨运营商链路（细节见 &lt;a href=&quot;/posts/linux-network-troubleshooting/&quot;&gt;Linux 网络排障&lt;/a&gt; 里对链路质量的判断方法）。同城同运营商的访问，CUBIC 与 BBR 的差距通常感知不到；为了一个拥塞算法把生产机换成树外内核，是把确定性的维护成本换不确定的边际收益，账要算明白。
:::&lt;/p&gt;
&lt;h2&gt;十、公平性争议：独立评测怎么说&lt;/h2&gt;
&lt;p&gt;Google 的材料证明 v3 在自家网络上跑得好，但「与别人的流共处时是否公平」必须看独立评测。2024 年 PAM 会议论文《Promises and Potential of BBRv3》（Zeynali 等）对 v3 做了系统的竞争实验，结论并不客气：**尽管 v3 引入了丢包上限、ECN 响应与留余量机制，在很宽的网络条件范围内，它与 CUBIC 竞争时仍难以做到均等的带宽分享。**这与 v1 时代的批评一脉相承，只是程度减轻。&lt;/p&gt;
&lt;p&gt;这也是看待 BBR 三代演进的正确姿势：v1 证明了「建模优于丢包信号」在吞吐与延迟上的上限；v2、v3 用一代代补丁把共存性往回拉，但直到最新草案，BBR 的工作点仍然系统性偏向「先保证自己的模型速率」，公平性靠约束而非靠机制天然成立。对个人 VPS 用户，这意味着一个朴素的结论：你的链路基本独占时，开 v1 收益明确、风险可控；身处共享瓶颈时，请意识到你开的不只是一个加速开关。&lt;/p&gt;
&lt;p&gt;排障时若要确认 BBR 流到底在干什么，除了 &lt;code&gt;ss -tin&lt;/code&gt;，也可以配合 &lt;a href=&quot;/posts/linux-tcpdump-basics/&quot;&gt;tcpdump 抓包入门&lt;/a&gt; 观察重传与窗口行为，避免只看 sysctl 就下结论。&lt;/p&gt;
&lt;h2&gt;十一、常见问题排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. &lt;code&gt;tcp_available_congestion_control&lt;/code&gt; 里没有 bbr。&lt;/strong&gt; 模块没加载或内核没编。先 &lt;code&gt;sudo modprobe tcp_bbr&lt;/code&gt; 再查；还没有，就是内核配置里没有 CONFIG_TCP_CONG_BBR（多见于极旧内核或深度定制的容器宿主机），不要硬上，更不要为此在生产机上换内核。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 设置写了，重启后失效。&lt;/strong&gt; 八成是多处 sysctl 配置互相覆盖：检查 &lt;code&gt;/etc/sysctl.conf&lt;/code&gt;、&lt;code&gt;/etc/sysctl.d/&lt;/code&gt; 下文件的字典序加载顺序，以及发行版自带的调优服务（如 tuned）有没有把拥塞控制改回去。以 &lt;code&gt;sysctl net.ipv4.tcp_congestion_control&lt;/code&gt; 的实际输出为准，不要以「我写过配置」为准。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 开了 BBR 感觉没变快。&lt;/strong&gt; 先分清瓶颈在不在拥塞控制：用 &lt;a href=&quot;/posts/linux-performance-troubleshooting/&quot;&gt;Linux 性能排障&lt;/a&gt; 的方法确认链路本身的带宽、丢包与 RTT 形态。同城低延迟链路无感是正常现象，不是 BBR 没生效；&lt;code&gt;ss -tin&lt;/code&gt; 里能看到 bbr 与 bw 估计，就说明它在工作。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 怎么确认自己跑的是不是 v3？&lt;/strong&gt; 唯一可靠依据是内核来源：主线与发行版内核 = v1；google/bbr v3 分支自编或 XanMod = v3。sysctl 与 &lt;code&gt;ss&lt;/code&gt; 的算法名都只写 &lt;code&gt;bbr&lt;/code&gt;，区分不了版本。凡是「一键升级 BBRv3」的脚本，先打开看它到底换了什么内核——看不懂，就不要在生产机上跑。&lt;/p&gt;
&lt;h2&gt;十二、小结&lt;/h2&gt;
&lt;p&gt;把十年的线收成几句：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;BBR 的思想贡献是把拥塞控制从「等丢包」改成「测带宽与传播时延」，v1 的四状态机（Startup、Drain、ProbeBW、ProbeRTT）与 BtlBw × RTprop 模型至今仍是主线里的实现；&lt;/li&gt;
&lt;li&gt;v1 的硬伤同样清楚：对丢包与 ECN 无感、2 倍 BDP 的在途量对 CUBIC 不公平，浅缓冲下还会打出高丢包；&lt;/li&gt;
&lt;li&gt;v2 把丢包上限（2%）、ECN 响应、长短期双界与 15% 余量请了回来，ProbeBW 改为四子阶段，但它从未进入主线；&lt;/li&gt;
&lt;li&gt;v3 是 v2 的收敛性修复版：修了带宽估计在丢包与无丢包两种情形下的收敛 bug，Startup 明显收敛（cwnd 增益 2.0），并已在 Google 内部 WAN 与 google.com 公网流量上完成规模验证；规范文本 draft-ietf-ccwg-bbr 已推进到 -06，但&lt;strong&gt;主线内核至今仍是 v1&lt;/strong&gt;；&lt;/li&gt;
&lt;li&gt;落到实操：发行版开 &lt;code&gt;bbr&lt;/code&gt; 就是 v1，够用且稳妥；v3 只存在于 google/bbr 的整棵树外内核与 XanMod 等第三方内核，尝鲜可以，生产慎之。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;拥塞控制是个十年尺度的慢变量。看懂每一代改了什么、为什么改，比追着版本号升级重要得多——这也是这篇长文想留下的东西。&lt;/p&gt;
</content:encoded></item><item><title>监控与可观测性：告警规则设计与降噪——少而准，比多而吵活得久</title><link>https://www.anexns.cloudns.org/posts/monitoring-alert-rules/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-alert-rules/</guid><description>告警规则设计与降噪方法论：先分清 page 与 ticket，按症状优先和四大黄金信号写规则，用 for 防抖、SLO 燃烧率与 P1/P2/P3 分级响应，把半夜被叫醒的次数降下来。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;告警不是越多越安全，恰恰相反&lt;/h2&gt;
&lt;p&gt;很多团队的监控系统是这样长大的：出一次事故，补一条告警；有人随口说一句「这个也监控一下吧」，再补一条。半年之后，值班群里每天几百条消息，红的黄的混在一起，所有人默默把群设成了免打扰——真出事那天晚上，系统照样会发消息，只是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;没有人会再点开看&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;告警的本质是注意力分配。人的注意力有限，每多一条低价值告警，都是在给高价值告警征税。更麻烦的是信任透支：值班的人被虚惊叫醒三次，第四次就会先翻个身再看手机——响应速度是被噪音一点点磨掉的，而不是某一天突然消失的。Google SRE 的经验结论很直接：能把人从床上叫起来的告警应该少到屈指可数，其余的要么变成工单，要么删掉。这一篇不绑单一工具，讲告警规则的设计方法论：哪些事值得叫醒人、规则怎么写才不吵、吵起来了怎么降噪。示例用 Prometheus 的规则语法，通知怎么分发到不同渠道，看本系列的 &lt;a href=&quot;/posts/monitoring-alertmanager/&quot;&gt;Alertmanager 篇&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;参考文档：https://prometheus.io/docs/practices/alerting/&lt;/p&gt;
&lt;h2&gt;第一步：先分清 page 和 ticket&lt;/h2&gt;
&lt;p&gt;所有告警先过一道分流：它是 page，还是 ticket？&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;到达方式&lt;/th&gt;
&lt;th&gt;响应预期&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;page&lt;/td&gt;
&lt;td&gt;正在发生、用户正在受损、必须立刻处理&lt;/td&gt;
&lt;td&gt;电话、短信、强提醒推送&lt;/td&gt;
&lt;td&gt;分钟级响应，立即处理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ticket&lt;/td&gt;
&lt;td&gt;需要处理，但不紧急&lt;/td&gt;
&lt;td&gt;工单、邮件、普通群消息&lt;/td&gt;
&lt;td&gt;上班时间处理即可&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;page 的核心特征是「等到明天早上就来不及了」。磁盘还剩 30%、证书还有 20 天过期、某个批处理任务慢了——这些都重要，但没有一条值得凌晨三点把人叫醒，它们全是 ticket。&lt;/p&gt;
&lt;p&gt;告警疲劳的根源，恰恰是这两类混在一起：ticket 级别的事情走 page 的渠道发，次数多了，人对这个渠道整体脱敏，等真正的 page 来了也被当成噪音划过去。分流做不好，后面所有优化都是白搭。&lt;/p&gt;
&lt;p&gt;遇到拿不准的边界情况，问两个问题：第一，它能不能等到下一个工作日？能，就降级。第二，不处理的话，影响会不会随时间自动扩大？磁盘缓慢写满、错误预算慢慢烧干这类会扩大的，可以留作 ticket 并设好升级条件；既能等又不会扩大的，连 ticket 都可以斟酌。把判断标准写下来，比逐条争论省事得多。&lt;/p&gt;
&lt;h2&gt;告警要盯症状，不要盯原因&lt;/h2&gt;
&lt;p&gt;第二条原则：基于症状告警，而不是基于原因告警。&lt;/p&gt;
&lt;p&gt;症状是用户能感知到的东西：请求报错、页面变慢、下单失败。原因是机器内部的状态：CPU 高、内存涨、某个容器重启了。&lt;/p&gt;
&lt;p&gt;举例说，「接口 5xx 比例超标」是症状——用户正在实实在在地遇到错误，这条该 page。而「某容器 CPU 使用率超过 90%」是原因——它可能只是批处理在正常干活，也可能被自动扩缩容消化掉，用户毫无感知，这条最多配一张 ticket。&lt;/p&gt;
&lt;p&gt;原因型告警还有个毛病：一个症状背后有几十种原因，按原因设告警永远设不全，还特别吵；而症状就那么几个，盯住症状，等于盯住了所有原因的最终汇合点。判断一条告警该不该 page，有个简单标准：如果它触发时你的第一反应是「先看看要不要紧」，那它就不该是 page——page 必须是那种一看就知道「用户正在受损，立刻动手」的。&lt;/p&gt;
&lt;p&gt;这不是说原因指标没用。CPU、内存、连接数这些应该老老实实躺在监控面板上，当症状告警触发、开始排查时，它们是定位根因的第一手材料；也可以在症状告警的注释里附上相关面板的链接，让处理的人一键跳过去看。位置摆对了，原因指标是帮手；摆错了，就是噪音源。&lt;/p&gt;
&lt;h2&gt;四大黄金信号，各配一条告警&lt;/h2&gt;
&lt;p&gt;不知道从哪下手时，就用四大黄金信号打底（概念本身在 &lt;a href=&quot;/posts/monitoring-concepts/&quot;&gt;监控概念篇&lt;/a&gt; 里讲过）：延迟、流量、错误、饱和度。每个面向用户的服务，把这四个信号各配一条告警，基本盘就有了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;错误&lt;/strong&gt;——最典型的症状型告警，盯 5xx 占总请求的比例，而不是绝对次数（绝对次数会随流量涨落乱报）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;groups:
- name: symptom-alerts
  rules:
  - alert: HttpErrorRateHigh
    # 过去 5 分钟内 5xx 占总请求的比例超过 5%
    expr: |
      sum(rate(http_requests_total{status=~&quot;5..&quot;}[5m]))
        / sum(rate(http_requests_total[5m])) &amp;gt; 0.05
    for: 5m        # 持续满 5 分钟才触发，瞬时毛刺不吵人
    labels:
      severity: page
    annotations:
      summary: &quot;接口 5xx 比例已达 {{ $value | humanizePercentage }}，用户正在遇到报错&quot;
      runbook_url: &quot;https://wiki.example.com/runbooks/http-5xx&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;延迟&lt;/strong&gt;——盯分位数而不是平均值，平均值会把长尾抹平。&lt;strong&gt;饱和度&lt;/strong&gt;——别等资源耗尽才报，按消耗速度预测「还有多久用完」：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;  - alert: ApiLatencyP99High
    # p99 延迟超过 1 秒：最慢的那 1% 请求已经明显卡顿
    expr: histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket[5m])) by (le)) &amp;gt; 1
    for: 10m       # 延迟类容易抖动，for 给长一点
    labels:
      severity: page

  - alert: DiskWillFillIn4Hours
    # 按过去 6 小时的消耗速度线性预测，4 小时后磁盘写满
    expr: predict_linear(node_filesystem_avail_bytes[6h], 4 * 3600) &amp;lt; 0
    for: 30m
    labels:
      severity: ticket   # 4 小时后才满，上班处理来得及，只发工单
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;流量&lt;/strong&gt;的告警常常被忽略：请求量骤降到接近零，往往比暴涨更可怕——入口断了、DNS 出问题、上游不往你这儿导流了，错误率反而一片正常（因为根本没请求进来）。给核心入口配一条「流量低于基线下限」的告警，成本很低，兜底价值很高。&lt;/p&gt;
&lt;h2&gt;静态阈值的坑，和 for 的作用&lt;/h2&gt;
&lt;p&gt;阈值最常见的写法是拍一个固定数字：CPU 超过 80%、延迟超过 1 秒。它的坑在于&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;业务涨了，阈值还停在去年&amp;lt;/span&amp;gt;：流量翻倍之后，原本合理的绝对值阈值开始天天误报；或者反过来，服务扩容之后阈值变得永远够不着，形同虚设。对策是能用比例就不用绝对值（错误率、成功率），能用基线对比就不用拍脑袋数字（与上周同期比），实在要用静态阈值的，把它写进季度复盘的检查项里。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;for&lt;/code&gt; 是另一个降噪主力：条件满足后不立刻触发，持续满设定时长才真正发出。它防的是毛刺——GC 停顿、瞬时抖动、发布过程中的短暂异常，这些持续十几秒就自愈的事情不该惊动任何人。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;阈值管「有多严重」，for 管「持续了多久」，两个一起用，告警才稳。&amp;lt;/span&amp;gt;代价也要心里有数：for 设得越长，发现故障越晚。核心链路的 page 一般给 2–5 分钟，延迟、饱和度这类慢变量可以给到 10–30 分钟。&lt;/p&gt;
&lt;p&gt;还有一个配套手法是发布窗口静默：上线、扩缩容、数据迁移这些计划内操作，必然会让一批指标短暂异常。提前在 Alertmanager 里给相关告警设好 silence，比事后在一堆消息里翻找、再逐个解释「这个是发布引起的」要体面得多。静默要设过期时间，过期自动恢复，避免有人忘了取消，把真告警也一起闷掉。&lt;/p&gt;
&lt;h2&gt;进阶：SLO 多窗口多燃烧率告警&lt;/h2&gt;
&lt;p&gt;服务有了明确的 SLO（比如月可用性 99.9%，即每月错误预算约 43 分钟）之后，阈值法可以升级成燃烧率告警。思想不复杂：不看错误率的绝对值，看错误预算的消耗速度。预算正以正常速度 14 倍的速度燃烧，意味着照这个势头两天就把一个月的预算烧光——这是 page；以 2 倍速度慢慢烧，是趋势问题，发 ticket 慢慢查。&lt;/p&gt;
&lt;p&gt;关键在「多窗口」：单一窗口要么太灵敏（毛刺就报），要么太迟钝（发现时预算已烧掉一半）。做法是大小两个窗口同时确认——1 小时窗口看大盘燃烧速度，5 分钟窗口确认此刻还在烧，两个都超标才触发，既快又不误报。慢烧的那一档同理，只是换成长窗口：3 天窗口的燃烧率持续偏高，说明有个慢性问题在偷预算（某个小版本引入的缓慢劣化最常见），发 ticket 慢慢查，但别拖——慢烧烧干预算的速度比想象中快。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;  - alert: ErrorBudgetFastBurn
    # 示意：1 小时与 5 分钟两个窗口的燃烧率同时超标才触发
    expr: |
      (job:slo_errors:ratio_rate1h &amp;gt; (14.4 * 0.001))
      and
      (job:slo_errors:ratio_rate5m &amp;gt; (14.4 * 0.001))
    for: 2m
    labels:
      severity: page
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;适用门槛要说清：这套方法需要先有定义清楚的 SLO、错误预算和足够大的流量（请求太少时比例毫无统计意义）。个人维护的小服务、内部工具，老老实实用黄金信号加阈值就够了，不要为了时髦硬套。&lt;/p&gt;
&lt;h2&gt;严重度分级：P1 / P2 / P3&lt;/h2&gt;
&lt;p&gt;分级不是把 page/ticket 换个名字，而是把「多严重、走什么渠道、多久响应」一次定死，落到规则的 &lt;code&gt;severity&lt;/code&gt; 标签上，再由 Alertmanager 按标签路由：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;级别&lt;/th&gt;
&lt;th&gt;定义&lt;/th&gt;
&lt;th&gt;通知渠道&lt;/th&gt;
&lt;th&gt;响应预期&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;P1&lt;/td&gt;
&lt;td&gt;核心功能不可用，用户大面积受损&lt;/td&gt;
&lt;td&gt;电话＋短信＋值班群强提醒&lt;/td&gt;
&lt;td&gt;5 分钟内响应，立即处理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;P2&lt;/td&gt;
&lt;td&gt;部分功能受损，或不处理会恶化成 P1&lt;/td&gt;
&lt;td&gt;值班群 @值班人＋短信&lt;/td&gt;
&lt;td&gt;30 分钟内响应，当天处理完&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;P3&lt;/td&gt;
&lt;td&gt;隐患、趋势、容量类问题&lt;/td&gt;
&lt;td&gt;工单或邮件&lt;/td&gt;
&lt;td&gt;下个工作日处理&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;分级的大忌是通货膨胀：如果一半告警都是 P1，P1 就等于没有分级。个人维护的几台服务器不必照搬大厂的值班体系，小规模的落地形态可以看本系列的&lt;a href=&quot;/posts/monitoring-fleet/&quot;&gt;舰队监控篇&lt;/a&gt;；自建服务场景的通用告警配置，自建服务系列也有一篇&lt;a href=&quot;/posts/selfhost-monitoring-alerts/&quot;&gt;监控告警篇&lt;/a&gt;可以对照。&lt;/p&gt;
&lt;h2&gt;每条告警的标配四件套&lt;/h2&gt;
&lt;p&gt;一条告警写完，逐项检查有没有这四样：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;可执行&lt;/strong&gt;：接到就能动手处理，而不是「提示你去看看」。看完还要调查半天才知道干什么的，是监控，不是告警。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;runbook 链接&lt;/strong&gt;：处理步骤沉淀成文档，链接写进 annotations。新人接手、半夜迷糊时，照着做就行。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;负责人&lt;/strong&gt;：用标签标明归属的服务或人。群发所有人的告警，等于没有负责人。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;用户影响写在第一句&lt;/strong&gt;：annotations 的摘要先说「用户怎么了」，再说机器指标。「订单接口 5xx 比例 8%，用户下单失败」远好于「http_requests_total 异常」。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;一条合格的告警，应该让接手的人在十秒内明白三件事：用户怎么了、影响有多大、第一步做什么。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;:::warning
没有 runbook 的告警，等于把决策推给半夜被叫醒的人。写规则时如果写不出处理步骤，说明这条告警本身还没想清楚——先补 runbook，或者先降级成 ticket，想清楚了再升级。
:::&lt;/p&gt;
&lt;h2&gt;反模式清单&lt;/h2&gt;
&lt;p&gt;对照自查，中招的尽快改：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;按指标设告警&lt;/strong&gt;：每个指标都配一条，「全覆盖」的结果是全是噪音。监控可以全覆盖，告警必须挑症状。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;原因型告警当 page 用&lt;/strong&gt;：CPU 高、内存高直接打电话，十次里九次虚惊。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;阈值拍脑袋且从不复盘&lt;/strong&gt;：上线时随手写的数字，三年没人再看过。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;不设 for&lt;/strong&gt;：条件一满足立刻触发，毛刺和发布抖动全变成告警。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;没有负责人&lt;/strong&gt;：发到大群里，所有人都觉得别人会处理。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;一个故障炸出十几条告警&lt;/strong&gt;：根因只有一条，其余全是连带症状——分组、抑制没做好。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;告警只加不删&lt;/strong&gt;：规则文件只涨不缩，迟早没人信它。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;发到没人看的地方&lt;/strong&gt;：告警邮箱没人收、群早已全员免打扰，发了等于没发。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;定期清理：告警也要做减法&lt;/h2&gt;
&lt;p&gt;每个季度把告警规则拉出来过一遍，重点盯两类：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;从不触发的&lt;/strong&gt;：要么阈值定得永远够不着，要么对应的服务早就下线了。要么修正，要么删除——留着只会给人虚假的安全感。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;每次触发都被无视的&lt;/strong&gt;：触发几十次、没人处理过一次、也从没出过事。这种告警&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;比没有这条告警更危险&amp;lt;/span&amp;gt;，因为它在持续训练团队忽略告警渠道。处理办法只有两个：修到值得处理，或者删掉、降级。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;判断依据是数据：每条告警的触发次数、误报比例、平均处理时长，Alertmanager 和工单系统里都有记录，复盘时拿出来逐条过，不要凭感觉。&lt;/p&gt;
&lt;p&gt;具体做法可以很朴素：把过去一个季度每条 page 的触发记录拉出来，逐条标注「真故障、误报、计划内操作」三类。误报占一半以上的规则，要么改阈值，要么直接降级成 ticket；真故障一次没抓到、靠用户投诉才发现的，说明症状告警有缺口，复盘时补上。再看总量趋势：健康的系统里，page 应该稳定在每周个位数的量级。如果连续几个月往上爬，先别怪值班的人响应慢——多半是规则在失控增长，到了该做减法的时候。&lt;/p&gt;
&lt;h2&gt;上线前自检清单&lt;/h2&gt;
&lt;p&gt;新告警上线前，逐条打勾：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;[ ] 它对应哪个用户症状？说不出来，先别上线&lt;/li&gt;
&lt;li&gt;[ ] 是 page 还是 ticket？分级和渠道对得上吗？&lt;/li&gt;
&lt;li&gt;[ ] 阈值有依据吗？比例型还是绝对值，为什么？&lt;/li&gt;
&lt;li&gt;[ ] 设了 for 防抖吗？时长和信号的快慢匹配吗？&lt;/li&gt;
&lt;li&gt;[ ] runbook 链接能打开、步骤照着能执行吗？&lt;/li&gt;
&lt;li&gt;[ ] 负责人明确吗？标签打对了吗？&lt;/li&gt;
&lt;li&gt;[ ] 摘要第一句写的是用户影响吗？&lt;/li&gt;
&lt;li&gt;[ ] 手动触发演练过吗？通知链路真的通吗？&lt;/li&gt;
&lt;li&gt;[ ] 恢复时有没有 resolved 通知？不然没人知道它自己好了&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;告警设计的核心就一句话：少而准。先用 page / ticket 把渠道分开，再用症状优先和四大黄金信号守住基本盘，阈值配上 for 防抖；有了 SLO 之后再考虑燃烧率告警；每条告警带齐可执行、runbook、负责人、用户影响四件套；最后定期做减法，把不触发的和没人理的清理掉。告警系统和代码一样，不维护就会腐烂——区别是，告警腐烂的代价是在真正出事的那个晚上付的。&lt;/p&gt;
</content:encoded></item><item><title>监控与可观测性：Alertmanager 告警链实战，分组抑制静默一次配好</title><link>https://www.anexns.cloudns.org/posts/monitoring-alertmanager/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-alertmanager/</guid><description>Prometheus 只负责发现问题，真正决定你半夜会不会被刷屏的是 Alertmanager：路由分组、抑制、静默与 Telegram/Webhook/邮件接收器全流程实战。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先讲个事故：条条都是真告警，等于没报&lt;/h2&gt;
&lt;p&gt;凌晨三点，一台机器的宿主机网络抖了一下。接下来十分钟，手机震了两百多次：实例宕机、服务不可用、接口错误率飙升、磁盘延迟异常……点开一看，每一条都是真的——机器确实短暂失联过，所有依赖它的检查当然全红。问题是两百条真告警挤在十分钟里，效果和没报一样：你既分不清哪条是根因，也不知道事态有没有扩大，只能一条条往下翻，翻到最后发现最初那条「实例宕机」才是源头，其余全是连锁反应。&lt;/p&gt;
&lt;p&gt;这不是规则写错了，而是告警链缺了最后一环。Prometheus 的职责到「算出哪条规则触发了」为止，它把告警一股脑往外推，不做合并、不做分级、不做去重。把告警收拢成「一件事一条消息」的，是 &lt;strong&gt;Alertmanager&lt;/strong&gt;：同一个故障引发的几十条告警，它按分组捏成一条通知；大故障已经报了，它把同源的小告警先压住；你在维护窗口里，它按静默规则闭嘴。这一篇就把这条链配完整：Prometheus 侧怎么接、规则文件怎么写、路由树怎么分流、Telegram/Webhook/邮件三个接收器怎么落地。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/prometheus/alertmanager&lt;/p&gt;
&lt;h2&gt;告警链全景：谁干什么&lt;/h2&gt;
&lt;p&gt;先把分工说清，后面所有配置都挂在这张图上：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;环节&lt;/th&gt;
&lt;th&gt;组件&lt;/th&gt;
&lt;th&gt;职责&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;采集与计算&lt;/td&gt;
&lt;td&gt;Prometheus&lt;/td&gt;
&lt;td&gt;抓指标、按规则文件评估表达式，触发后把告警推给 Alertmanager&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;收拢与分发&lt;/td&gt;
&lt;td&gt;Alertmanager&lt;/td&gt;
&lt;td&gt;去重、分组、抑制、静默，按路由树把通知发给不同接收器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;落地&lt;/td&gt;
&lt;td&gt;Telegram / Webhook / 邮件&lt;/td&gt;
&lt;td&gt;你真正看到消息的地方&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;Alertmanager 官方镜像是 &lt;code&gt;prom/alertmanager&lt;/code&gt;，默认监听 &lt;strong&gt;9093&lt;/strong&gt; 端口。它本身不存指标、不算表达式，是个纯粹的「告警邮局」：Prometheus 把信投进来，它负责分拣、合并、按地址投递。所以排障时也要按这个分工来：没收到消息，先分清是信没投进来，还是邮局分拣出了问题。&lt;/p&gt;
&lt;p&gt;Prometheus 侧的接入只有两处改动。&lt;code&gt;prometheus.yml&lt;/code&gt; 里告诉它 Alertmanager 在哪、规则文件在哪：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# prometheus.yml（节选）
alerting:
  alertmanagers:
    - static_configs:
        - targets:
            - alertmanager:9093   # Docker 网络内用服务名；同机部署可用 localhost:9093

rule_files:
  - &quot;rules/*.yml&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改完重启或热重载 Prometheus，它就会把触发中的告警持续推送给 Alertmanager——注意是「持续推送」：只要告警还在 firing 状态，Prometheus 会周期性重发，Alertmanager 靠这个机制做去重和「恢复通知」，所以链路偶尔抖一下不会丢告警。&lt;/p&gt;
&lt;h2&gt;规则文件：先有一条能用的告警&lt;/h2&gt;
&lt;p&gt;规则写在 &lt;code&gt;rule_files&lt;/code&gt; 挂载的文件里。先给一条最经典、也最该有的完整规则——实例失联：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# rules/node.yml
groups:
  - name: instance-health
    rules:
      - alert: InstanceDown
        expr: up == 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: &quot;实例 {{ $labels.instance }} 已失联&quot;
          description: &quot;{{ $labels.job }} 的目标 {{ $labels.instance }} 连续 5 分钟抓取失败，请立即检查。&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三个部分各管一件事：&lt;code&gt;expr&lt;/code&gt; 是触发条件（&lt;code&gt;up == 0&lt;/code&gt; 表示抓取目标失败，表达式写法可回顾 &lt;a href=&quot;/posts/monitoring-promql/&quot;&gt;PromQL 查询入门&lt;/a&gt;）；&lt;code&gt;for: 5m&lt;/code&gt; 是防抖——状态持续满 5 分钟才真正 firing，短暂抖动不会打扰你，这一条能挡掉一大半误报；&lt;code&gt;labels.severity&lt;/code&gt; 是给 Alertmanager 路由用的分流标签，后面路由树全靠它。&lt;code&gt;annotations&lt;/code&gt; 里的 summary 和 description 会被通知模板引用，写成人话，半夜被吵醒时你第一眼看的就是这两行。规则的系统化写法（分级、阈值、录制规则配合）我在 &lt;a href=&quot;/posts/monitoring-alert-rules/&quot;&gt;告警规则编写指南&lt;/a&gt; 里展开过，这一篇只取一条贯穿全程。&lt;/p&gt;
&lt;h2&gt;alertmanager.yml：路由、接收器、抑制三大部分&lt;/h2&gt;
&lt;p&gt;Alertmanager 的全部行为都在一个 &lt;code&gt;alertmanager.yml&lt;/code&gt; 里，分三大块：&lt;code&gt;route&lt;/code&gt; 路由树、&lt;code&gt;receivers&lt;/code&gt; 接收器、&lt;code&gt;inhibit_rules&lt;/code&gt; 抑制规则。先看一份完整的最小可用配置，再逐块拆：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# alertmanager.yml
global:
  resolve_timeout: 5m

route:
  receiver: telegram-default        # 默认接收器：没被子路由接走的告警都来这
  group_by: [&apos;alertname&apos;, &apos;instance&apos;]
  group_wait: 30s                   # 新分组先等 30 秒，把同时到达的告警攒齐再发
  group_interval: 5m                # 同一组有新告警加入时，距上次通知至少隔 5 分钟
  repeat_interval: 4h               # 告警一直没恢复，最多每 4 小时重复提醒一次
  routes:
    - matchers:
        - severity = &quot;critical&quot;
      receiver: telegram-critical
      repeat_interval: 30m          # 严重级单独覆盖：半小时催一次
    - matchers:
        - severity = &quot;warning&quot;
      receiver: webhook-warning

receivers:
  - name: telegram-default
    telegram_configs:
      - bot_token: &apos;&amp;lt;在环境变量或挂载文件中填入&amp;gt;&apos;
        chat_id: 123456789
        send_resolved: true

  - name: telegram-critical
    telegram_configs:
      - bot_token: &apos;&amp;lt;同上&amp;gt;&apos;
        chat_id: 123456789
        send_resolved: true

  - name: webhook-warning
    webhook_configs:
      - url: &apos;http://localhost:5001/alert-hook&apos;
        send_resolved: true

  - name: email-team
    email_configs:
      - to: &apos;ops@example.com&apos;
        from: &apos;alertmanager@example.com&apos;
        smarthost: &apos;smtp.example.com:587&apos;
        auth_username: &apos;alertmanager@example.com&apos;
        auth_password: &apos;&amp;lt;凭据不要明文进仓库&amp;gt;&apos;
        send_resolved: true

inhibit_rules:
  - source_matchers:
      - alertname = &quot;InstanceDown&quot;
    target_matchers:
      - severity =~ &quot;warning|critical&quot;
    equal: [&apos;instance&apos;]
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;路由树：按标签把告警分流&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;route&lt;/code&gt; 是一棵树：告警从根节点进入，依次匹配子路由的 &lt;code&gt;matchers&lt;/code&gt;，命中就走那个子路由指定的接收器，没命中就落回根节点的默认接收器。上面的例子里，&lt;code&gt;severity: critical&lt;/code&gt; 的进 &lt;code&gt;telegram-critical&lt;/code&gt; 并把重复提醒加密到 30 分钟一次，&lt;code&gt;warning&lt;/code&gt; 的走 Webhook，其余全部进默认 Telegram。分流维度不只有 severity，也可以按 &lt;code&gt;job&lt;/code&gt;、&lt;code&gt;team&lt;/code&gt;、&lt;code&gt;instance&lt;/code&gt; 任意标签组合——原则是&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;让不同重要程度的告警走不同的打扰通道&amp;lt;/span&amp;gt;：严重级要能把人叫醒，提醒级进群里留个记录就够了，全挤在一个通道里，最后就是开头那场刷屏事故。&lt;/p&gt;
&lt;p&gt;四个时间参数是分组行为的核心，一起讲透：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;调大的后果&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;group_wait&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;新分组第一条告警先等多久再发，等同批告警到齐&lt;/td&gt;
&lt;td&gt;报得慢，但合并得更干净&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;group_interval&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;同一组新增告警时，两次通知的最小间隔&lt;/td&gt;
&lt;td&gt;故障演进的细节会被攒着晚报&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;repeat_interval&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;告警持续未恢复时，重复提醒的间隔&lt;/td&gt;
&lt;td&gt;太大容易把「还没好」忘了，太小又刷屏&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;resolve_timeout&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;多久收不到重发就判定告警已恢复&lt;/td&gt;
&lt;td&gt;太小会在链路抖动时误发恢复通知&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;接收器：三个最小可用例子&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;receivers&lt;/code&gt; 是命名的投递目标，路由树里引用的就是这些名字。Telegram 是个人和小团队最顺手的：先找 BotFather 建机器人、拿到 bot_token，再把机器人拉进群（或私聊它）拿到 chat_id，填进 &lt;code&gt;telegram_configs&lt;/code&gt; 即可；&lt;code&gt;send_resolved: true&lt;/code&gt; 别省，恢复通知和触发通知一样重要，不然你永远不知道故障结束没有。Webhook 是最通用的口子，任何能收 HTTP POST 的系统都能接——自建的转发脚本、聊天机器人的自定义集成、工单系统都行，Alertmanager 会把整组告警以 JSON 发过去。邮件是最古老但最可靠的兜底，&lt;code&gt;email_configs&lt;/code&gt; 需要一个可用的 SMTP 中继；注意 Gmail 等服务商通常要求应用专用密码，且部分云厂商默认封 25 端口，用 587 提交端口更稳妥。&lt;/p&gt;
&lt;p&gt;:::warning
Telegram 的 bot_token 和 SMTP 密码都是凭据，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;alertmanager.yml 绝不要提交进公开仓库&amp;lt;/span&amp;gt;。稳妥做法是把配置文件挂载进容器并收紧文件权限，或把凭据拆到单独文件、用环境变量注入的启动方式管理；一旦 token 泄漏，任何人都能借你的机器人发消息、读会话 ID。
:::&lt;/p&gt;
&lt;h3&gt;抑制规则：大故障在场时，小告警先闭嘴&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;inhibit_rules&lt;/code&gt; 解决的是开头事故的另一半：根因明确时，连锁告警不要再单独响。上面的规则说的是：当某台 instance 已经触发 &lt;code&gt;InstanceDown&lt;/code&gt;（源告警），同一台 instance 上所有 warning 和 critical 告警（目标告警）全部被抑制——机器都失联了，它身上的「接口错误率」「磁盘延迟」自然全红，再逐条发出来纯属噪音。&lt;code&gt;equal: [&apos;instance&apos;]&lt;/code&gt; 是关键：抑制只在标签值相同的告警之间生效，不会误伤别的机器。抑制不是删除，告警在 Alertmanager 的 Web UI 里能看到且标着 inhibited 状态，故障恢复后抑制自动解除。&lt;/p&gt;
&lt;h2&gt;分组、抑制、静默：三件套别混淆&lt;/h2&gt;
&lt;p&gt;这三个概念名字相近，解决的问题完全不同，配错了会互相打架，单独对比一遍：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;机制&lt;/th&gt;
&lt;th&gt;解决的问题&lt;/th&gt;
&lt;th&gt;生效方式&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;分组（Grouping）&lt;/td&gt;
&lt;td&gt;同一故障的几十条告警刷屏&lt;/td&gt;
&lt;td&gt;按标签合并成一条通知，自动、长期有效&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;抑制（Inhibition）&lt;/td&gt;
&lt;td&gt;根因告警已报，连锁告警重复打扰&lt;/td&gt;
&lt;td&gt;大告警在场时压住同源小告警，自动、长期有效&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;静默（Silence）&lt;/td&gt;
&lt;td&gt;维护窗口内明知会触发告警&lt;/td&gt;
&lt;td&gt;人工在 Web UI 创建，按标签匹配、带过期时间&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一句话记忆：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;分组管「合并」，抑制管「主次」，静默管「临时」&amp;lt;/span&amp;gt;。分组和抑制写在配置文件里长期生效；静默是运行时操作，下面单独说。&lt;/p&gt;
&lt;h2&gt;校验、热重载与静默操作&lt;/h2&gt;
&lt;p&gt;改配置最怕写错一个缩进然后服务起不来。Alertmanager 自带命令行工具 &lt;code&gt;amtool&lt;/code&gt;，改完先校验再加载：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 校验配置文件语法与引用完整性
amtool check-config alertmanager.yml

# 查看当前实际收到的告警（排障验货用）
amtool alert query
amtool alert query --alertmanager.url=http://localhost:9093
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;校验通过后不必重启进程，给它发一个热重载请求即可，新配置立即生效、正在分组的告警不丢失：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -X POST http://localhost:9093/-/reload
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Docker 部署时也可以用 &lt;code&gt;docker kill -s SIGHUP &amp;lt;容器名&amp;gt;&lt;/code&gt; 达到同样效果。养成「改配置 → check-config → reload」三步习惯，能避开绝大多数「改完反而全哑」的事故——&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;配置写错时 Alertmanager 会拒绝加载新配置并保持旧配置运行&amp;lt;/span&amp;gt;，表面上看服务没挂，实际你的新路由根本没生效，所以每次 reload 后顺手去 Web UI 的 Status 页确认配置已更新。&lt;/p&gt;
&lt;p&gt;静默（Silence）是给维护窗口用的：打开 &lt;code&gt;http://localhost:9093&lt;/code&gt; 的 Web UI，进 Silences 页签点 New Silence，填匹配器（比如 &lt;code&gt;instance=&quot;db-01&quot;&lt;/code&gt;）和起止时间，再写一句备注说明在维护什么。到点自动失效，不用记得手动解除。计划内重启、升级、迁移这类「明知道会红一片」的操作，提前建好静默，比事后在一堆告警里翻找省事得多。注意静默匹配的是标签，建之前先用告警列表页确认目标告警的标签拼写，&lt;code&gt;instance&lt;/code&gt; 值带不带端口这类细节写错，静默就形同虚设。&lt;/p&gt;
&lt;h2&gt;排障：Prometheus 里 fired 了，手机却没动静&lt;/h2&gt;
&lt;p&gt;这是最常见的一类问题：规则明明触发，通知就是不来。按告警的流向逐段排查，不要跳步：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;规则段&lt;/strong&gt;：在 Prometheus 的 Alerts 页确认告警状态是 firing 而不是 pending——&lt;code&gt;for&lt;/code&gt; 时长没熬满是不会推送的，新规则上线后前几分钟没动静多半是这个原因。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;推送段&lt;/strong&gt;：Prometheus 的 Status → Runtime &amp;amp; Build / Targets 之外，重点看它眼中的 Alertmanager 状态：在 Web UI 的 Status 页或 &lt;code&gt;/-/healthy&lt;/code&gt; 之外，用 &lt;code&gt;amtool alert query&lt;/code&gt; 直接问 Alertmanager——能列出这条告警，说明推送段通了，问题在分发段；列不出，就是 Prometheus 的 &lt;code&gt;alerting.alertmanagers&lt;/code&gt; 目标写错或网络不通。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;路由段&lt;/strong&gt;：在 Alertmanager Web UI 的 Alerts 页点开这条告警，看它命中的 receiver 名字对不对。匹配不上预期路由，多半是标签问题：规则里 &lt;code&gt;severity&lt;/code&gt; 的值拼写、大小写与路由 &lt;code&gt;matchers&lt;/code&gt; 不一致是最常见的坑。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;接收器段&lt;/strong&gt;：路由对了仍没消息，查 Alertmanager 日志里的发送错误：Telegram 常见 bot_token 失效、机器人没被拉进群、chat_id 写错；邮件常见 SMTP 认证失败或端口被封；Webhook 常见目标服务没起或返回非 2xx。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;时间段&lt;/strong&gt;：通知延迟得离谱时，检查两台机器的系统时间与时区——分组等待、静默窗口、&lt;code&gt;for&lt;/code&gt; 时长全都吃系统时钟，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;时区错位会让静默和分组表现得像闹鬼&amp;lt;/span&amp;gt;。服务器统一 NTP 同步，通知里的时间字段也建议在模板里固定时区再看。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;另外一个容易忽略的点：告警被抑制或静默时，表面症状也是「没收到」，但那是配置在正常工作——在 Alerts 页能看到 inhibited / silenced 标记，先排除这两种状态，再往链路故障方向查。自建服务里把告警接到现成通知渠道的轻量做法，可对照 &lt;a href=&quot;/posts/selfhost-monitoring-alerts/&quot;&gt;自建服务监控告警&lt;/a&gt; 那篇；从外网探测可用性的另一条线，则是 &lt;a href=&quot;/posts/monitoring-blackbox/&quot;&gt;黑盒监控&lt;/a&gt; 的活儿。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Alertmanager 的价值不在「把消息发出去」——那只是个 HTTP 请求——而在于它站在 Prometheus 和你之间，把告警流先收拢再分发：分组把同一故障的几十条合并成一条，路由按严重程度分到不同打扰通道，抑制让根因告警压住连锁噪音，静默给维护窗口留一个体面的关窗方式。配好这四样，再回头看开头那场事故：宿主机抖动会变成一条「InstanceDown（critical）」加上同组的一串连带告警摘要，而不是两百次震动。告警系统的目标从来不是「一条不漏」，而是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;每一次打扰都值得被吵醒&amp;lt;/span&amp;gt;——这条链配完，你的告警才算从「装了」变成「能用了」。&lt;/p&gt;
</content:encoded></item><item><title>监控与可观测性：blackbox_exporter 黑盒探测——站在用户的位置看你的服务</title><link>https://www.anexns.cloudns.org/posts/monitoring-blackbox/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-blackbox/</guid><description>用 blackbox_exporter 从外部视角探测 HTTP、TCP、DNS 与 ICMP：模块配置、Prometheus relabel 经典写法、证书到期告警与排障全流程。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;一个经典场景：监控全绿，用户说打不开&lt;/h2&gt;
&lt;p&gt;服务器 CPU 正常、内存充足、Nginx 进程活着，Prometheus 仪表盘上一片绿色。然后用户发来截图：网站打不开。&lt;/p&gt;
&lt;p&gt;问题出在哪？出在你站的位置不对。node_exporter、进程探活这类白盒监控站在服务器内部往外看，看到的是「进程还活着」；而用户站在互联网另一端，他经历的是 DNS 解析、TCP 建连、TLS 握手、HTTP 响应这一整条链路——任何一环断了，他看到的都是打不开。证书过期、DNS 解析被改错、防火墙误封、运营商线路故障，这些事故在白盒视角里全是隐形的。&lt;/p&gt;
&lt;p&gt;黑盒探测补的就是这个视角：不关心服务内部怎么实现，只从外部模拟一次真实访问，记录成没成、花了多久。Prometheus 生态里干这件事的标准工具就是 blackbox_exporter。本篇把它和&lt;a href=&quot;/posts/monitoring-prometheus/&quot;&gt;Prometheus 本体&lt;/a&gt;接起来，再顺手解决证书到期告警这个高频刚需。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/prometheus/blackbox_exporter&lt;/p&gt;
&lt;h2&gt;blackbox_exporter 是怎么工作的&lt;/h2&gt;
&lt;p&gt;它的模型很简单：自己不主动探测任何目标，而是等 Prometheus 来问。Prometheus 通过 relabel 把「要探测的目标」作为参数传给它，它按指定的模块（module）对目标发起一次探测，把结果翻译成指标返回。一次探测产出的核心指标有：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;指标&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;probe_success&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;探测成功为 1，失败为 0，最重要的告警依据&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;probe_duration_seconds&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;整个探测过程的总耗时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;probe_http_status_code&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;HTTP 探测实际拿到的状态码&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;probe_ssl_earliest_cert_expiry&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;目标证书的最早到期时间（Unix 时间戳），证书告警靠它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;probe_dns_lookup_time_seconds&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;DNS 解析耗时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;probe_http_duration_seconds&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;HTTP 各阶段耗时（解析、建连、TLS、处理、传输分段）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;探测器（prober）内置四种：&lt;code&gt;http&lt;/code&gt;、&lt;code&gt;tcp&lt;/code&gt;、&lt;code&gt;dns&lt;/code&gt;、&lt;code&gt;icmp&lt;/code&gt;，再加上 &lt;code&gt;grpc&lt;/code&gt;。用哪种、什么参数算成功，都写在它自己的配置文件里，这就是模块。&lt;/p&gt;
&lt;h2&gt;Docker 部署&lt;/h2&gt;
&lt;p&gt;官方镜像 &lt;code&gt;prom/blackbox-exporter&lt;/code&gt;，默认端口 9115。先写好配置文件再启动，配置目录只读挂载：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p /opt/blackbox &amp;amp;&amp;amp; cd /opt/blackbox
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把下面的 blackbox.yml 放进去，然后用 Docker Compose 拉起：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  blackbox:
    image: prom/blackbox-exporter:latest
    container_name: blackbox
    restart: unless-stopped
    command:
      - --config.file=/config/blackbox.yml
    ports:
      - &quot;127.0.0.1:9115:9115&quot;
    volumes:
      - ./blackbox.yml:/config/blackbox.yml:ro
    cap_add:
      - NET_RAW
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;cap_add: NET_RAW&lt;/code&gt; 是给 ICMP 探测用的——ping 探测需要原始套接字能力，普通容器权限不够，不加这一段 ICMP 模块永远失败。用不到 ping 可以去掉。&lt;/p&gt;
&lt;h2&gt;配置模块：blackbox.yml&lt;/h2&gt;
&lt;p&gt;模块就是「一类目标的探测配方」。下面这份覆盖最常见的四种场景：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;modules:
  http_2xx:
    prober: http
    timeout: 10s
    http:
      valid_status_codes: [200]
      method: GET
      follow_redirects: true
      preferred_ip_protocol: &quot;ip4&quot;
      tls_config:
        insecure_skip_verify: false
  http_post_2xx:
    prober: http
    timeout: 10s
    http:
      valid_status_codes: [200, 204]
      method: POST
  tcp_connect:
    prober: tcp
    timeout: 10s
  dns_query:
    prober: dns
    timeout: 10s
    dns:
      query_name: &quot;example.com&quot;
      query_type: &quot;A&quot;
      valid_rcodes:
        - NOERROR
  icmp_ping:
    prober: icmp
    timeout: 10s
    icmp:
      preferred_ip_protocol: &quot;ip4&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;http_2xx&lt;/code&gt; 是最常用的模块。&lt;code&gt;valid_status_codes&lt;/code&gt; 不写时默认 2xx 算成功；写死 &lt;code&gt;[200]&lt;/code&gt; 可以把「返回 301 去了别处」也判为异常，视你的预期取舍。&lt;code&gt;preferred_ip_protocol&lt;/code&gt; 建议明确写 &lt;code&gt;ip4&lt;/code&gt; 或 &lt;code&gt;ip6&lt;/code&gt;，否则双栈环境下解析到哪个协议带有随机性，探测结果会飘。&lt;/li&gt;
&lt;li&gt;需要带请求头的场景（比如绕过 CDN 的回源检查、带 Host 访问）在模块里加 &lt;code&gt;headers&lt;/code&gt; 字段即可，一个模块对应一类目标，不要把所有目标塞进一个模块硬凑。&lt;/li&gt;
&lt;li&gt;DNS 模块的 &lt;code&gt;query_name&lt;/code&gt; 和 &lt;code&gt;query_type&lt;/code&gt; 写在模块里，这意味着不同域名要配不同模块，或者在 Prometheus 侧用参数覆盖——目标不多时按域名建模块最直白。&lt;/li&gt;
&lt;li&gt;TCP 模块只验证端口能不能建连，适合探测 MySQL、Redis 这类没有 HTTP 接口的服务「还活着」。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
blackbox_exporter 的 9115 端口不要裸奔公网。它没有任何鉴权，任何人都能拿它当跳板去探测任意地址，等于在你的服务器上开了一个公开的 SSRF 入口。像上面那样只绑 &lt;code&gt;127.0.0.1&lt;/code&gt;、只让同机的 Prometheus 访问，是最稳妥的做法；跨机器部署时也要用防火墙或内网隔离。同理，探测目标清单里不要写内网敏感端口再把结果页暴露出去。
:::&lt;/p&gt;
&lt;h2&gt;Prometheus 侧：经典 relabel 写法&lt;/h2&gt;
&lt;p&gt;这是全篇最核心的一段。blackbox 的接法初看有点绕：Prometheus 把目标写进 &lt;code&gt;__param_target&lt;/code&gt; 参数，再把抓取地址 &lt;code&gt;__address__&lt;/code&gt; 改写成 blackbox 的地址，于是 Prometheus 实际抓的是 blackbox，探测的却是目标：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;scrape_configs:
  - job_name: &quot;blackbox-http&quot;
    metrics_path: /probe
    params:
      module: [http_2xx]
    static_configs:
      - targets:
          - https://blog.example.com
          - https://www.example.com
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9115

  - job_name: &quot;blackbox-tcp&quot;
    metrics_path: /probe
    params:
      module: [tcp_connect]
    static_configs:
      - targets:
          - 127.0.0.1:3306
          - 127.0.0.1:6379
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9115
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三条 relabel 各司其职：第一条把原始目标抄进 &lt;code&gt;__param_target&lt;/code&gt;，Prometheus 会自动把它拼成 &lt;code&gt;/probe?target=...&lt;/code&gt; 的查询参数；第二条把目标地址留一份到 &lt;code&gt;instance&lt;/code&gt; 标签，方便在仪表盘和告警里认出是哪个目标；第三条把真正的抓取地址换成 blackbox 的 9115。少了任何一条都跑不通，这是官方范式，照抄即可。&lt;/p&gt;
&lt;p&gt;目标多起来之后不要把 targets 列表写死在 Prometheus 配置里，改用 &lt;code&gt;file_sd_configs&lt;/code&gt; 把目标放进独立的 JSON/YAML 文件，改目标不用重启 Prometheus，配合&lt;a href=&quot;/posts/monitoring-alertmanager/&quot;&gt;告警链路&lt;/a&gt;做变更管理也更干净。轻量场景如果只需要「活没活」的状态页，也可以看看更简单的 &lt;a href=&quot;/posts/monitoring-gatus/&quot;&gt;Gatus&lt;/a&gt;；但要把探测结果沉淀成指标、做趋势和证书告警，还是 blackbox 这套更合适。和 &lt;a href=&quot;/posts/selfhost-uptime-kuma/&quot;&gt;Uptime Kuma&lt;/a&gt; 的分工也是同理：Kuma 看状态，blackbox 出数据。&lt;/p&gt;
&lt;h2&gt;先手动验活，再接 Prometheus&lt;/h2&gt;
&lt;p&gt;接配置之前，先用 curl 直接问 blackbox 一次，能省掉大量来回猜的时间：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl &apos;http://localhost:9115/probe?target=https://blog.example.com&amp;amp;module=http_2xx&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回一堆 &lt;code&gt;probe_*&lt;/code&gt; 指标就说明模块和目标都通。重点看 &lt;code&gt;probe_success 1&lt;/code&gt;——是 1 再去改 Prometheus 配置，是 0 就先在这一层把问题定位掉。&lt;/p&gt;
&lt;h2&gt;证书到期告警&lt;/h2&gt;
&lt;p&gt;这是黑盒探测最有价值的副产品：只要目标走 HTTPS，&lt;code&gt;probe_ssl_earliest_cert_expiry&lt;/code&gt; 就会带回证书到期时间戳，不需要任何额外的证书管理工具。在 Prometheus 的告警规则里加两条：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;groups:
  - name: blackbox
    rules:
      - alert: CertExpiringSoon
        expr: (probe_ssl_earliest_cert_expiry - time()) / 86400 &amp;lt; 15
        for: 1h
        labels:
          severity: warning
        annotations:
          summary: &quot;证书将在 15 天内到期：{{ $labels.instance }}&quot;
      - alert: ProbeFailed
        expr: probe_success == 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: &quot;黑盒探测失败：{{ $labels.instance }}（job {{ $labels.job }}）&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第一条把时间戳换算成剩余天数，小于 15 天开始提醒——Let&apos;s Encrypt 这类 90 天短证书靠自动续期，续期任务悄悄挂掉是真实发生过的事故，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;证书过期当天网站直接不可访问，且白盒监控往往毫无察觉&amp;lt;/span&amp;gt;，这条规则就是专门兜这种底的。第二条是最基础的可用性告警，&lt;code&gt;for: 5m&lt;/code&gt; 避免网络抖动一闪就报警。规则触发后经 Alertmanager 分发到 Telegram 或邮件，本系列的告警篇有完整链路。&lt;/p&gt;
&lt;p&gt;有了指标，Grafana 侧可以顺手做两个面板：各目标 &lt;code&gt;probe_duration_seconds&lt;/code&gt; 的时序图看响应趋势，&lt;code&gt;probe_http_duration_seconds&lt;/code&gt; 按 &lt;code&gt;phase&lt;/code&gt; 标签拆开看 DNS、TLS、服务端处理各占多少——慢在哪一段，一目了然。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;probe_success&lt;/code&gt; 一直是 0。&lt;/strong&gt; 别先怀疑 Prometheus。按上面的方法手动 curl 一次 probe 接口：curl 通、Prometheus 里不通，是 relabel 写错了（最常见是漏了第三条改写 &lt;code&gt;__address__&lt;/code&gt;）；curl 也不通，问题在 blackbox 侧，接着看下面几条。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;HTTP 目标明明能打开却报失败。&lt;/strong&gt; 查 &lt;code&gt;probe_http_status_code&lt;/code&gt; 的实际值：可能是目标返回了非预期的状态码（比如强制跳转、需要特定 Host 头），调整模块的 &lt;code&gt;valid_status_codes&lt;/code&gt; 或补 &lt;code&gt;headers&lt;/code&gt;；也可能是双栈解析飘到了 IPv6，先把 &lt;code&gt;preferred_ip_protocol&lt;/code&gt; 写死再看。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;DNS 模块不通。&lt;/strong&gt; 先确认模块里的 &lt;code&gt;query_type&lt;/code&gt; 和目标场景对得上（查 A 记录写 &lt;code&gt;A&lt;/code&gt;、查邮件记录写 &lt;code&gt;MX&lt;/code&gt;），再确认 &lt;code&gt;query_name&lt;/code&gt; 没拼错；还不行就把 target 换成具体的 DNS 服务器地址单独验，区分是模块配置问题还是目标 DNS 本身不响应。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;ICMP 探测全灭。&lt;/strong&gt; 几乎都是权限问题：Docker 部署确认 &lt;code&gt;cap_add&lt;/code&gt; 里有 &lt;code&gt;NET_RAW&lt;/code&gt;；宿主机直接运行确认二进制有相应的 capability。另外有些云厂商和目标侧防火墙默认禁 ping，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;ICMP 不通不等于主机宕机&amp;lt;/span&amp;gt;，别拿它当唯一的存活判据。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;证书指标缺失。&lt;/strong&gt; &lt;code&gt;probe_ssl_earliest_cert_expiry&lt;/code&gt; 只在目标真正走了 TLS 时才有。如果目标是纯 HTTP、或者 HTTPS 探测因为证书校验失败根本没握上手，这个指标就不会出现。想单独盯证书校验问题，可以另建一个 &lt;code&gt;insecure_skip_verify: false&lt;/code&gt; 的严格模块和宽松模块对照着看。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;探测超时。&lt;/strong&gt; 模块的 &lt;code&gt;timeout&lt;/code&gt; 和 Prometheus 的 &lt;code&gt;scrape_timeout&lt;/code&gt; 要对齐，前者大于后者时 Prometheus 会先一步掐断并报 context deadline exceeded，看起来像目标故障，其实是配置打架。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;黑盒探测的价值在于&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;换一个站位：从用户的网络位置出发，把 DNS、建连、TLS、响应整条链路验一遍&amp;lt;/span&amp;gt;，这是任何内部指标都替代不了的视角。落地路径很短：一个容器、一份 blackbox.yml、一段照抄即可的 relabel 配置，再加两条告警规则，就能把可用性探测和证书到期预警一起补齐。它和白盒指标不是二选一——白盒告诉你服务内部健不健康，黑盒告诉你用户到底能不能用得上，两边都绿，才是真的没问题。&lt;/p&gt;
</content:encoded></item><item><title>监控与可观测性：cAdvisor 给每个容器装一块仪表盘</title><link>https://www.anexns.cloudns.org/posts/monitoring-cadvisor/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-cadvisor/</guid><description>用 cAdvisor 持续采集每个容器的 CPU、内存、网络与磁盘指标并接入 Prometheus，定位到底是哪个容器在偷吃资源。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;十几个容器跑着，哪个在偷吃内存？&lt;/h2&gt;
&lt;p&gt;宿主机内存告警响了，你 SSH 上去敲 &lt;code&gt;docker stats&lt;/code&gt;，看到的只是敲下回车那一秒的快照：某个容器占了 1.2 GiB，看起来也不算离谱。可偷吃内存的往往不是「现在占得最多」的那个，而是「一直在慢慢涨」的那个——快照看不出趋势，更看不出凌晨三点发生过什么。&lt;/p&gt;
&lt;p&gt;容器级监控缺的不是某一个瞬间的数据，而是一条连续的时间线：每个容器的 CPU、内存、网络、磁盘用量随时间变化的曲线。有了曲线，谁在涨、什么时候开始涨、涨之前发布过什么，一目了然。上一篇 &lt;a href=&quot;/posts/monitoring-node-exporter/&quot;&gt;node_exporter 篇&lt;/a&gt;解决的是「宿主机整体怎么样」，这一篇补上「每个容器分别怎么样」这一层。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/google/cadvisor&lt;/p&gt;
&lt;h2&gt;cAdvisor 是什么&lt;/h2&gt;
&lt;p&gt;cAdvisor（Container Advisor）是 Google 开源的容器资源监控工具。它常驻在宿主机上，通过 cgroup 读取每一个容器的资源计数器，持续采集 CPU、内存、网络、文件系统等用量数据，自带一个简易 Web UI（默认 8080 端口），同时在 &lt;code&gt;/metrics&lt;/code&gt; 端点以 Prometheus 格式暴露全部指标，供 Prometheus 定期抓取入库。&lt;/p&gt;
&lt;p&gt;它和 &lt;code&gt;docker stats&lt;/code&gt; 的定位完全不同：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;docker stats&lt;/th&gt;
&lt;th&gt;cAdvisor&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;数据形态&lt;/td&gt;
&lt;td&gt;当前时刻的一次性快照&lt;/td&gt;
&lt;td&gt;持续采集的时间序列&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;历史趋势&lt;/td&gt;
&lt;td&gt;无，看完即逝&lt;/td&gt;
&lt;td&gt;入库 Prometheus 后任意回溯&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;告警能力&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;配合 PromQL 与 Alertmanager&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;覆盖范围&lt;/td&gt;
&lt;td&gt;容器 CPU、内存、网络、IO 概况&lt;/td&gt;
&lt;td&gt;更细：工作集内存、文件系统用量、每网卡流量等&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;使用方式&lt;/td&gt;
&lt;td&gt;临时排障时手动看&lt;/td&gt;
&lt;td&gt;常驻服务，面板与告警自动跑&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;简单说，&lt;code&gt;docker stats&lt;/code&gt; 是体温计，量一下就完事；cAdvisor 是住院监护仪，曲线一直画着。前者适合临时确认，后者才是监控体系的一部分。&lt;/p&gt;
&lt;p&gt;它的工作方式并不复杂：Linux 内核会把每个容器的资源用量记在 cgroup 文件系统里，cAdvisor 要做的就是周期性地把这些计数器读出来、按容器整理好、再以指标格式暴露出去。它还会自动发现新启动的容器、移除已停止的容器，运维侧不需要每加一个容器就改一处配置。除用量之外，它同时暴露每个容器的规格信息，比如 CPU 与内存上限，方便把「实际用了多少」和「最多能用多少」放在一起看，这一点后面写 PromQL 时会用到。&lt;/p&gt;
&lt;h2&gt;Docker Compose 部署&lt;/h2&gt;
&lt;p&gt;cAdvisor 需要读取宿主机的 cgroup、Docker 元数据与容器文件系统，所以部署的关键不在镜像本身，而在一组只读挂载：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  cadvisor:
    image: gcr.io/cadvisor/cadvisor:latest
    container_name: cadvisor
    privileged: true
    ports:
      - &quot;127.0.0.1:8080:8080&quot;
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
      - /dev/disk/:/dev/disk:ro
    restart: unless-stopped
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐项解释这些挂载为什么存在、为什么全部只读：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;挂载&lt;/th&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;th&gt;为什么只读&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/:/rootfs:ro&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;宿主机根文件系统，cAdvisor 要遍历其中的目录结构统计各容器文件系统用量&lt;/td&gt;
&lt;td&gt;只需要看目录与用量，不需要改任何文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/var/run:/var/run:ro&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Docker 的 socket（docker.sock）在这里，用来查询容器名、镜像、标签等元数据&lt;/td&gt;
&lt;td&gt;只通过 socket 问信息，不写宿主机文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/sys:/sys:ro&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;cgroup 挂载点在 &lt;code&gt;/sys/fs/cgroup&lt;/code&gt; 下，CPU 与内存的原始计数器都从这里读&lt;/td&gt;
&lt;td&gt;计数器只读读取，写权限毫无必要&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/var/lib/docker/:/var/lib/docker:ro&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器可写层与镜像层数据在这里，&lt;code&gt;container_fs_usage_bytes&lt;/code&gt; 靠它统计&lt;/td&gt;
&lt;td&gt;只统计占用大小，不动容器数据&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/dev/disk/:/dev/disk:ro&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;部分环境下统计块设备信息需要，可选&lt;/td&gt;
&lt;td&gt;同上，仅识别设备&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;权限方面，cAdvisor 要访问宿主机大量受保护的路径与 cgroup 接口，通常直接给 &lt;code&gt;privileged: true&lt;/code&gt;，或者用一组等价的 capability 与设备授权替代——前者省事，后者更克制，生产环境可以按需收紧。所有挂载坚持只读是底线：监控工具只需要「看」，任何写权限都是多余的风险面。&lt;/p&gt;
&lt;p&gt;启动后打开 &lt;code&gt;http://localhost:8080&lt;/code&gt; 能看到自带 UI，可以按容器逐个点进去看实时曲线，先确认数据在正常采集，再往下接 Prometheus。命令行侧也可以快速验证一遍：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose ps
# 数一下容器指标有多少条，有输出说明采集正常
curl -s http://localhost:8080/metrics | grep -c &quot;^container_&quot;
# 随便看一条内存指标，确认标签里带容器名
curl -s http://localhost:8080/metrics | grep container_memory_working_set_bytes | head -n 5
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第二条命令如果能看到带 &lt;code&gt;name=&quot;/某容器名&quot;&lt;/code&gt; 标签的输出，说明挂载与权限都对了；如果指标寥寥无几或者压根没有容器名，多半是挂载缺项，直接跳到文末排障部分逐项核对。&lt;/p&gt;
&lt;p&gt;:::warning
cAdvisor 的 8080 端口&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;没有任何鉴权，却能看到全部容器的名称、镜像与资源用量&amp;lt;/span&amp;gt;，绝不能直接暴露到公网。上面的 compose 把端口绑在 &lt;code&gt;127.0.0.1&lt;/code&gt; 上，只供本机访问与抓取；确实要远程看，也应该套一层带认证的反向代理，或者干脆只看 Grafana 面板。
:::&lt;/p&gt;
&lt;h2&gt;接入 Prometheus&lt;/h2&gt;
&lt;p&gt;cAdvisor 的指标端点就是根路径下的 &lt;code&gt;/metrics&lt;/code&gt;，Prometheus 侧只需加一个抓取任务：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;scrape_configs:
  - job_name: cadvisor
    static_configs:
      - targets: [&quot;cadvisor:8080&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;整套 Prometheus 的部署在 &lt;a href=&quot;/posts/docker-monitoring-prometheus/&quot;&gt;Docker 监控篇&lt;/a&gt;里已经搭好，这里加一个 job 即可。如果 Prometheus 和 cAdvisor 不在同一个 Compose 网络里，把 targets 换成宿主机地址加映射端口即可。&lt;/p&gt;
&lt;p&gt;抓回来的每条指标都带一组标签，其中最常用的是 &lt;code&gt;name&lt;/code&gt;——容器名。按容器筛选、聚合、画图，全靠它。比如只看名为 myapp 的容器，就是 &lt;code&gt;name=&quot;myapp&quot;&lt;/code&gt;；而 &lt;code&gt;name!=&quot;&quot;&lt;/code&gt; 可以滤掉没有容器名的根 cgroup 汇总行，画 Top 榜时几乎必用。&lt;/p&gt;
&lt;h2&gt;关键指标&lt;/h2&gt;
&lt;p&gt;cAdvisor 暴露的指标很多，日常真正要盯的就下面这些：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;指标&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;使用要点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;container_cpu_usage_seconds_total&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器累计消耗的 CPU 时间（秒）&lt;/td&gt;
&lt;td&gt;计数器型，用 &lt;code&gt;rate()&lt;/code&gt; 换算成核数使用率&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;container_memory_working_set_bytes&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;工作集内存：当前活跃使用、不可回收的内存&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;判断容器真实内存占用看它，比 usage 准&amp;lt;/span&amp;gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;container_memory_usage_bytes&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;内存总用量，包含 page cache&lt;/td&gt;
&lt;td&gt;数值偏大，做告警容易误报&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;container_network_receive_bytes_total&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;网卡累计接收字节数&lt;/td&gt;
&lt;td&gt;按 &lt;code&gt;interface&lt;/code&gt; 标签区分网卡，&lt;code&gt;rate()&lt;/code&gt; 算速率&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;container_network_transmit_bytes_total&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;网卡累计发送字节数&lt;/td&gt;
&lt;td&gt;同上&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;container_fs_usage_bytes&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器文件系统用量&lt;/td&gt;
&lt;td&gt;盯可写层异常膨胀很好用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;container_last_seen&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器最近一次被采集到的时间戳&lt;/td&gt;
&lt;td&gt;判断容器是否还活着、采集是否中断&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个常用 PromQL 示例（语法细节见 &lt;a href=&quot;/posts/monitoring-promql/&quot;&gt;PromQL 篇&lt;/a&gt;）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 某容器最近 5 分钟的 CPU 使用率（单位：核）
rate(container_cpu_usage_seconds_total{name=&quot;myapp&quot;}[5m])

# 内存工作集占用最高的 5 个容器
topk(5, container_memory_working_set_bytes{name!=&quot;&quot;})

# 某容器 eth0 网卡的接收速率
rate(container_network_receive_bytes_total{name=&quot;myapp&quot;, interface=&quot;eth0&quot;}[5m])
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;回到开头的问题：把第二条查询放进 Grafana 面板，再拉出过去 24 小时的时间范围，那个内存曲线一路向上的容器，就是偷吃内存的元凶——配合它的发布时间点，基本能锁定是哪次发布引入的。&lt;/p&gt;
&lt;p&gt;再补两个实战中高频的查询。一个是内存占上限的比例，光看绝对值不够，离上限还有多远才是告警的关键——前提是给容器设了内存上限（limit 为 0 表示没设上限，要先滤掉）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 各容器内存工作集占自身上限的百分比
container_memory_working_set_bytes{name!=&quot;&quot;}
  / container_spec_memory_limit_bytes{name!=&quot;&quot;} * 100
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;另一个是盯磁盘：容器可写层只涨不缩通常是日志或临时文件没人清理，按速率看哪个容器在快速吞磁盘：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 各容器文件系统用量的增长速率
rate(container_fs_usage_bytes{name!=&quot;&quot;}[1h])
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;先说清代价：开销与指标基数&lt;/h2&gt;
&lt;p&gt;cAdvisor 不是免费的午餐。容器数量一多，它自身的 CPU 与内存开销就不能忽略；更麻烦的是指标基数：每个容器乘以每块网卡、每个挂载点、每个 CPU 核，标签组合成倍膨胀，Prometheus 的存储与查询都会被拖累。&lt;/p&gt;
&lt;p&gt;应对办法是在 Prometheus 抓取侧做保留策略，把用不上的指标提前 drop 掉：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;scrape_configs:
  - job_name: cadvisor
    static_configs:
      - targets: [&quot;cadvisor:8080&quot;]
    metric_relabel_configs:
      - source_labels: [__name__]
        regex: &quot;container_tasks_state|container_memory_failures_total|container_blkio_device_usage_total&quot;
        action: drop
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;原则是：只留你真的会画图、会告警的指标，其余在入口处丢弃，别等入库之后再心疼存储。如果单机指标量实在压不住，可以考虑把抓取间隔放宽到 30 秒，或者换用对高基数更友好的存储方案，比如 &lt;a href=&quot;/posts/monitoring-victoriametrics/&quot;&gt;VictoriaMetrics 篇&lt;/a&gt;里讲的替代路线。&lt;/p&gt;
&lt;p&gt;还有一类容易被忽视的基数来源：短命容器。CI 构建、定时任务这类跑完就退的容器，会不断产生新的标签组合，旧序列虽然不再更新，却依然占着索引直到数据过期。这也是前面 &lt;code&gt;container_last_seen&lt;/code&gt; 的用处之一——定期看一眼最近还有哪些容器「出现过」，能帮你判断基数膨胀到底是业务真的多，还是被一堆一次性容器撑起来的。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;抓不到指标，或指标里没有容器数据。&lt;/strong&gt; 先打开 &lt;code&gt;http://localhost:8080/metrics&lt;/code&gt; 看有没有 &lt;code&gt;container_&lt;/code&gt; 前缀的输出。如果基本为空，十有八九是挂载问题：&lt;code&gt;/sys&lt;/code&gt; 没挂对，cgroup 计数器读不到；&lt;code&gt;/var/lib/docker&lt;/code&gt; 没挂，文件系统类指标全无；&lt;code&gt;privileged&lt;/code&gt; 没给，关键路径权限不足。排查顺序是先 &lt;code&gt;docker logs cadvisor&lt;/code&gt; 看报错，再 &lt;code&gt;docker exec&lt;/code&gt; 进容器确认 &lt;code&gt;/rootfs&lt;/code&gt;、&lt;code&gt;/sys/fs/cgroup&lt;/code&gt; 这些路径真实可读，逐项对着上面的挂载表补齐。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;内存数值和 docker stats 对不上。&lt;/strong&gt; 这是口径问题，不是 bug。&lt;code&gt;docker stats&lt;/code&gt; 显示的内存用量接近工作集口径，而 &lt;code&gt;container_memory_usage_bytes&lt;/code&gt; 把 page cache 也算了进去，数值天然偏大。page cache 是可回收的，文件读写频繁的容器这一项会涨得很高，但并不代表真的吃紧。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;拿 usage 指标做内存告警，会被 page cache 反复误报坑得很惨&amp;lt;/span&amp;gt;——面板和告警统一改用 &lt;code&gt;container_memory_working_set_bytes&lt;/code&gt;，两边就对上了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;指标太多，Prometheus 变慢。&lt;/strong&gt; 症状是查询超时、磁盘涨得飞快。先去 Prometheus 的 Status 页面看每个 job 的样本量，确认大头是不是 cadvisor。然后回到抓取配置，用上一节的 &lt;code&gt;metric_relabel_configs&lt;/code&gt; 把低价值指标 drop 掉；还不够就缩短本地保留时长、把长期数据下沉到远程存储。基数问题只能在入口治理，入库之后再删既慢又不彻底。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;cAdvisor 补齐了容器这一层的可观测性：部署就是一组只读挂载加一个抓取任务，关键是想清楚三件事——内存看 working set 而不是 usage、8080 端口绝不裸奔公网、指标在抓取入口就做好取舍。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;宿主机看 node_exporter，容器看 cAdvisor，两层曲线合起来，资源问题才算看全&amp;lt;/span&amp;gt;。下一篇我们把这些指标接上 Alertmanager，让曲线异常的时候能主动找到你。&lt;/p&gt;
</content:encoded></item><item><title>监控与可观测性：先分清坏没坏，再追问为什么坏</title><link>https://www.anexns.cloudns.org/posts/monitoring-concepts/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-concepts/</guid><description>从指标、日志与链路三大支柱出发，讲清 USE、RED、四大黄金信号、SLO 与错误预算，并给出小规模自建场景的务实落地顺序。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;凌晨三点出问题，你打开面板能看到什么？&lt;/h2&gt;
&lt;p&gt;凌晨三点，手机突然响了：网站打不开。你睡眼惺忪地打开监控面板，CPU 曲线正常，内存还有富余，磁盘也没满，可用户就是无法下单。再过几分钟，群里开始有人问“是不是数据库挂了”“是不是新版本有问题”“到底慢在哪一步”。这时你会发现，知道“出事了”只是第一步，真正耗时间的是回答后面一连串问题：影响了多少人？从什么时候开始？错误集中在哪个接口？请求卡在网关、应用、数据库还是第三方服务？&lt;/p&gt;
&lt;p&gt;这篇文章先不急着安装某个工具，而是把监控与可观测性的基本概念理顺：监控负责及时发现异常，可观测性负责在异常发生后追问原因；指标、日志、链路各解决什么问题；USE、RED 与四大黄金信号该怎么用；SLI、SLO、SLA 和错误预算又有什么区别。把这张地图看懂，后面选 Prometheus、Grafana、Loki 还是 OpenTelemetry，就不会只是照着教程堆组件。&lt;/p&gt;
&lt;p&gt;参考文档：https://opentelemetry.io/docs/concepts/observability-primer/&lt;/p&gt;
&lt;h2&gt;监控和可观测性，回答的不是同一个问题&lt;/h2&gt;
&lt;p&gt;监控（Monitoring）更像体检报告和烟雾报警器。它预先定义一组指标和阈值，持续判断系统是否处于预期状态，例如 CPU 使用率是否过高、HTTP 5xx 是否激增、证书还剩多少天到期。监控最擅长回答的是：&lt;strong&gt;坏没坏、坏了多少、从何时开始坏&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;可观测性（Observability）则强调系统对外输出的数据是否足够丰富，能否让运维者在没有预先写好问题清单的情况下，从外部现象反推内部状态。它更关注：&lt;strong&gt;为什么坏、坏在哪里、影响了谁、下一步查什么&lt;/strong&gt;。一个系统不是“装了 Grafana 就有可观测性”，也不是“日志很多就一定查得清”。关键在于数据之间能不能关联，问题出现时能不能沿着时间、服务、请求一路追下去。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;监控&lt;/th&gt;
&lt;th&gt;可观测性&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;核心问题&lt;/td&gt;
&lt;td&gt;系统是否正常&lt;/td&gt;
&lt;td&gt;系统为什么不正常&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;典型手段&lt;/td&gt;
&lt;td&gt;指标、阈值、健康检查、告警&lt;/td&gt;
&lt;td&gt;指标、日志、链路、事件与上下文关联&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合场景&lt;/td&gt;
&lt;td&gt;已知故障模式、容量与可用性巡检&lt;/td&gt;
&lt;td&gt;未知故障、复杂调用链、偶发慢请求&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;输出结果&lt;/td&gt;
&lt;td&gt;红绿状态、趋势曲线、告警通知&lt;/td&gt;
&lt;td&gt;可下钻的证据链与定位路径&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;两者不是替代关系。没有监控，异常可能没人知道；没有可观测性，知道了异常也可能只能靠猜。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;监控负责发现问题，可观测性负责解释问题。&amp;lt;/span&amp;gt;对小团队来说，目标不是把概念做满，而是让每一次故障都能更快地从“有人报错”走到“证据指向某个环节”。&lt;/p&gt;
&lt;h2&gt;三大支柱：指标、日志与链路&lt;/h2&gt;
&lt;p&gt;业内常把可观测性数据分成三大支柱：指标（Metrics）、日志（Logs）和链路追踪（Traces）。它们观察的是同一套系统，只是粒度、成本和用途不同。&lt;/p&gt;
&lt;h3&gt;指标：便宜、聚合，适合长期趋势和告警&lt;/h3&gt;
&lt;p&gt;指标是随时间变化的数值，例如每秒请求数、CPU 使用率、内存占用、队列长度、HTTP 错误数。指标通常按固定间隔采集，并按服务、实例、状态码等标签聚合，因此查询快、存储成本相对可控，特别适合画趋势图和触发告警。&lt;/p&gt;
&lt;p&gt;指标的弱点是信息被聚合了。你能看到 &lt;code&gt;/checkout&lt;/code&gt; 接口过去五分钟的 P95 延迟升到 2 秒，却看不到某一个失败请求到底传了什么参数、在哪一层报错。指标像医院的体温、血压和心率，适合持续观察，却不能代替完整病历。&lt;/p&gt;
&lt;h3&gt;日志：细节最全，但量大且需要结构&lt;/h3&gt;
&lt;p&gt;日志记录离散事件：一次请求何时到达、调用了哪个接口、返回什么状态码、抛出了什么异常、关联的订单或任务是什么。故障细节往往藏在日志里，尤其是错误堆栈、业务状态变化和外部依赖返回结果。&lt;/p&gt;
&lt;p&gt;日志的问题是量大、格式不一、检索成本高。若日志只是随手打印的文本，故障时只能靠关键词碰运气；若能统一成结构化字段，带上时间、服务、级别、请求 ID、接口和错误码，日志就会从“文本仓库”变成可筛选的证据库。日志适合回答“这一件事当时发生了什么”，但不适合长期计算全局趋势，那是指标的工作。&lt;/p&gt;
&lt;h3&gt;链路：把一次请求的全程串起来&lt;/h3&gt;
&lt;p&gt;链路追踪记录一次请求经过的所有环节。一个 Trace 由多个 Span 组成，每个 Span 表示一段工作，例如网关转发、应用处理、SQL 查询、Redis 访问或调用支付接口。把这些 Span 按父子关系和耗时排开，就能看到请求总共花了 800 ms，其中 620 ms 卡在一条 SQL 上，还是 500 ms 等在第三方接口。&lt;/p&gt;
&lt;p&gt;链路最擅长定位“慢在哪”和“错误从哪一层冒出来”，尤其适合微服务与多层调用。但它的采集、存储和采样成本通常高于指标，数据模型也更复杂。对于只有一两台服务器、几个容器的自建场景，未必需要第一天就上完整链路系统；先把指标和日志做好，往往收益更直接。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;支柱&lt;/th&gt;
&lt;th&gt;记录什么&lt;/th&gt;
&lt;th&gt;最擅长回答&lt;/th&gt;
&lt;th&gt;主要代价&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Metrics&lt;/td&gt;
&lt;td&gt;聚合后的数值时间序列&lt;/td&gt;
&lt;td&gt;趋势如何、何时异常、是否该告警&lt;/td&gt;
&lt;td&gt;细节少，受高基数影响大&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Logs&lt;/td&gt;
&lt;td&gt;一条条离散事件&lt;/td&gt;
&lt;td&gt;某次请求或任务当时发生了什么&lt;/td&gt;
&lt;td&gt;数据量大、检索与治理成本高&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Traces&lt;/td&gt;
&lt;td&gt;一次请求的完整调用路径&lt;/td&gt;
&lt;td&gt;慢在哪、错在哪一层&lt;/td&gt;
&lt;td&gt;接入与采样复杂、存储成本较高&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;三者之间还需要一根线把它们串起来：时间戳、服务名、版本、实例、请求 ID 或 Trace ID。没有统一上下文，面板、日志和链路各说各话；有了关联，才能从一条告警跳到对应时间段的日志，再跳到具体请求链路。这也是本系列后面讲 &lt;a href=&quot;/posts/monitoring-prometheus/&quot;&gt;Prometheus 指标体系&lt;/a&gt; 时，会反复强调命名和标签规范的原因。&lt;/p&gt;
&lt;h2&gt;看资源用 USE，看服务用 RED&lt;/h2&gt;
&lt;p&gt;面对几十张图，新手最容易陷入“什么都看、什么都看不出”的状态。两个经典方法可以帮你建立观察顺序：USE 方法看资源，RED 方法看服务。&lt;/p&gt;
&lt;p&gt;USE 方法由 Brendan Gregg 提出，针对每一类资源检查三件事：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Utilization（利用率）&lt;/strong&gt;：资源有多忙，例如 CPU 使用率、磁盘利用率、网络带宽占用。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Saturation（饱和度）&lt;/strong&gt;：有多少工作在排队，例如 CPU 运行队列、磁盘等待、连接池排队数。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Errors（错误）&lt;/strong&gt;：资源本身发生了多少错误，例如磁盘 I/O 错误、网卡丢包、连接失败。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;只看利用率并不够。一个磁盘利用率 70% 时可能已经排队严重，一个连接池使用率不高也可能因为错误而不可用。饱和度往往比利用率更早暴露“快撑不住了”的信号。&lt;/p&gt;
&lt;p&gt;RED 方法则站在服务请求的角度，关注：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Rate（请求量）&lt;/strong&gt;：每秒收到多少请求。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Errors（错误率）&lt;/strong&gt;：失败请求占多少，错误类型是什么。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Duration（耗时分布）&lt;/strong&gt;：请求要多久，重点看 P95、P99，而不是只看平均值。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Google SRE 提出的四大黄金信号与 RED 高度相通，包括延迟（Latency）、流量（Traffic）、错误（Errors）和饱和度（Saturation）。可以把它们理解为服务健康检查的最小集合：用户请求多不多、快不快、错不错、系统离成功能上限还有多远。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方法&lt;/th&gt;
&lt;th&gt;观察对象&lt;/th&gt;
&lt;th&gt;核心问题&lt;/th&gt;
&lt;th&gt;典型指标&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;USE&lt;/td&gt;
&lt;td&gt;CPU、内存、磁盘、网络、连接池&lt;/td&gt;
&lt;td&gt;资源是否忙、是否排队、是否出错&lt;/td&gt;
&lt;td&gt;利用率、队列长度、I/O 错误&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;RED&lt;/td&gt;
&lt;td&gt;API、Web 服务、任务消费者&lt;/td&gt;
&lt;td&gt;请求是否成功、是否足够快&lt;/td&gt;
&lt;td&gt;QPS、错误率、P95/P99 延迟&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;四大黄金信号&lt;/td&gt;
&lt;td&gt;整个服务&lt;/td&gt;
&lt;td&gt;用户体验与容量是否恶化&lt;/td&gt;
&lt;td&gt;延迟、流量、错误、饱和度&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;实战中不要只盯平均延迟。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;平均值会把长尾请求藏起来：99 个请求只要 10 ms，1 个请求等了 10 秒，平均值看起来依然不高，但那 1% 的用户已经无法忍受。&amp;lt;/span&amp;gt;这也是为什么耗时要用直方图和分位数表达，而不是只采集一个平均数。&lt;/p&gt;
&lt;p&gt;如果你已经在用 Linux 自带工具和脚本巡检，可以把这套方法与 &lt;a href=&quot;/posts/linux-server-monitoring/&quot;&gt;Linux 服务器监控&lt;/a&gt; 对照起来看：前者解决“机器层面先看什么”，USE 与 RED 则帮你把观察范围从机器扩展到服务。&lt;/p&gt;
&lt;h2&gt;SLI、SLO、SLA：先量出来，再定目标，最后才谈承诺&lt;/h2&gt;
&lt;p&gt;可用性讨论最容易混淆三个词：SLI、SLO 和 SLA。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;SLI（Service Level Indicator）&lt;/strong&gt; 是服务质量的量化指标，例如请求成功率、P95 延迟低于 300 ms 的请求占比、数据处理新鲜度。它回答“实际表现是多少”。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;SLO（Service Level Objective）&lt;/strong&gt; 是团队给自己定的内部目标，例如 30 天内请求成功率不低于 99.9%，或 95% 的请求在 300 ms 内完成。它回答“我们希望达到什么水平”。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;SLA（Service Level Agreement）&lt;/strong&gt; 是对客户或业务方的正式协议，通常带补偿、赔付或合同后果。它回答“没做到要付出什么代价”。SLA 一般应比 SLO 留有余量，因为等 SLA 被打破时，往往已经不是内部预警，而是对外违约。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;名词&lt;/th&gt;
&lt;th&gt;本质&lt;/th&gt;
&lt;th&gt;示例&lt;/th&gt;
&lt;th&gt;面向对象&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;SLI&lt;/td&gt;
&lt;td&gt;测量值&lt;/td&gt;
&lt;td&gt;过去 30 天成功率 99.93%&lt;/td&gt;
&lt;td&gt;系统与团队&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SLO&lt;/td&gt;
&lt;td&gt;内部目标&lt;/td&gt;
&lt;td&gt;30 天成功率不低于 99.9%&lt;/td&gt;
&lt;td&gt;工程与产品团队&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SLA&lt;/td&gt;
&lt;td&gt;正式承诺&lt;/td&gt;
&lt;td&gt;低于 99.5% 按比例补偿&lt;/td&gt;
&lt;td&gt;客户与合同双方&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;SLO 最有价值的副产品是&lt;strong&gt;错误预算（Error Budget）&lt;/strong&gt;。若 30 天成功率 SLO 是 99.9%，允许失败的比例就是 0.1%。换算成停机时间，30 天大约可容忍 43 分钟；换算成请求量，若一个月有 100 万次请求，大约允许 1000 次失败。错误预算不是鼓励故障，而是把可靠性变成可管理的额度：预算充足时可以更快发布，预算快耗尽时就应暂停高风险变更，优先修复稳定性问题。&lt;/p&gt;
&lt;p&gt;定 SLO 时要从用户感受出发，而不是从“机器活着”出发。进程在线、端口能通，并不等于用户能登录、下单或上传文件。对于自建服务，先给关键路径定一两个简单 SLO 就够了，例如“首页与核心 API 30 天成功率不低于 99.9%”“P95 延迟不超过 800 ms”。目标太多、口径不清，最后只会变成墙上的数字。&lt;/p&gt;
&lt;h2&gt;告警哲学：为症状告警，每条都必须能行动&lt;/h2&gt;
&lt;p&gt;告警不是越多越好。真正好的告警应该满足三个条件：它代表用户正在受影响或即将受影响；值班人收到后知道先做什么；如果不处理，后果明确。换句话说，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;告警应基于症状，而不是把每一个可能的原因都做成报警。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;例如“CPU 使用率超过 90%”只是一个原因信号。CPU 高可能来自正常批处理，也可能完全不影响用户；反过来，CPU 不高时，应用也可能因为数据库锁、线程池耗尽而不可用。更值得告警的是“过去 5 分钟结账接口错误率超过 5%”“P99 延迟持续高于 2 秒”“SLO 错误预算燃烧速度异常”。这些是用户能感知到的症状。至于根因是 CPU、磁盘还是某条 SQL，应该通过仪表盘、日志和链路继续下钻，而不是让每一种猜测都半夜叫醒人。&lt;/p&gt;
&lt;p&gt;每条告警还应附带处理入口：对应的仪表盘链接、常用查询、最近变更、第一步检查和升级路径。收到告警后还要翻文档、问同事、找面板，这条告警就没有设计完整。对于不要求立即处理的问题，应进入工单、日报或周报，而不是占用紧急告警通道。&lt;/p&gt;
&lt;p&gt;:::warning
不要一上来就追求“全家桶”。先把指标采集、仪表盘和症状告警跑通，再补结构化日志与检索；链路追踪等到调用关系真的复杂、慢请求靠日志查不清时再引入。组件越多，维护成本越高，告警噪音也越容易失控。
:::&lt;/p&gt;
&lt;p&gt;告警分级同样重要。核心服务不可用、数据损坏风险、错误预算快速燃烧，属于需要立即响应的级别；单副本异常但服务仍可用、容量预计一周后不足，可以先通知并安排处理；纯信息类变化只记录不打扰人。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;如果每条告警都喊“紧急”，最终结果不是系统更可靠，而是所有人都学会忽略告警。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;对于已经在用轻量面板的自建场景，&lt;a href=&quot;/posts/selfhost-komari/&quot;&gt;Komari 探针&lt;/a&gt; 这类工具适合先解决节点在线、资源水位和基础通知；当你需要更细的服务指标、告警规则和长期趋势时，再进入 Prometheus 与 Alertmanager 的体系。工具升级应由问题驱动，而不是由“别人都在用”驱动。&lt;/p&gt;
&lt;h2&gt;高基数：为什么几个标签能把指标系统拖垮&lt;/h2&gt;
&lt;p&gt;高基数（High Cardinality）是新手最容易踩的坑。指标系统中的每组唯一标签组合，都会生成一条时间序列。假设一个指标有 20 个实例、30 个接口、5 个状态码，组合数是 20 × 30 × 5 = 3000 条序列，看起来还可控。若再加上 10 万个用户 ID，序列数立刻变成 3 亿，采集、索引、内存和查询都会被拖垮。&lt;/p&gt;
&lt;p&gt;问题不在于“标签不能用”，而在于标签值必须相对有限且稳定。适合做标签的通常是服务名、实例、接口模板、状态码、地区、版本等枚举型字段；不适合的是用户 ID、订单号、请求 ID、完整 URL、IP 地址、错误消息原文等近乎无限增长的值。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;适合放进指标标签吗&lt;/th&gt;
&lt;th&gt;原因&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;service=&quot;api&quot;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;适合&lt;/td&gt;
&lt;td&gt;取值有限，便于聚合&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;status=&quot;500&quot;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;适合&lt;/td&gt;
&lt;td&gt;状态码范围可控&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;route=&quot;/orders/:id&quot;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;适合&lt;/td&gt;
&lt;td&gt;使用路由模板而非真实 ID&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;user_id=&quot;123456&quot;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不适合&lt;/td&gt;
&lt;td&gt;用户越多，序列越多&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;request_id=&quot;...&quot;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不适合&lt;/td&gt;
&lt;td&gt;每个请求都产生新组合&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;url=&quot;/orders/98765&quot;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不适合&lt;/td&gt;
&lt;td&gt;路径参数导致组合爆炸&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;请求级细节应该放在日志和链路里，通过请求 ID 检索，而不是塞进指标标签。指标负责聚合与趋势，日志和链路负责个体细节，这正是三大支柱分工的体现。若你用 Docker 部署监控组件，也要留意采集目标和标签增长对资源的影响，相关思路可与 &lt;a href=&quot;/posts/docker-monitoring-prometheus/&quot;&gt;Docker 监控实战&lt;/a&gt; 一起看。&lt;/p&gt;
&lt;h2&gt;小规模自建场景：先指标加日志，链路按需补&lt;/h2&gt;
&lt;p&gt;家用服务器、个人 VPS 和小团队业务，没必要复制大厂的完整平台。更务实的顺序是：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;先做指标&lt;/strong&gt;：覆盖主机资源、容器状态、关键服务请求量、错误率、延迟和外部可用性探测。确保故障能被发现，趋势能回看。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;再做日志&lt;/strong&gt;：统一时间与时区，保留服务名、级别、请求 ID 等结构化字段，设置轮转与保留周期。确保故障发生后能查到现场。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;补好告警&lt;/strong&gt;：只为用户症状和明确风险设置紧急告警，配上仪表盘与处理步骤，定期删掉无人响应的噪音规则。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;最后按需上链路&lt;/strong&gt;：当系统出现跨服务调用、第三方依赖多、慢请求难以定位时，再引入 OpenTelemetry 与链路后端，并用采样控制成本。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;存储保留也要分层：高频指标保留一到四周用于排障，关键趋势可降采样后保留更久；日志按价值设置天数，不要无限堆在本机磁盘；链路可只采样错误请求与慢请求。监控系统本身也要被监控，至少要知道采集器是否存活、磁盘还剩多少、告警通道是否可用。否则最讽刺的情况就是：业务系统凌晨挂了，而监控系统早在三天前就因为磁盘写满悄悄停了。&lt;/p&gt;
&lt;h2&gt;常见误区&lt;/h2&gt;
&lt;h3&gt;误区一：装了面板，就等于有可观测性&lt;/h3&gt;
&lt;p&gt;面板只是展示层。若指标没有统一命名、日志没有请求 ID、告警点不开对应证据，面板再漂亮也只能让人“看个热闹”。可观测性体现在故障时能不能快速下钻和验证假设。&lt;/p&gt;
&lt;h3&gt;误区二：数据越多越好&lt;/h3&gt;
&lt;p&gt;无节制采集高频指标、全量日志和全量链路，会带来存储、查询和维护成本。数据策略应围绕问题设计：哪些指标用于告警，哪些日志用于审计与排障，哪些请求值得采样。能回答问题的数据才是资产，否则只是账单。&lt;/p&gt;
&lt;h3&gt;误区三：只监控机器，不监控用户路径&lt;/h3&gt;
&lt;p&gt;CPU、内存正常，不代表登录、支付、上传都正常。除了主机指标，还应有外部黑盒探测和关键业务接口检查。监控视角要从“服务器活着”推进到“用户能完成任务”。&lt;/p&gt;
&lt;h3&gt;误区四：阈值拍脑袋，告警靠复制&lt;/h3&gt;
&lt;p&gt;把网上模板的 CPU 80%、内存 90% 原样搬来，往往与自己的业务节奏不符。阈值应结合历史基线、容量变化和用户影响调整，并通过复盘不断删改。没有负责人、没有处理动作、长期无人响应的告警，应降级或删除。&lt;/p&gt;
&lt;h3&gt;误区五：把可用性目标定成 100%&lt;/h3&gt;
&lt;p&gt;100% 可用既不现实，也会让团队不敢发布和维护。SLO 与错误预算的意义，就是承认故障不可避免，并把可靠性投入放在最影响用户的地方。与其追求口号，不如先守住一个可测量、可复盘的 99.9%。&lt;/p&gt;
&lt;h2&gt;小结：先建立证据链，再追求工具齐全&lt;/h2&gt;
&lt;p&gt;监控与可观测性的核心，不是某个产品名，而是一套分工：指标告诉你趋势和异常，日志保留现场细节，链路还原请求路径；USE 帮你看资源，RED 与四大黄金信号帮你看服务；SLI 量化现实，SLO 设定目标，错误预算决定变更节奏；告警只打扰真正需要行动的时刻。&lt;/p&gt;
&lt;p&gt;本系列接下来会按落地顺序展开：先用 Prometheus 建立指标采集与查询，再补 Exporter 与 Grafana 仪表盘，随后接入 Alertmanager 做像样的告警，然后讲日志聚合、黑盒探测、OpenTelemetry 链路追踪，最后回到 SLO 实践与日常巡检。第一步仍然是这篇的概念地图——下次凌晨三点被告警叫醒时，你至少要知道先看哪类数据、每个数字能证明什么、又不能证明什么。&lt;/p&gt;
</content:encoded></item><item><title>监控与可观测性：Exporter 生态选型——给老软件配上 Prometheus 的翻译插头</title><link>https://www.anexns.cloudns.org/posts/monitoring-exporters/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-exporters/</guid><description>Prometheus 自己不会说 MySQL、Redis、交换机的「方言」，Exporter 就是中间的翻译层：本文把主流 Exporter 的选型、部署注意、最小权限账号与 Pushgateway 的适用边界一次讲清。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先打个比方：Exporter 是万能翻译插头&lt;/h2&gt;
&lt;p&gt;出国旅行时，插头制式不对，电器再好也用不了——你需要的不是换电器，而是一个转换插头。Prometheus 面对存量软件时是同样的处境：它只认一种「插头」，即 HTTP 拉取 &lt;code&gt;/metrics&lt;/code&gt; 返回的文本 exposition format；而 MySQL 说的是 &lt;code&gt;SHOW GLOBAL STATUS&lt;/code&gt;，Redis 说的是 &lt;code&gt;INFO&lt;/code&gt;，交换机说的是 SNMP，物理机硬件说的是 IPMI——全是互不相通的方言。&lt;/p&gt;
&lt;p&gt;Exporter 就是夹在中间的翻译插头：它自己连上目标软件已有的状态接口，把读到的状态翻译成 Prometheus 能懂的 &lt;code&gt;/metrics&lt;/code&gt; 文本，挂在一个 HTTP 端口上等 Prometheus 来抓。目标软件一行代码不用改，监控就接上了。本篇把主流 Exporter 的选型讲透：每个盯什么指标、镜像从哪来、部署时有哪些坑，最后再讲清两个常被用错的东西——Pushgateway 的边界，以及「要不要自己写一个 Exporter」。&lt;/p&gt;
&lt;p&gt;参考文档：https://prometheus.io/docs/instrumenting/exporters/&lt;/p&gt;
&lt;h2&gt;先对齐概念：什么算 Exporter，什么不算&lt;/h2&gt;
&lt;p&gt;Prometheus 官方把接入方式分成两类。一类是应用自己埋点（instrumentation）：代码里引入 client library，直接暴露 &lt;code&gt;/metrics&lt;/code&gt;，指标语义由开发者定义，这是最理想的形态。另一类就是 Exporter：面向那些改不了代码、或者本身不是你开发的软件（数据库、中间件、硬件、操作系统），由一个独立进程做协议翻译。本系列前面写的 node_exporter 就是最典型的 Exporter——把 &lt;code&gt;/proc&lt;/code&gt;、&lt;code&gt;/sys&lt;/code&gt; 里的内核状态翻译成指标。&lt;/p&gt;
&lt;p&gt;判断一个组件是不是 Exporter，看两点就够了：第一，它对上游说上游的协议（SQL、INFO 命令、SNMP、IPMI），对下游只暴露 &lt;code&gt;/metrics&lt;/code&gt;；第二，它是无状态的翻译层，自己不存数据，抓取时才实时去问上游。所以 Exporter 挂了不会丢历史数据，只会在那段时间留下一个抓取失败的空洞，这也是排障时要先分清「Exporter 进程问题」还是「上游问题」的原因。&lt;/p&gt;
&lt;h2&gt;选型全景：逐个过一遍&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Exporter&lt;/th&gt;
&lt;th&gt;来源 / 镜像&lt;/th&gt;
&lt;th&gt;主要盯什么&lt;/th&gt;
&lt;th&gt;部署注意&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;mysqld_exporter&lt;/td&gt;
&lt;td&gt;官方 prom/mysqld-exporter&lt;/td&gt;
&lt;td&gt;连接数、QPS、慢查询、InnoDB 缓冲池、主从延迟&lt;/td&gt;
&lt;td&gt;必须建只读监控账号；多实例用 multi-target 模式一个进程管多台&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;postgres_exporter&lt;/td&gt;
&lt;td&gt;官方 prometheus-community/postgres-exporter&lt;/td&gt;
&lt;td&gt;连接与会话、事务提交/回滚、缓存命中率、复制延迟、锁等待&lt;/td&gt;
&lt;td&gt;监控账号需要 &lt;code&gt;pg_monitor&lt;/code&gt; 角色；自定义查询用 queries.yaml 扩展&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;redis_exporter&lt;/td&gt;
&lt;td&gt;社区主流 oliver006/redis_exporter&lt;/td&gt;
&lt;td&gt;内存使用与碎片率、命中率、连接数、键空间、主从复制偏移&lt;/td&gt;
&lt;td&gt;支持单机/集群/哨兵；密码走环境变量注入，别写进抓取参数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;mongodb_exporter&lt;/td&gt;
&lt;td&gt;Percona 版 percona/mongodb_exporter&lt;/td&gt;
&lt;td&gt;操作计数、连接、复制集状态、WiredTiger 缓存&lt;/td&gt;
&lt;td&gt;官方旧版早已停更，别用错仓库；账号需 clusterMonitor 等只读角色&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;snmp_exporter&lt;/td&gt;
&lt;td&gt;官方 prom/snmp-exporter&lt;/td&gt;
&lt;td&gt;交换机/路由器端口流量、错误包、光模块、UPS 与打印机状态&lt;/td&gt;
&lt;td&gt;先用 generator 把厂商 MIB 生成 snmp.yml；按 module + auth 分组抓取&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ipmi_exporter&lt;/td&gt;
&lt;td&gt;社区 prometheus-community/ipmi-exporter&lt;/td&gt;
&lt;td&gt;物理机温度、风扇转速、电源状态、电压&lt;/td&gt;
&lt;td&gt;需要带外管理口（BMC）可达；本机模式也可走本地 IPMI 设备&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;consul_exporter&lt;/td&gt;
&lt;td&gt;官方 prom/consul-exporter&lt;/td&gt;
&lt;td&gt;Consul 集群健康、服务与检查状态&lt;/td&gt;
&lt;td&gt;场景单一，服务发现本身由 Prometheus 原生支持，多数人用不上，一句带过&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个共性的点先说在前面。第一，数据库类 Exporter 都遵循同一套路：一个专用低权限账号连上去，周期性执行状态查询。账号怎么建、给什么权，是部署里最不能省的一步，下面单独讲。第二，多数 Exporter 支持两种跑法：一个进程盯一个目标（简单，适合容器编排里做 sidecar），或者用 multi-target 模式由 Prometheus 传 &lt;code&gt;target&lt;/code&gt; 参数，一个进程代理很多目标（省资源，但配置和排障更绕）。小规模环境优先前者，别一上来就给自己加难度。第三，Exporter 暴露的指标名和标签以它自己的版本为准，升级 Exporter 前先看 release notes——指标改名、删标签这类破坏性变更并不罕见，仪表盘和告警规则要跟着回归一遍，这一点和 &lt;a href=&quot;/posts/monitoring-prometheus/&quot;&gt;Prometheus 本体的版本管理&lt;/a&gt; 是同一条纪律。&lt;/p&gt;
&lt;h3&gt;数据库账号：最小权限不是口号&lt;/h3&gt;
&lt;p&gt;以 mysqld_exporter 为例，官方推荐的监控账号建法是：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE USER &apos;exporter&apos;@&apos;localhost&apos; IDENTIFIED BY &apos;&amp;lt;强密码&amp;gt;&apos; WITH MAX_USER_CONNECTIONS 3;
GRANT PROCESS, REPLICATION CLIENT, SELECT ON *.* TO &apos;exporter&apos;@&apos;localhost&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;PROCESS&lt;/code&gt; 用来看连接与线程状态，&lt;code&gt;REPLICATION CLIENT&lt;/code&gt; 用来看主从状态，&lt;code&gt;SELECT&lt;/code&gt; 是为了能读 &lt;code&gt;performance_schema&lt;/code&gt; 与 &lt;code&gt;information_schema&lt;/code&gt; 里的统计表。注意它没有写权限、没有 &lt;code&gt;SUPER&lt;/code&gt;、没有授权他人权限的能力，再加上连接数上限——这个账号就算泄露，影响面也被框住了。PostgreSQL 对应的是把监控账号加入内置的 &lt;code&gt;pg_monitor&lt;/code&gt; 角色，MongoDB 对应 &lt;code&gt;clusterMonitor&lt;/code&gt; 这类只读角色，思路完全一致：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;监控账号也是生产账号，绝不要图省事直接拿 root 或超级管理员顶上&amp;lt;/span&amp;gt;。Exporter 是常驻进程、配置里存着明文或半明文的凭据，又往往跑在相对边缘的位置，它恰恰是最容易被顺手摸到的那一环。&lt;/p&gt;
&lt;p&gt;:::warning
给 Exporter 的账号只授「读状态」所需的最小权限：MySQL 用 PROCESS + REPLICATION CLIENT + SELECT 并限制连接数，PostgreSQL 用 pg_monitor 角色，MongoDB 用 clusterMonitor 类只读角色。用 root / 超级管理员跑 Exporter，等于把最高权限凭据散布到每台被监控机器上。
:::&lt;/p&gt;
&lt;h3&gt;网络与硬件：snmp_exporter 和 ipmi_exporter&lt;/h3&gt;
&lt;p&gt;这两类和数据库 Exporter 的气质不同：它们翻译的不是软件状态，而是设备协议。snmp_exporter 的关键不在部署，而在配置生成——不同厂商、不同型号的交换机 MIB 定义不同，要先用官方的 generator 工具把厂商 MIB 编译成 &lt;code&gt;snmp.yml&lt;/code&gt;，运行时按 module 选择对应的指标集。直接拿示例配置去抓生产交换机，大概率只能拿到接口流量这种通用指标，拿不到光功率、温度这些真正值钱的厂商私有指标。&lt;/p&gt;
&lt;p&gt;ipmi_exporter 走的是服务器的带外管理口（BMC/iDRAC/iLO），哪怕操作系统已经死透，只要 BMC 还通电联网，就能读到温度、风扇、电源的硬件状态——这是它在 &lt;a href=&quot;/posts/monitoring-fleet/&quot;&gt;整机队监控&lt;/a&gt; 里不可替代的位置：软件层探针全灭时，它是最后一个还能说话的。&lt;/p&gt;
&lt;h2&gt;Pushgateway：只给短命任务用&lt;/h2&gt;
&lt;p&gt;Pushgateway 经常被误解成「另一个 Exporter」，其实它解决的是完全不同的问题：有些任务活得太短——比如一个跑三分钟的备份脚本、一个批处理作业——Prometheus 还没来得及抓，它就已经退出了，pull 模式天然抓不到。Pushgateway 允许这类短命任务在退出前把指标 push 到一个中转点，Prometheus 再从中转点拉。&lt;/p&gt;
&lt;p&gt;边界必须划清：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Pushgateway 只适合短命的批处理任务，常驻服务禁用&amp;lt;/span&amp;gt;。原因在于它推上去的指标不会随着进程死亡而消失——一个服务进程崩了，它最后 push 的「健康值 = 1」会永远躺在 Pushgateway 里，Prometheus 抓到的始终是这份僵尸数据，告警被彻底骗过去。常驻服务的存活判断必须靠 pull 模式下抓取成功与否（也就是 &lt;code&gt;up&lt;/code&gt; 指标）来做，这是 Prometheus 模型的地基，不能用 push 去绕。另外 Pushgateway 是单点且数据只在内存里，它挂了就丢光那批指标，这也决定了它只配待在监控体系的边缘，别把关键链路压在它身上。&lt;/p&gt;
&lt;p&gt;正确用法长这样：批处理脚本结尾把本次运行的结果推过去，并带上 grouping key 区分任务实例；推的时候用 PUT 覆盖同名分组，别用 POST 不断堆新分组把内存撑爆。任务失败时也要保证那行 push 能执行到（写在脚本的收尾逻辑里），否则你监控到的永远是「上次成功」。&lt;/p&gt;
&lt;h2&gt;顺带一提：textfile collector 不是 Exporter&lt;/h2&gt;
&lt;p&gt;有些状态既不在数据库里、也没有现成 Exporter——比如「昨晚备份脚本到底成功没有」「证书还有几天过期」这种本机脚本才知道的事情。这类场景不用写 Exporter，node_exporter 自带的 textfile collector 就够了：脚本把结果按 exposition format 写成 &lt;code&gt;.prom&lt;/code&gt; 文件丢进约定目录，node_exporter 抓取时顺带捎上。用法细节在 &lt;a href=&quot;/posts/monitoring-node-exporter/&quot;&gt;node_exporter 那一篇&lt;/a&gt; 里已经讲过，这里只强调定位：它是 node_exporter 的一个扩展口，不是独立组件，跨机器的、成体系的数据源还是应该走正经 Exporter。&lt;/p&gt;
&lt;h2&gt;要不要自己写一个 Exporter&lt;/h2&gt;
&lt;p&gt;当现成 Exporter 确实不存在（自研中间件、小众设备），自己写并不难，因为 exposition format 本质上就是带约定的纯文本。门槛主要在规矩，不在代码量：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;优先用官方 client library：Go 的 &lt;code&gt;client_golang&lt;/code&gt;、Python 的 &lt;code&gt;prometheus_client&lt;/code&gt; 是最成熟的两个，其他语言也有官方或社区库，别自己手拼字符串。&lt;/li&gt;
&lt;li&gt;每组指标前要有 &lt;code&gt;# HELP&lt;/code&gt;（说明这指标是什么）和 &lt;code&gt;# TYPE&lt;/code&gt;（声明类型）两行，Prometheus 靠它们理解语义。&lt;/li&gt;
&lt;li&gt;Counter（只增不减的计数）指标名以 &lt;code&gt;_total&lt;/code&gt; 结尾，比如 &lt;code&gt;http_requests_total&lt;/code&gt;；单位写进名字而不是值里，如 &lt;code&gt;process_cpu_seconds_total&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;标签只放低基数维度（实例、接口、状态码段），&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;把用户 ID、订单号这类高基数值塞进标签，是把 Prometheus 内存打爆的最快方式&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;写之前先翻一遍官方 Exporter 列表和社区仓库，确认真的没人写过——Exporter 生态的覆盖面比大多数人以为的广，重复造轮子不如给现有项目提一个 PR。&lt;/p&gt;
&lt;h2&gt;选型四原则&lt;/h2&gt;
&lt;p&gt;把上面所有细节收拢成四条决策规则，遇到新组件时按顺序过一遍：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;先问有没有原生 &lt;code&gt;/metrics&lt;/code&gt;&lt;/strong&gt;：新版应用和中间件越来越多地自带 Prometheus 端点，有就直接抓，别多套一层 Exporter——少一层翻译，少一处版本耦合。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;官方优先&lt;/strong&gt;：先查 prometheus-community 与官方组织仓库；官方没有再看社区主流（star 数、更新频率、是否跟得上主程序版本）；Percona 之于 MongoDB 这种「厂商维护版」也算一线选择。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;版本跟主程序&lt;/strong&gt;：Exporter 与目标软件的大版本要对得上，升级数据库时把对应 Exporter 一起排进变更单；版本错位最常见的症状不是报错，而是某些指标悄悄消失。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;账号最小权限&lt;/strong&gt;：每个 Exporter 一个专用账号，只给读状态的权，限制连接数，凭据用环境变量或文件注入而不写死在抓取配置里。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;这四条里，第一条最容易被跳过。很多人装完 redis_exporter 用了半年，才发现新版 Redis 旁边早就有人用原生模块或者更轻的方案——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Exporter 是给「改不了的软件」准备的退路，不是所有组件的默认入口&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h2&gt;排障：抓不到、缺指标、名字对不上&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Exporter 起来了，但 Prometheus 抓不到数据。&lt;/strong&gt; 先跳过 Prometheus，直接 &lt;code&gt;curl http://&amp;lt;exporter地址&amp;gt;:&amp;lt;端口&amp;gt;/metrics&lt;/code&gt;：能返回指标文本，问题在 Prometheus 侧的抓取配置（job 写错、网络不通、标签重写把 target 改丢了）；连不上或返回错误，再去看 Exporter 自己的日志。数据库类 Exporter 还有一个 &lt;code&gt;/probe&lt;/code&gt; 或 multi-target 端点形态，别把两种端点搞混。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Exporter 不报错，但某些指标就是没有。&lt;/strong&gt; 十有八九是账号权限不足。很多状态查询在权限不够时不是报错，而是返回空集或直接跳过——Exporter 把「查不到」翻译成了「没有这条指标」。拿监控账号手动执行一遍它要跑的状态查询（MySQL 的 &lt;code&gt;SHOW GLOBAL STATUS&lt;/code&gt;、PostgreSQL 的 &lt;code&gt;pg_stat_*&lt;/code&gt; 视图），缺哪块补哪块权限，别一股脑改成全权。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;升级之后仪表盘大片无数据。&lt;/strong&gt; 基本是版本不匹配或新版改了指标名。用 &lt;code&gt;curl&lt;/code&gt; 把新版的 &lt;code&gt;/metrics&lt;/code&gt; 输出和旧版存档 diff 一遍，改名、删标签一眼可见；改完查询语句记得同步改告警规则。数据库侧的指标语义问题，也可以对照 &lt;a href=&quot;/posts/database-monitoring-troubleshooting/&quot;&gt;数据库监控与排障&lt;/a&gt; 那篇一起看。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;snmp_exporter 只抓到通用接口指标。&lt;/strong&gt; 不是故障，是 &lt;code&gt;snmp.yml&lt;/code&gt; 里缺你这台设备的厂商 module——回去用 generator 针对具体型号重新生成配置。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Exporter 的本质是一层无状态翻译：对上游说方言，对 Prometheus 只说 &lt;code&gt;/metrics&lt;/code&gt;。选型时先确认软件有没有原生端点，再按官方优先、版本跟随、账号最小权限的顺序落地；数据库类盯紧账号授权，网络硬件类盯紧配置生成。Pushgateway 只留给短命批处理任务，常驻服务一律走 pull；本机脚本类状态交给 textfile collector。把这层翻译层选对、配稳，后面无论接多少种新组件进监控体系，Prometheus 侧的模型都不用变——这正是 Exporter 生态最大的价值。&lt;/p&gt;
</content:encoded></item><item><title>监控与可观测性：六台 VPS 收进一块面板——多机统一监控落地实战</title><link>https://www.anexns.cloudns.org/posts/monitoring-fleet/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-fleet/</guid><description>六台机器六个面板的时代该结束了：中心拉取、remote_write 推送、联邦三条路线对比选型，标签纪律、保留期分层、告警收口与上线检查清单一次讲清。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;半夜出事，你先开了六个标签页&lt;/h2&gt;
&lt;p&gt;凌晨三点，手机响了，某台机器的告警。你的第一反应不是处理问题，而是先想：这是哪台机器来着？然后打开它的面板看一眼 CPU，发现不是资源问题，再打开第二台、第三台……六台 VPS，六套各看各的监控，六个标签页来回切。等你把现场拼凑完整，二十分钟过去了，故障本身可能五分钟就能修好。&lt;/p&gt;
&lt;p&gt;这就是单机监控堆到多机之后的典型状态：每台机器单独看都没毛病，合在一起就是一团乱。缺的不是更多的图表，而是一套统一的系统——一个地方看全部机器，一个出口发全部告警，一套标签查全部数据。&lt;/p&gt;
&lt;p&gt;本篇是监控与可观测性系列的完结篇。前面十四篇把零件逐个讲透了：概念与指标体系、Prometheus 抓取、各类 exporter、VictoriaMetrics 存储、Alertmanager 告警、Grafana 看板、日志与拨测。这一篇不再讲单个组件，只做拼装：把六台机器收进一块面板，顺带把全系列收个尾。概念还没打底的，建议先看&lt;a href=&quot;/posts/monitoring-concepts/&quot;&gt;监控与可观测性：先把概念理清&lt;/a&gt;再回来。&lt;/p&gt;
&lt;h2&gt;先选架构：三条路线，只有一条适合六台机器&lt;/h2&gt;
&lt;p&gt;多机汇聚无非三种打法，先把账算清楚再动手。&lt;/p&gt;
&lt;h3&gt;路线一：中心 Prometheus 主动拉取&lt;/h3&gt;
&lt;p&gt;中心放一台 Prometheus，各机跑 node_exporter 等 exporter 暴露 &lt;code&gt;/metrics&lt;/code&gt;，中心按抓取配置逐台拉。优点是模型最简单：抓没抓到、目标在不在线，中心一清二楚，&lt;code&gt;up&lt;/code&gt; 指标天然可用。缺点也直接：&lt;strong&gt;中心必须能连通每一台机器的 exporter 端口&lt;/strong&gt;。跨公网时通道要自己搭——把各机组进 WireGuard 或 Tailscale 内网，或者给 exporter 套一层反向代理加 Basic Auth 和 IP 白名单。机器都在同一内网、或者你愿意维护一张虚拟内网时，这条路线最省心。&lt;/p&gt;
&lt;h3&gt;路线二：各机推送，中心只收（remote_write）&lt;/h3&gt;
&lt;p&gt;各机本地跑 vmagent（或 Prometheus 开启 remote_write），抓完本机数据后主动推到中心的 VictoriaMetrics 或 Prometheus。通道方向反过来了：&lt;strong&gt;各机只需要出站&lt;/strong&gt;，不用在每台机器上开任何入站端口。机器躲在 NAT 后面、防火墙策略严、或者分布在不同机房时，这条路线几乎是唯一顺手的。代价是中心不再天然知道「谁没推数据」，要靠 &lt;code&gt;up&lt;/code&gt; 类指标和数据断流告警自己补上——后面排障一节会讲怎么交叉验证。&lt;/p&gt;
&lt;h3&gt;路线三：联邦 federation——这个规模别碰&lt;/h3&gt;
&lt;p&gt;联邦是让上级 Prometheus 定时拉取下级 Prometheus 的汇总数据，为的是跨地域、成百上千台机器的分级汇聚。六台机器上联邦，等于给每一台都养一个完整 Prometheus 再叠一层抓取，配置翻倍、排障翻倍，收益为零。记住一句话：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;联邦是千台规模的解法，六台机器用它纯属给自己找活。&amp;lt;/span&amp;gt;真到了需要分级汇聚的那天再学不迟。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;路线&lt;/th&gt;
&lt;th&gt;通道要求&lt;/th&gt;
&lt;th&gt;小机器友好度&lt;/th&gt;
&lt;th&gt;运维复杂度&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;中心拉取&lt;/td&gt;
&lt;td&gt;中心能入站连通每台 exporter&lt;/td&gt;
&lt;td&gt;中（每台只需 exporter）&lt;/td&gt;
&lt;td&gt;低&lt;/td&gt;
&lt;td&gt;同内网或已有虚拟内网&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;remote_write 推送&lt;/td&gt;
&lt;td&gt;各机只需出站&lt;/td&gt;
&lt;td&gt;高（vmagent 内存占用小）&lt;/td&gt;
&lt;td&gt;中&lt;/td&gt;
&lt;td&gt;跨机房、NAT 后、防火墙严&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;联邦 federation&lt;/td&gt;
&lt;td&gt;双向都要通&lt;/td&gt;
&lt;td&gt;低（每台一个完整 Prometheus）&lt;/td&gt;
&lt;td&gt;高&lt;/td&gt;
&lt;td&gt;千台级分级汇聚&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;结论先放这儿：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;六台机器的规模，首选 remote_write 推送——各机只出站、中心只接收，通道和防火墙都最省事。&amp;lt;/span&amp;gt;下文就按这条路线展开；选拉取路线的同学把抓取配置写好即可，其余的标签、保留、收口部分完全通用。&lt;/p&gt;
&lt;h2&gt;remote_write 最小配置&lt;/h2&gt;
&lt;p&gt;各机装 vmagent（VictoriaMetrics 的单机组件包里自带），本地抓取本机 exporter 后往中心推。一份能用的启动参数长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 各机 vmagent 关键启动参数
./vmagent-prod \
  -prometheusDataPath=/var/lib/vmagent \
  -remoteWrite.url=https://monitor.example.com:8428/api/v1/write \
  -remoteWrite.basicAuth.username=vmagent \
  -remoteWrite.basicAuth.password=&apos;自行设置的强密码&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;配套的抓取配置（&lt;code&gt;prometheus.yml&lt;/code&gt;，vmagent 兼容 Prometheus 语法）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;global:
  scrape_interval: 30s
  external_labels:
    env: prod

scrape_configs:
  - job_name: node
    static_configs:
      - targets: [&apos;127.0.0.1:9100&apos;]
        labels:
          instance: rn-01
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个要点：第一，&lt;code&gt;external_labels&lt;/code&gt; 里的 &lt;code&gt;env&lt;/code&gt; 和每条抓取的 &lt;code&gt;instance&lt;/code&gt; 在这里一次定死，全网照抄同一套规范（下一节细说）；第二，中心端 VictoriaMetrics 前面要套 HTTPS 和 Basic Auth，接收端同样可以用 &lt;code&gt;-httpAuth&lt;/code&gt; 或反向代理加认证，别裸奔。中心为什么选 VictoriaMetrics 而不是原生 Prometheus，&lt;a href=&quot;/posts/monitoring-victoriametrics/&quot;&gt;监控与可观测性：VictoriaMetrics 单机版部署&lt;/a&gt;里算过资源账：同样的保留期，它的磁盘和内存开销明显更低，中心机不用单独加大配置。&lt;/p&gt;
&lt;p&gt;:::warning
多机监控最大的风险点不是数据丢了，而是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把 exporter 端口直接暴露在公网上&amp;lt;/span&amp;gt;。&lt;code&gt;/metrics&lt;/code&gt; 里有主机名、内核版本、文件系统、进程与网络连接的全套细节，等于把内网资产清单免费送人，历史上还出过未授权访问顺藤摸瓜的事件。无论走拉取还是推送：exporter 只监听回环或内网地址，跨公网必须走加密通道（WireGuard、Tailscale 或 HTTPS），通道上还要有认证（Basic Auth、mTLS 或 IP 白名单至少占一样）。加密和认证一样都没有的跨公网抓取，不要上线。
:::&lt;/p&gt;
&lt;h2&gt;标签纪律：全网一套命名，定死不许改&lt;/h2&gt;
&lt;p&gt;多机系统里最先崩的往往不是程序，而是标签。今天这台写 &lt;code&gt;instance: 192.0.2.10:9100&lt;/code&gt;，明天那台写 &lt;code&gt;instance: rn-01&lt;/code&gt;，后天有人临时加了个 &lt;code&gt;test: &apos;true&apos;&lt;/code&gt; 忘了删——看板变量查出来五台机器，告警规则匹配漏一台，复盘时三份数据对不上号。规矩只有三条：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;job&lt;/code&gt; 表示角色&lt;/strong&gt;：&lt;code&gt;node&lt;/code&gt;、&lt;code&gt;docker&lt;/code&gt;、&lt;code&gt;nginx&lt;/code&gt;、&lt;code&gt;postgres&lt;/code&gt;，全网同一角色同一个词，不用复数不用缩写花活。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;instance&lt;/code&gt; 用机器名，不用 IP&lt;/strong&gt;：&lt;code&gt;rn-01&lt;/code&gt;、&lt;code&gt;gc-02&lt;/code&gt; 这种稳定名字。IP 会变、端口会变，机器名是这台机器的身份证；看板和告警里出现机器名也比 IP 亲切得多，出事时一眼知道是谁。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;env&lt;/code&gt; 只有 &lt;code&gt;prod&lt;/code&gt; 和 &lt;code&gt;test&lt;/code&gt; 两个值&lt;/strong&gt;，在抓取端或 vmagent 的 &lt;code&gt;external_labels&lt;/code&gt; 里统一打，不允许业务侧自己加。临时标签一律禁止：要临时排查，用日志和命令行，别往时序数据里塞——标签基数一旦膨胀，存储和查询一起遭殃，而且塞进去容易删起来难。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这套命名写进 Git 里的配置模板，新机器上线照着模板改个机器名就行，不给自由发挥留空间。&lt;/p&gt;
&lt;h2&gt;保留期分层：本地短留，中心长留&lt;/h2&gt;
&lt;p&gt;数据留多久，按「离事故现场的距离」分层：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;各机本地只留 3–7 天&lt;/strong&gt;：vmagent 的本地缓冲和短期存储够了，它的核心任务是抓取和转发，顺带扛住中心短暂不可用时的断点续传。本地盘本来就小，别让监控数据和业务抢空间。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;中心留 6–12 个月&lt;/strong&gt;：趋势对比、容量规划、季度复盘都靠它。VictoriaMetrics 对老数据可以做降采样（downsampling），比如 90 天后只保留 5 分钟粒度，磁盘立刻省一个量级。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;原始高频数据不追求永久&lt;/strong&gt;：30 秒粒度留一年已经足够回答「去年这时候这台机器忙不忙」，真要多年留存，留降采样后的就好。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;容量上先有个粗略概念：六台机器、每台一个 node_exporter 加两三个业务 exporter、30 秒抓一次，中心一天的新增数据通常在几百 MB 量级，VictoriaMetrics 压缩之后更小。一块 20 GB 的数据盘留一年绰绰有余——多机监控在存储上从来不是负担，负担只来自标签基数失控和保留期漫无边际，这也是前面把标签纪律单列一节的原因。&lt;/p&gt;
&lt;h2&gt;收口：一个 Grafana，一个 Alertmanager&lt;/h2&gt;
&lt;p&gt;看板和告警必须收口，这是多机系统和单机堆叠的分水岭。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;看板只进一个 Grafana&lt;/strong&gt;：中心 Grafana 只连中心一个数据源（VictoriaMetrics 兼容 Prometheus 数据源）。所有看板按「全舰队总览 → 单机下钻」的结构组织，总览页一排六台机器的水位，下钻页用 &lt;code&gt;instance&lt;/code&gt; 变量切换。机器增减只动变量，不用改图。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;告警只从中心出&lt;/strong&gt;：各机本地不要各发各的告警——六个出口六套静默策略，半夜能把人逼疯。所有告警规则在中心统一评估，统一进一个 Alertmanager 做分组、抑制和静默，再分发到 Telegram、邮件或 Webhook。Alertmanager 的路由与静默玩法在&lt;a href=&quot;/posts/monitoring-alertmanager/&quot;&gt;监控与可观测性：Alertmanager 告警全解&lt;/a&gt;里讲透了，这里只强调纪律：&lt;strong&gt;任何新告警先问一句「它进中心规则库了吗」，没进的告警不算数。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;配置全部进 Git&lt;/strong&gt;：抓取配置、告警规则、Alertmanager 路由、Grafana 的 provisioning（数据源与看板即代码）都进仓库。改配置走提交记录，谁在什么时候为什么改了一目了然；新机器上线就是套模板加一行；机器重装时配置十分钟恢复。监控系统自己不能成为唯一没有备份和版本史的东西。&lt;/p&gt;
&lt;h2&gt;和轻量探针分工：三层各管一段&lt;/h2&gt;
&lt;p&gt;上了 Prometheus 体系，要不要把 Komari、Uptime Kuma 撤了？不用，它们和深度监控不是替代关系，是分工关系：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;层&lt;/th&gt;
&lt;th&gt;工具&lt;/th&gt;
&lt;th&gt;回答的问题&lt;/th&gt;
&lt;th&gt;视角&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;值班层&lt;/td&gt;
&lt;td&gt;Komari&lt;/td&gt;
&lt;td&gt;还活着吗、水位大概多少&lt;/td&gt;
&lt;td&gt;机器内部，秒级心跳&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;拨测层&lt;/td&gt;
&lt;td&gt;Uptime Kuma / Gatus&lt;/td&gt;
&lt;td&gt;用户能不能打开、证书还剩几天&lt;/td&gt;
&lt;td&gt;机器外部，真实访问路径&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;深挖层&lt;/td&gt;
&lt;td&gt;Prometheus ＋ VictoriaMetrics ＋ Grafana&lt;/td&gt;
&lt;td&gt;为什么慢、趋势如何、出过几次&lt;/td&gt;
&lt;td&gt;全量指标，事后复盘&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;值班层要的是轻和稳：&lt;a href=&quot;/posts/selfhost-komari/&quot;&gt;Komari 探针&lt;/a&gt;装在每台机器上，面板一眼看全舰队生死与资源水位，它挂了不影响任何业务。拨测层从外侧打进来，&lt;a href=&quot;/posts/selfhost-uptime-kuma/&quot;&gt;Uptime Kuma&lt;/a&gt;测的是用户真实路径——机器活着但域名解析错了、证书过期了，只有这一层能发现。深挖层负责回答「为什么」：某台机器上周二凌晨内存为什么冲高、磁盘按这个增速还能撑几周。排障时三层交叉着看，比任何单层都快——下一节就用得上。&lt;/p&gt;
&lt;h2&gt;上线检查清单：每台机器逐项打勾&lt;/h2&gt;
&lt;p&gt;新机器接入统一监控，照这张单子验收，全过才算上线：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;[ ] exporter 已安装并在跑，且只监听回环或内网地址，公网扫不到端口&lt;/li&gt;
&lt;li&gt;[ ] 中心能查到这台机器的数据，&lt;code&gt;up&lt;/code&gt;（或 vmagent 的推送状态）正常&lt;/li&gt;
&lt;li&gt;[ ] &lt;code&gt;job&lt;/code&gt;、&lt;code&gt;instance&lt;/code&gt;、&lt;code&gt;env&lt;/code&gt; 三个标签与全网规范一致，&lt;code&gt;instance&lt;/code&gt; 是机器名不是 IP&lt;/li&gt;
&lt;li&gt;[ ] 在总览看板里能通过变量选到这台机器，曲线完整不断裂&lt;/li&gt;
&lt;li&gt;[ ] 手动触发一次测试告警（比如把阈值临时调低），确认能经中心 Alertmanager 送达手机&lt;/li&gt;
&lt;li&gt;[ ] 时间同步正常，&lt;code&gt;chronyc tracking&lt;/code&gt; 或 &lt;code&gt;timedatectl&lt;/code&gt; 显示已同步&lt;/li&gt;
&lt;li&gt;[ ] 本地保留期与磁盘上限已设置，监控数据不会撑爆系统盘&lt;/li&gt;
&lt;li&gt;[ ] 这台机器的抓取配置已提交进 Git&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;排障：数据断流时，先分清是哪一层的事&lt;/h2&gt;
&lt;h3&gt;某台机数据断了：机器挂了，还是通道断了？&lt;/h3&gt;
&lt;p&gt;这是多机监控最高频的问题，处理顺序别反。先看值班层：Komari 上这台机器还在线吗？在线，说明机器没死，大概率是通道或中心端的问题——查 vmagent 日志看 remote_write 是否报错、中心 VictoriaMetrics 是否在重启或磁盘满。再看拨测层：Uptime Kuma 的外部探测还通吗？两层都说活着、只有深挖层没数据，问题就锁定在「抓取—推送」这一段里。若 Komari 也掉线，才按机器故障处理。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要一看到曲线断了就去重启机器&amp;lt;/span&amp;gt;，先交叉验证，很多时候机器好好的，只是推送通道断了，重启反而把现场清了。&lt;/p&gt;
&lt;h3&gt;曲线错位：先查时钟&lt;/h3&gt;
&lt;p&gt;两台机器的曲线对不齐、告警时间比日志慢了几分钟，十有八九是某台机器时钟漂了。时序数据的时间戳以抓取与写入侧为准，机器本地时钟不准则日志、告警、曲线三者互相打架。逐台跑 &lt;code&gt;timedatectl&lt;/code&gt; 确认 NTP 已同步，老机器优先检查 chrony 服务是否在跑。这一条也是检查清单里单列时间同步的原因。&lt;/p&gt;
&lt;h3&gt;看板变量漏机器：标签不统一的现行犯&lt;/h3&gt;
&lt;p&gt;总览页变量里只有五台、独缺新上的那台，别去改看板——先去查那台机器的标签。变量一般用 &lt;code&gt;label_values(up, instance)&lt;/code&gt; 生成，漏机器只可能是：这台的 &lt;code&gt;instance&lt;/code&gt; 写成了 IP、拼错了名字，或者 &lt;code&gt;job&lt;/code&gt; 不在变量限定的集合里。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;看板漏机器，九成是标签没按规范写&amp;lt;/span&amp;gt;，回抓取配置里对照模板改掉，改完这类问题不会再犯第二次。&lt;/p&gt;
&lt;h2&gt;小结：全系列到此收束&lt;/h2&gt;
&lt;p&gt;从第一篇的概念，到采集、存储、告警、看板、日志、拨测，再到这一篇的多机落地，这个系列想讲的其实只有一件事：监控不是装个面板看曲线，而是一套「出事能发现、发现能定位、定位能复盘」的系统。落到六台机器上，它的形状就是这篇的样子——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;各机轻量采集、中心统一存储、一块面板看全舰队、一个出口发全部告警、一套标签走天下。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;不必一次到位。先把六台机器的数据汇到一个中心、标签统一、告警收口，这三件做完，半夜再出事，你只需要打开一个标签页。&lt;/p&gt;
</content:encoded></item><item><title>监控与可观测性：Gatus 把状态页写进一个 YAML 文件</title><link>https://www.anexns.cloudns.org/posts/monitoring-gatus/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-gatus/</guid><description>用 Gatus 以配置即代码的方式管理拨测与状态页：一个 config.yaml 声明全部端点、条件与告警，进 Git 可审查可复制，告别在网页后台里点点点。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先吵一架：状态页的配置，该点鼠标还是该进 Git&lt;/h2&gt;
&lt;p&gt;做拨测监控有两条路线。一条是 Uptime Kuma 那样的图形界面派：开个网页，点几下鼠标，加一个监控项，存进数据库，舒服直观；另一条是配置即代码派：所有监控项写在一个文本文件里，改配置就是改文件，文件进 Git，谁改了什么、什么时候改的，一条 blame 全看得清清楚楚。&lt;/p&gt;
&lt;p&gt;这两条路线没有谁碾压谁，但当你的服务从三五个涨到二三十个，当你想把同一套拨测复制到第二台机器，当某天凌晨你想弄明白「这个监控项是谁上周改掉的」——图形界面派就开始吃力了：配置躺在数据库里，看不见、比不了、搬不走。&lt;/p&gt;
&lt;p&gt;Gatus 就是配置即代码派的代表作：一个 config.yaml 声明全部端点、判定条件和告警渠道，首页就是一张现成的状态页，轻量、透明、可版本管理。这篇把它讲透：怎么部署、条件怎么写、告警怎么配、历史怎么留住。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/TwiN/gatus&lt;/p&gt;
&lt;h2&gt;Gatus 是什么：一份 YAML 就是一整套拨测&lt;/h2&gt;
&lt;p&gt;Gatus 是开源的自动化拨测与状态页工具。它的工作方式一句话说清：你在一个 config.yaml 里声明要测的端点，它按你设的间隔去请求这些端点，用你写的条件判断健康与否，把结果画在首页状态页上，异常时按你配的渠道发告警。&lt;/p&gt;
&lt;p&gt;它和同系列里讲过的 &lt;a href=&quot;/posts/monitoring-blackbox/&quot;&gt;Blackbox Exporter&lt;/a&gt; 是亲戚关系：都属于主动拨测。但 Blackbox 是 Prometheus 体系里的探针组件，数据要进 Prometheus 才能看；Gatus 是自带存储、自带状态页、自带告警的一体机，部署完打开网页就能用。两者怎么选，简单说：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;已经在用 Prometheus 全家桶就用 Blackbox，只想快速要一张状态页加告警，就用 Gatus。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;和 &lt;a href=&quot;/posts/selfhost-uptime-kuma/&quot;&gt;Uptime Kuma&lt;/a&gt; 的差异更值得展开，放在文末有完整的对比表，这里先给结论：Kuma 胜在功能全、界面友好；Gatus 胜在配置透明、轻量、天然适合 Git 管理。&lt;/p&gt;
&lt;h2&gt;部署：一个容器，一份配置&lt;/h2&gt;
&lt;p&gt;Gatus 的官方镜像是 &lt;code&gt;twinproduction/gatus&lt;/code&gt;，服务端口 8080。部署只需要两样东西：一个 docker-compose.yml 和一个 config.yaml，两者放在同一目录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  gatus:
    image: twinproduction/gatus:latest
    container_name: gatus
    restart: unless-stopped
    ports:
      - &quot;8080:8080&quot;
    volumes:
      - ./config:/config
      - ./data:/data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 volumes 的挂载点：Gatus 默认从 &lt;code&gt;/config&lt;/code&gt; 目录读取 config.yaml，数据文件我们指定写到 &lt;code&gt;/data&lt;/code&gt;，这两个路径在下面的配置里要对上。&lt;/p&gt;
&lt;p&gt;目录建好、文件就位之后，启动和验证就三条命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose logs -f gatus
curl -s http://localhost:8080/health
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;日志里能看到每个端点被逐个加载、第一次拨测的结果；&lt;code&gt;/health&lt;/code&gt; 返回正常，就说明服务本身活着。之后改 config.yaml 不需要重建镜像，重启容器即可重新加载配置——这也是配置即代码的日常体验：改文件、重启、生效，整个过程可以写进一个 Git 提交里。&lt;/p&gt;
&lt;h2&gt;config.yaml 全解剖：三个端点一次讲清&lt;/h2&gt;
&lt;p&gt;下面这份配置包含三类最典型的端点：一个网站首页、一个 API 接口、一个专门盯证书过期的检查。先看全貌，再逐段拆解：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;storage:
  type: sqlite
  path: /data/data.db

endpoints:
  - name: 博客首页
    group: 对外服务
    url: &quot;https://blog.example.com&quot;
    interval: 60s
    conditions:
      - &quot;[STATUS] == 200&quot;
      - &quot;[RESPONSE_TIME] &amp;lt; 1000&quot;
    alerts:
      - type: telegram
        failure-threshold: 3
        success-threshold: 2
        description: &quot;博客首页异常&quot;

  - name: 业务 API
    group: 对外服务
    url: &quot;https://api.example.com/health&quot;
    interval: 60s
    conditions:
      - &quot;[STATUS] == 200&quot;
      - &quot;[BODY].status == ok&quot;
    alerts:
      - type: telegram
        failure-threshold: 3
        success-threshold: 2

  - name: 证书过期检查
    group: 基础设施
    url: &quot;https://blog.example.com&quot;
    interval: 5m
    conditions:
      - &quot;[CERTIFICATE_EXPIRATION] &amp;gt; 48h&quot;

alerting:
  telegram:
    authorization-key: &quot;你的 Bot Token&quot;
    to: &quot;你的 Chat ID&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;端点四要素：name、group、url、interval&lt;/h3&gt;
&lt;p&gt;每个端点先有四个基本字段：&lt;code&gt;name&lt;/code&gt; 是显示在状态页上的名字；&lt;code&gt;group&lt;/code&gt; 是分组，状态页会按组归类展示，服务多了不分组就是一场灾难；&lt;code&gt;url&lt;/code&gt; 是拨测目标；&lt;code&gt;interval&lt;/code&gt; 是拨测间隔，网站和 API 用 60s 比较常见，证书这类慢变量用 5m 甚至更长就够了，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要给所有端点无脑上 10s 的高频拨测，那是在给被测服务和自己同时上压力。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h3&gt;条件语法：方括号占位符加比较运算&lt;/h3&gt;
&lt;p&gt;conditions 是一个数组，端点健康要求数组里的条件&lt;strong&gt;全部成立&lt;/strong&gt;，有一条不成立就判失败。可用的占位符主要有：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;[STATUS]&lt;/code&gt;：HTTP 状态码，最常用，如 &lt;code&gt;[STATUS] == 200&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;[RESPONSE_TIME]&lt;/code&gt;：响应时间，单位毫秒，如 &lt;code&gt;[RESPONSE_TIME] &amp;lt; 1000&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;[CERTIFICATE_EXPIRATION]&lt;/code&gt;：证书剩余有效期，如 &lt;code&gt;[CERTIFICATE_EXPIRATION] &amp;gt; 48h&lt;/code&gt;，提前两天预警&lt;/li&gt;
&lt;li&gt;&lt;code&gt;[DNS_RCODE]&lt;/code&gt;：DNS 解析返回码，如 &lt;code&gt;[DNS_RCODE] == NOERROR&lt;/code&gt;，适合盯域名解析是否正常&lt;/li&gt;
&lt;li&gt;&lt;code&gt;[BODY]&lt;/code&gt;：响应体内容，可以做字符串包含匹配，也能像示例里那样取 JSON 字段 &lt;code&gt;[BODY].status == ok&lt;/code&gt;，让健康检查不止看状态码、还看业务自报状态&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;除了条件，端点还支持自定义 &lt;code&gt;headers&lt;/code&gt;，比如给 API 带上鉴权头或特定的 User-Agent，需要测「带头才能访问」的接口时用得上。&lt;/p&gt;
&lt;p&gt;证书之外，DNS 也是值得单独盯的一项：域名解析被改错、DNS 服务商出故障时，网站本身明明好端端的，用户却打不开。给关键域名加一个专门的 DNS 端点，成本只有几行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;  - name: 域名解析检查
    group: 基础设施
    url: &quot;8.8.8.8&quot;
    interval: 5m
    dns:
      query-name: &quot;blog.example.com&quot;
      query-type: &quot;A&quot;
    conditions:
      - &quot;[DNS_RCODE] == NOERROR&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这类「慢变量端点」的共同点是间隔可以放长、条件可以单纯，它们的价值不在实时，而在于出事时你能第一时间分清是服务挂了、证书过期了，还是解析没了。&lt;/p&gt;
&lt;h3&gt;告警：阈值防抖是精髓&lt;/h3&gt;
&lt;p&gt;alerting 段在全局统一声明渠道的凭据——示例里是 Telegram，Gatus 还支持 Slack、Discord、邮件、PagerDuty，以及一个 &lt;code&gt;custom&lt;/code&gt; 类型，本质就是 Webhook，能往任意 HTTP 接口 POST，方便接自建的通知网关；本站的告警体系怎么统一收口，可以参考 &lt;a href=&quot;/posts/monitoring-alertmanager/&quot;&gt;Alertmanager 告警链&lt;/a&gt; 那篇的思路。&lt;/p&gt;
&lt;p&gt;端点里引用告警时，最重要的两个参数是 &lt;code&gt;failure-threshold&lt;/code&gt; 和 &lt;code&gt;success-threshold&lt;/code&gt;：前者是连续失败几次才真正发告警，后者是连续成功几次才发恢复通知。示例里设 3 和 2，意思是抖动一两次不吭声、确认挂了才喊、确认活了才报平安。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;这两个阈值是 Gatus 告警好用的关键：没有防抖的拨测告警，迟早被你自己静音。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;:::warning
两个坑一次说清。第一，storage 不配 sqlite 时，Gatus 默认把历史放在内存里，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;容器一重启，可用率和响应时间历史全部清零&amp;lt;/span&amp;gt;——这不是 bug，是默认行为，想留住历史必须像示例这样显式配 sqlite 并把数据目录挂出来持久化。第二，Gatus 的首页状态页默认不需要登录，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把状态页直接公开到公网，等于把你的服务清单、域名和可用率双手送给所有人&amp;lt;/span&amp;gt;，对外暴露前请务必套一层反向代理加访问控制，或者只在内网开放。
:::&lt;/p&gt;
&lt;h2&gt;状态页与接口：给人看的和给机器看的&lt;/h2&gt;
&lt;p&gt;部署完成后访问 8080 端口，首页就是状态页：每个端点一行，按 group 分组，显示当前状态、可用率百分比和响应时间历史曲线。一眼扫过去全绿才安心，有红的一行点进去能看到每次拨测的明细。&lt;/p&gt;
&lt;p&gt;给机器用的部分有两个：一是 &lt;code&gt;/api/v1/endpoints/statuses&lt;/code&gt; 接口，返回全部端点的结构化状态数据，可以被其他系统消费，比如汇总多台机器的状态、接到自己的面板里；二是徽章（badge）能力，能生成某个端点的可用率或响应时间徽章图片，嵌在 README 或文档里很顺手。多机部署时怎么把各节点的状态收拢成一个总览，&lt;a href=&quot;/posts/monitoring-fleet/&quot;&gt;舰队总览&lt;/a&gt; 那篇有完整的组织方法。&lt;/p&gt;
&lt;h2&gt;和 Uptime Kuma 正面对比&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;Gatus&lt;/th&gt;
&lt;th&gt;Uptime Kuma&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;配置方式&lt;/td&gt;
&lt;td&gt;单个 config.yaml，进 Git 管理&lt;/td&gt;
&lt;td&gt;网页 GUI 操作，存数据库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;配置可审查性&lt;/td&gt;
&lt;td&gt;强，diff 与 blame 一目了然&lt;/td&gt;
&lt;td&gt;弱，变更无版本记录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;复制到新机器&lt;/td&gt;
&lt;td&gt;拷贝文件即可&lt;/td&gt;
&lt;td&gt;导出导入或重搭数据库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;判定条件&lt;/td&gt;
&lt;td&gt;表达式语法，状态码/响应时间/证书/DNS/响应体组合判断&lt;/td&gt;
&lt;td&gt;以状态码和关键词匹配为主&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;状态页&lt;/td&gt;
&lt;td&gt;自带，按分组展示可用率与历史&lt;/td&gt;
&lt;td&gt;自带，功能更丰富，可多状态页&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;通知渠道&lt;/td&gt;
&lt;td&gt;Telegram、Slack、Discord、Webhook 等主流渠道&lt;/td&gt;
&lt;td&gt;渠道数量更多，冷门渠道也覆盖&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;资源占用&lt;/td&gt;
&lt;td&gt;很轻，单容器内存占用小&lt;/td&gt;
&lt;td&gt;相对更重&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;上手门槛&lt;/td&gt;
&lt;td&gt;要会写 YAML&lt;/td&gt;
&lt;td&gt;点鼠标即可，零门槛&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选型一句话：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;个人少量服务、喜欢图形界面选 Kuma；服务上了规模、想把监控配置当代码管，选 Gatus。&amp;lt;/span&amp;gt;两者并不互斥，完全可以 Kuma 管内网杂项、Gatus 管对外服务的状态页，各取所长。&lt;/p&gt;
&lt;h2&gt;把配置管进 Git：这才是它真正的用法&lt;/h2&gt;
&lt;p&gt;既然配置只是一个文件，就别浪费这个形态。推荐的日常姿势是：把 config.yaml 连同 docker-compose.yml 一起放进一个私有 Git 仓库，改监控项走和改代码一样的流程——本地编辑、提交、推送、到服务器上拉取重启。好处是立竿见影的：谁在什么时候加了一个端点、谁把某个间隔从 60s 改成了 5m，git log 里全有；新机器要复刻整套拨测，clone 仓库、填上凭据、up 一下就完事；改坏了想回滚，一条 git revert 就回到上一版。&lt;/p&gt;
&lt;p&gt;唯一要留心的是凭据：config.yaml 里写着 Telegram Bot Token 这类敏感信息，仓库必须是私有的；更稳妥的做法是把凭据抽到环境变量里，配置文件只留占位，仓库里再放一份不带真实值的示例文件。这样配置可以放心地版本管理，秘密则留在服务器本地，两不耽误。&lt;/p&gt;
&lt;h2&gt;排障小节&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;条件写错了不报错，只判失败。&lt;/strong&gt; 这是新手最容易被坑的一点：conditions 里的表达式写错语法、占位符拼错，Gatus 不会在启动时拦住你，而是每次拨测都判定为失败，状态页一片红。排查顺序是先看容器日志确认配置已加载，再把条件删到只剩 &lt;code&gt;[STATUS] == 200&lt;/code&gt; 这一条最基础的，确认端点能转绿，然后逐条把条件加回去，加一条测一条。尤其注意 &lt;code&gt;[BODY]&lt;/code&gt; 的 JSON 路径写法和字符串比较要不要带引号，这是错得最多的地方。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;时区对不上，历史曲线看着别扭。&lt;/strong&gt; Gatus 容器默认时区通常是 UTC，状态页上的时间点和你本地时间差着时区，半夜的故障看起来像发生在下午。解决办法是在 compose 里给容器加环境变量 &lt;code&gt;TZ=Asia/Shanghai&lt;/code&gt;，让日志和展示都回到本地时区。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;间隔与保留期的关系没算清。&lt;/strong&gt; 历史能留多久，取决于拨测间隔和存储里的数据量：60s 间隔的端点一天产生 1440 条记录，端点多了之后 sqlite 文件会稳步长大。不是故障，但要心里有数，磁盘告警别漏了 Gatus 自己的数据目录。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;容器里测宿主机上的服务，地址别写 localhost。&lt;/strong&gt; Gatus 在容器里运行时，config.yaml 里写 &lt;code&gt;http://localhost:某端口&lt;/code&gt; 指的是容器自己，不是宿主机。测同机其他服务时，Linux 上可以在 compose 里给服务加 &lt;code&gt;extra_hosts: [&quot;host.docker.internal:host-gateway&quot;]&lt;/code&gt;，然后 url 写 &lt;code&gt;http://host.docker.internal:端口&lt;/code&gt;；或者干脆测这些服务对外暴露的域名地址，顺带把反向代理这一层也测进去了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Telegram 告警发不出。&lt;/strong&gt; 先分清是渠道配置问题还是没触发：把某个端点的 failure-threshold 临时改成 1，再把 url 改成一个必然失败的地址，重启后一分钟内应该收到告警；收不到，就专心查 Bot Token 与 Chat ID——最常见的是机器人没和你说过话、或群 ID 填错。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Gatus 的价值不在功能多，而在姿态对：监控配置从数据库里的黑盒变成 Git 里的明文，审查、复制、回滚、迁移全部顺理成章。一份 config.yaml 同时搞定拨测、状态页和告警，sqlite 把历史留住，阈值防抖把告警噪音压下去。如果你已经受够了在网页后台里逐个点监控项，或者正想把手里的监控配置纳入版本管理，Gatus 是目前这个路线里最值得先试的一个。&lt;/p&gt;
</content:encoded></item><item><title>监控与可观测性：Grafana 部署与看板实战</title><link>https://www.anexns.cloudns.org/posts/monitoring-grafana/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-grafana/</guid><description>用官方镜像部署 Grafana，接入 Prometheus 数据源、导入 Node Exporter Full 看板、用变量实现一板多机，再把数据源与看板用 provisioning 当代码管理。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说结论：Prometheus 的自带界面只能验活&lt;/h2&gt;
&lt;p&gt;上一篇把 Prometheus 装好之后，你大概已经打开过它自带的 Web 界面：Targets 页看看抓取目标是不是 UP，表达式浏览器里临时敲一条 PromQL，确认曲线能出来。这个界面用来「验活」足够了，但真要日常看数，它缺的东西太多：多条曲线叠加对比很别扭，没有单位换算和阈值线，想从一台机器切到另一台机器得重写表达式，更没有像样的权限和分享能力。&lt;/p&gt;
&lt;p&gt;这就是监控栈里的经典分工：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Prometheus 负责采集和存储，Grafana 才是给人看的那张脸&amp;lt;/span&amp;gt;。Grafana 本身不存任何监控数据，它只负责把数据源里的数字画成看板：折线、仪表盘、热力图、表格，再配上时间范围切换、变量筛选和自动刷新。上一篇的 &lt;a href=&quot;/posts/monitoring-prometheus/&quot;&gt;Prometheus 部署与抓取配置&lt;/a&gt; 解决的是「数从哪来」，这一篇解决「数怎么看」：用官方镜像把 Grafana 部署起来，接入 Prometheus，导入社区最常用的主机看板，再把配置沉淀成代码。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/grafana/grafana&lt;/p&gt;
&lt;h2&gt;部署：和 Prometheus 放进同一个 Compose&lt;/h2&gt;
&lt;p&gt;Grafana 官方镜像是 &lt;code&gt;grafana/grafana&lt;/code&gt;，默认端口 3000，数据目录 &lt;code&gt;/var/lib/grafana&lt;/code&gt;（看板、用户、数据源配置都存这里面的 SQLite 数据库里），所以这个目录必须挂卷持久化。最省事的做法是把它加进上一篇 Prometheus 的同一个 Compose 文件，两个服务天然在同一网络里，后面填数据源地址能省掉一堆麻烦：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  grafana:
    image: grafana/grafana
    container_name: grafana
    restart: unless-stopped
    environment:
      GF_SECURITY_ADMIN_USER: admin
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD}
      GF_USERS_ALLOW_SIGN_UP: &quot;false&quot;
    ports:
      - &quot;127.0.0.1:3000:3000&quot;
    volumes:
      - grafana-data:/var/lib/grafana
    depends_on:
      - prometheus

volumes:
  grafana-data:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个细节先交代清楚：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;管理员密码不要明文写在 Compose 里，用同目录 &lt;code&gt;.env&lt;/code&gt; 文件里的 &lt;code&gt;GRAFANA_ADMIN_PASSWORD&lt;/code&gt; 变量注入，&lt;code&gt;.env&lt;/code&gt; 本身记得加进 &lt;code&gt;.gitignore&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;GF_USERS_ALLOW_SIGN_UP=false&lt;/code&gt; 关掉自助注册，自用场景没必要开放任何人建号。&lt;/li&gt;
&lt;li&gt;端口只绑 &lt;code&gt;127.0.0.1&lt;/code&gt;，先在本机访问，对外开放走后面的反向代理。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;启动并确认状态：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose ps
docker compose logs --tail=50 grafana
curl -I http://localhost:3000/login
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;http://localhost:3000&lt;/code&gt; 就能看到登录页。用 &lt;code&gt;.env&lt;/code&gt; 里预设的密码登录即可；如果你没设 &lt;code&gt;GF_SECURITY_ADMIN_PASSWORD&lt;/code&gt;，默认账号密码是 admin / admin，首次登录会强制改密，这一步不要跳过。&lt;/p&gt;
&lt;p&gt;:::warning
默认账号 admin / admin 是公开信息，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;装好之后第一件事就是改掉管理员密码&amp;lt;/span&amp;gt;。同时 3000 端口不要图省事直接映射到公网：Grafana 里能看到你全部机器的指标细节，属于敏感信息。对外访问请套一层带 HTTPS 和访问控制的反向代理（比如本系列和自建服务系列里用过的 Nginx Proxy Manager），或者干脆只走内网和 VPN。
:::&lt;/p&gt;
&lt;h2&gt;添加 Prometheus 数据源&lt;/h2&gt;
&lt;p&gt;登录后先进 Connections → Data sources → Add data source，选 Prometheus，只需要填一个 URL：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;http://prometheus:9090
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里的 &lt;code&gt;prometheus&lt;/code&gt; 是 Compose 里的服务名。两个容器在同一网络，Grafana 后端会把这个名字解析到 Prometheus 容器。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;最常见的坑就是在这里填 &lt;code&gt;http://localhost:9090&lt;/code&gt;&amp;lt;/span&amp;gt;：Grafana 容器里的 localhost 指的是它自己，不是宿主机，更不是 Prometheus 容器，填完点 Save &amp;amp; test 必然报错。如果你的 Grafana 是单独部署的，要么把两个容器接进同一个外部网络后继续用服务名，要么填宿主机内网 IP 加映射端口，不要想当然写 localhost。&lt;/p&gt;
&lt;p&gt;填完点 Save &amp;amp; test，出现绿色的成功提示，说明 Grafana 已经能从 Prometheus 拉数了。顺手把这个数据源设为默认（Default），后面导入看板时少选一次。&lt;/p&gt;
&lt;h2&gt;导入社区看板：先站在 1860 的肩膀上&lt;/h2&gt;
&lt;p&gt;自己从零画看板很费时间，社区看板库 grafana.com 已经沉淀了大量现成模板，导入只需要一个 ID。主机监控最常用的就是 Node Exporter Full，看板 ID &lt;strong&gt;1860&lt;/strong&gt;，几乎是装完 Node Exporter 后的标配。&lt;/p&gt;
&lt;p&gt;导入路径：Dashboards → New → Import，在输入框里填 &lt;code&gt;1860&lt;/code&gt; 点 Load，Grafana 会从 grafana.com 拉回这块看板的定义。导入确认页上有一个关键动作：把数据源选成上一步加好的 Prometheus，然后点 Import。&lt;/p&gt;
&lt;p&gt;导入成功后你会看到一块信息量很大的看板：CPU、内存、磁盘、网络、负载、文件句柄……全都有，前提是 Prometheus 那边确实在抓 Node Exporter 的指标（job 和 instance 的来历见 &lt;a href=&quot;/posts/monitoring-prometheus/&quot;&gt;Prometheus 那一篇&lt;/a&gt;）。如果整块板全是 No data，先别怀疑看板，去排障小节对一遍变量和时间范围。&lt;/p&gt;
&lt;p&gt;除了 1860，同一个导入入口还能装很多现成看板：Docker 容器、Nginx、MySQL 各有社区模板。原则是先导入现成的用起来，觉得哪里不顺手再自己改，比从空白画布开始高效得多。&lt;/p&gt;
&lt;h2&gt;看板变量：一块板看所有机器&lt;/h2&gt;
&lt;p&gt;1860 这块板顶部有两个下拉框：&lt;code&gt;$job&lt;/code&gt; 和 &lt;code&gt;$instance&lt;/code&gt;。这就是 Grafana 的模板变量在起作用：看板里的每条查询写的不是写死的机器名，而是变量占位，切换下拉框，整块板所有图表一起换到另一台机器。这就是「一板多机」——机器从 3 台涨到 30 台，看板还是这一块。&lt;/p&gt;
&lt;p&gt;变量的定义在看板右上角 Settings → Variables 里，1860 用的核心写法是：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;label_values(node_uname_info, job)
label_values(node_uname_info{job=&quot;$job&quot;}, instance)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;label_values&lt;/code&gt; 把 Prometheus 里某个指标的标签值捞出来当选项，第二个变量还引用了第一个变量的值做级联过滤。你自己建变量时照着这个套路来就行：先定 job，再定 instance，最后所有面板查询里用 &lt;code&gt;{job=&quot;$job&quot;, instance=&quot;$instance&quot;}&lt;/code&gt; 引用。&lt;/p&gt;
&lt;p&gt;再说两个每天都会用的控件：右上角的时间范围（Last 1 hour / Last 6 hours / Last 24 hours）和旁边的自动刷新（30s、1m）。排障时先把时间范围拉宽确认「到底有没有数」，日常盯盘再切回短范围加自动刷新。很多「看板没数据」的乌龙，最后发现是时间范围停在某个没数据的时段。&lt;/p&gt;
&lt;h2&gt;图表设置：图例、单位和阈值&lt;/h2&gt;
&lt;p&gt;导入的看板能直接用，但有几个设置值得按自己的习惯调一遍，调一次受益所有面板：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;图例（Legend）&lt;/strong&gt;：多曲线面板把图例格式写成 &lt;code&gt;{{instance}}&lt;/code&gt; 只显示机器名，比默认一长串标签清爽得多；图例位置放底部并切成表格模式，还能顺带看到每条曲线的 max、avg、current。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;单位（Unit）&lt;/strong&gt;：内存、磁盘、网络这类面板一定要设对单位。字节类选 bytes(IEC)，Grafana 会自动换算成 GiB；比例类（比如 CPU 使用率算出来是 0 到 1 的小数）选 Percent(0.0-1.0)，不要选成 0-100 的 Percent，否则 0.85 会显示成 0.85% 而不是 85%。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;阈值（Thresholds）&lt;/strong&gt;：给磁盘使用率这类面板加一条 85% 的红色阈值线，扫一眼就知道哪块盘快满了，不用逐个读数。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;自己建一块面板&lt;/h2&gt;
&lt;p&gt;现成看板之外，总有些指标是自己关心的。在任意看板点 Add → Visualization，选数据源后在查询框里写 PromQL，比如主机 CPU 使用率：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;100 - (avg by(instance) (rate(node_cpu_seconds_total{job=&quot;$job&quot;, instance=&quot;$instance&quot;, mode=&quot;idle&quot;}[5m])) * 100)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;写查询时多用变量占位而不是写死标签值，这块板以后换机器、复制到别的看板都能直接用。PromQL 的函数和聚合写法在 &lt;a href=&quot;/posts/monitoring-promql/&quot;&gt;PromQL 查询语言入门&lt;/a&gt; 里有系统讲解，这里不展开。&lt;/p&gt;
&lt;p&gt;顺带一提，Grafana 不只接 Prometheus：本系列后面要装的 &lt;a href=&quot;/posts/monitoring-loki/&quot;&gt;Loki 日志聚合&lt;/a&gt; 也是加一个数据源进同一个 Grafana，指标和日志在一块界面里对照看，这正是它作为统一可视化层的位置。&lt;/p&gt;
&lt;h2&gt;Provisioning：把数据源和看板当代码管理&lt;/h2&gt;
&lt;p&gt;在 Web 界面里点出来的配置都存在 Grafana 的数据库里，容器重建、换机器迁移时全靠数据卷，出了问题也没法回滚。生产级的玩法是 provisioning：用 YAML 文件声明数据源、用 JSON 文件存放看板定义，Grafana 启动时自动加载，整个目录进 Git 管理。&lt;/p&gt;
&lt;p&gt;先给 Compose 加两条挂载：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    volumes:
      - grafana-data:/var/lib/grafana
      - ./provisioning:/etc/grafana/provisioning
      - ./dashboards:/var/lib/grafana/dashboards
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;数据源声明文件 &lt;code&gt;provisioning/datasources/prometheus.yaml&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    editable: true
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;看板加载器 &lt;code&gt;provisioning/dashboards/default.yaml&lt;/code&gt;，告诉 Grafana 去哪个目录捞看板 JSON：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apiVersion: 1
providers:
  - name: default
    orgId: 1
    folder: &apos;&apos;
    type: file
    disableDeletion: true
    updateIntervalSeconds: 30
    options:
      path: /var/lib/grafana/dashboards
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后把调好的看板通过 Share → Export 导出 JSON，放进 &lt;code&gt;dashboards/&lt;/code&gt; 目录，重启 Grafana 就会自动出现。&lt;code&gt;editable: true&lt;/code&gt; 建议保留，这样界面里临时改的数据源还能存回去；看板 JSON 一旦被 provisioning 接管，界面里改完记得重新导出覆盖文件，不然下次重启会被文件版本盖掉。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;数据源和看板都进 Git，监控系统才算真正可复制、可回滚&amp;lt;/span&amp;gt;，这也是本系列后面所有组件统一的管理方式。&lt;/p&gt;
&lt;h2&gt;组织、文件夹与权限&lt;/h2&gt;
&lt;p&gt;Grafana 有 Organization（组织）、Folder（文件夹）和 Viewer / Editor / Admin 三档角色：组织之间的数据源和看板完全隔离，文件夹用来给看板分组并单独授权。个人自用一个默认组织加几个文件夹就够了，团队共用时再按组织拆分、给只看不改的人发 Viewer，别把 Admin 满天飞。&lt;/p&gt;
&lt;p&gt;告警方面只点明分工：Grafana 自带一套统一告警（Unified Alerting），但本系列走的是 Alertmanager 路线——告警规则写在 Prometheus 侧、由 Alertmanager 统一去重分组和发送，Grafana 专心做可视化，两边不要同时开告警，免得同一件事收到两份通知。&lt;/p&gt;
&lt;p&gt;最后摆正一下和已有工具的位置：&lt;a href=&quot;/posts/selfhost-uptime-kuma/&quot;&gt;Uptime Kuma&lt;/a&gt; 回答的是「服务还活着吗」，是存活探测；Grafana 回答的是「活得怎么样、趋势往哪走」，是把指标拉成时间维度看。两者互补，不互相替代。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;数据源 Save &amp;amp; test 报错，连不上。&lt;/strong&gt;
十有八九是地址写错：容器里填了 localhost、两个服务不在同一网络、或者端口写错。对照检查：&lt;code&gt;docker compose ps&lt;/code&gt; 确认两个服务都在，用 &lt;code&gt;docker compose exec grafana cat /etc/hosts&lt;/code&gt; 之类的方式不现实（官方镜像工具很少），最直接的是把 URL 换成服务名 &lt;code&gt;http://prometheus:9090&lt;/code&gt; 再测；单独部署的，确认 Grafana 容器能解析并访问目标地址，必要时把两个容器接进同一个外部网络。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;看板导入成功，但所有面板 No data。&lt;/strong&gt;
按顺序查三件事：第一，时间范围，右上角切到 Last 6 hours 排除时段乌龙；第二，变量，&lt;code&gt;$job&lt;/code&gt; 的实际取值要和 Prometheus 里的 job 名一字不差（很多人 Prometheus 里写的是 &lt;code&gt;node-exporter&lt;/code&gt;，看板默认找的却是别的值），&lt;code&gt;$instance&lt;/code&gt; 也要选中具体机器而不是空着；第三，数据源，导入时是否选错了数据源。还不行就去 Prometheus 界面直接执行看板里的一条原始查询，确认指标本身存在。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;导入看板时报错，或者面板显示缺插件、样式错乱。&lt;/strong&gt;
社区看板有版本兼容问题：太老的看板可能依赖已经被新版 Grafana 移除的 Angular 面板插件，太新的看板又可能用了旧版没有的特性。处理顺序：先把 Grafana 镜像升级到较新的稳定版再导入；导入页如果提供多个 revision，换一个稍旧的版本试；个别面板缺插件的，在看板里把那个面板换成内置的 Time series 面板重建查询即可。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;容器启动即退出，日志报 permission denied。&lt;/strong&gt;
Grafana 进程在容器里以 uid 472 运行。用命名卷一般不会碰到这个问题；如果改成了宿主机目录绑定挂载，需要把目录属主改对：&lt;code&gt;chown -R 472:472 目录路径&lt;/code&gt;，再重启。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;管理员密码忘了。&lt;/strong&gt;
不用重装，进容器重置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose exec grafana grafana-cli admin reset-admin-password 新密码
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重置后记得同步更新 &lt;code&gt;.env&lt;/code&gt; 里的预设值，避免下次重建容器又变回旧密码。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇把监控栈的「脸」立起来了：Grafana 用官方镜像和 Prometheus 同 Compose 部署，管理员密码用环境变量预设、3000 只绑回环、对外套反代；数据源地址记住用服务名不要用 localhost；社区看板 1860 一键导入先把主机监控跑起来，再靠 &lt;code&gt;$job&lt;/code&gt; / &lt;code&gt;$instance&lt;/code&gt; 变量实现一板多机；最后用 provisioning 把数据源和看板沉淀成 Git 里的代码。下一篇进入 Loki，把日志也接进这同一块 Grafana 界面。&lt;/p&gt;
</content:encoded></item><item><title>监控与可观测性：Loki＋Promtail 日志聚合——像 Prometheus 一样管日志</title><link>https://www.anexns.cloudns.org/posts/monitoring-loki/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-loki/</guid><description>用 Loki＋Promtail 把散落在各台服务器和容器里的日志收拢到一处：只给标签建索引的轻量设计、LogQL 查询、保留期管理与标签基数红线，一篇走完从部署到排障的全流程。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;那个一台台 SSH 上去 grep 的夜晚&lt;/h2&gt;
&lt;p&gt;凌晨两点，服务报警，某个接口开始大面积返回 500。手边有六台服务器、二十多个容器，日志散在每一台机器上。于是开六个终端窗口，一个个 SSH 登录，&lt;code&gt;docker logs&lt;/code&gt; 看最近输出，&lt;code&gt;grep ERROR&lt;/code&gt; 翻关键字，再对着时间戳在脑子里把几台机器的日志拼成一条时间线。等拼明白，半小时过去了，故障窗口里最关键的那几分钟日志，还被新日志冲掉了一部分。&lt;/p&gt;
&lt;p&gt;这种排障方式的问题不在手速，在于日志本身是「散装」的：没有统一入口、没有统一时间轴、没有跨机器检索。指标那边早就解决了这个问题——Prometheus 把所有机器的指标收拢到一处，Grafana 里一个面板看全局；日志这边却还停留在单机时代。这一篇要装的 Loki，干的正是把日志也收拢起来的事：每台机器、每个容器的日志实时汇到一个地方，在 Grafana 里和指标面板并排打开，按标签和关键字一查到底。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/grafana/loki&lt;/p&gt;
&lt;h2&gt;Loki 的设计：只给标签建索引&lt;/h2&gt;
&lt;p&gt;Loki 是 Grafana Labs 出品的日志聚合系统，设计理念一句话概括：&lt;strong&gt;像 Prometheus 一样做日志&lt;/strong&gt;。它和 Elasticsearch 那一派最大的区别在索引策略上。ELK 会把日志全文切词建索引，查什么都快，但索引本身往往比日志还大，内存和磁盘成本居高不下；Loki 反过来，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;只给标签（label）建索引，日志正文不做全文索引、压缩后整块存放&amp;lt;/span&amp;gt;，所以同一批日志在 Loki 里占用的存储通常比在 ELK 里低一个数量级，一台小内存的 VPS 就能跑得很稳。&lt;/p&gt;
&lt;p&gt;代价也要说清楚：Loki 的查询是「先用标签把范围缩到某几个日志流，再在流内做文本过滤」，本质是带索引的 grep。它不适合拿任意关键词在全量日志里做秒级全文检索；但真实排障场景里，你几乎总是先知道「哪台机器、哪个服务、大概什么时间」，标签加时间窗已经把范围缩得足够小，流内过滤的速度完全够用。想清楚这个取舍，就理解了 Loki 的全部设计。&lt;/p&gt;
&lt;p&gt;整套系统三个角色：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;组件&lt;/th&gt;
&lt;th&gt;角色&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Loki&lt;/td&gt;
&lt;td&gt;服务端&lt;/td&gt;
&lt;td&gt;接收、索引、存储、查询，HTTP 端口 3100&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Promtail&lt;/td&gt;
&lt;td&gt;采集端&lt;/td&gt;
&lt;td&gt;装在每台机器上，读日志文件或容器日志，打好标签推给 Loki&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Grafana&lt;/td&gt;
&lt;td&gt;查询端&lt;/td&gt;
&lt;td&gt;加 Loki 数据源后在 Explore 里查日志，与 Prometheus 面板同屏关联&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;Docker Compose 一把梭&lt;/h2&gt;
&lt;p&gt;单机自用直接用官方的单体（monolithic）模式，一个 Loki 进程包办全部工作。下面这份 compose 把三件套都带上，Grafana 如果已经装过可以删掉那一段，只留 Loki＋Promtail：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  loki:
    image: grafana/loki:latest
    container_name: loki
    ports:
      - &quot;127.0.0.1:3100:3100&quot;
    volumes:
      - ./loki-config.yaml:/etc/loki/local-config.yaml
      - loki-data:/loki
    command: -config.file=/etc/loki/local-config.yaml
    restart: unless-stopped

  promtail:
    image: grafana/promtail:latest
    container_name: promtail
    volumes:
      - ./promtail-config.yaml:/etc/promtail/config.yaml
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /var/log:/var/log:ro
    command: -config.file=/etc/promtail/config.yaml
    restart: unless-stopped

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - &quot;3000:3000&quot;
    volumes:
      - grafana-data:/var/lib/grafana
    restart: unless-stopped

volumes:
  loki-data:
  grafana-data:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 Loki 的端口绑了 &lt;code&gt;127.0.0.1&lt;/code&gt;：它默认没有鉴权，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把 3100 端口直接暴露到公网&amp;lt;/span&amp;gt;，远程写入靠反向代理加认证，或者干脆走内网和隧道。Promtail 挂了 Docker socket，是为了用服务发现自动盯上每个容器；这也意味着 Promtail 权限不低，配置文件要管好。&lt;/p&gt;
&lt;h2&gt;Loki 配置：存储与保留期&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;loki-config.yaml&lt;/code&gt; 用单体模式的经典写法，存储先用本地 filesystem，个人和小团队规模完全够用，日后再迁对象存储也不难：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;auth_enabled: false

server:
  http_listen_port: 3100

common:
  instance_addr: 127.0.0.1
  path_prefix: /loki
  storage:
    filesystem:
      chunks_directory: /loki/chunks
      rules_directory: /loki/rules
  replication_factor: 1
  ring:
    kvstore:
      store: inmemory

schema_config:
  configs:
    - from: 2020-10-24
      store: tsdb
      object_store: filesystem
      schema: v13
      index:
        prefix: index_
        period: 24h

limits_config:
  retention_period: 720h

compactor:
  working_directory: /loki/compactor
  delete_request_store: filesystem
  retention_enabled: true
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个关键点。其一，索引用 TSDB schema（&lt;code&gt;store: tsdb&lt;/code&gt;），这是官方现行推荐，网上老教程里的 boltdb-shipper 写法已经过时，照抄容易在新版本上启动失败。其二，保留期不是改一个数字就完事：&lt;code&gt;retention_period&lt;/code&gt; 只是声明「想留多久」，真正执行删除的是 compactor，必须同时给它配上 &lt;code&gt;retention_enabled: true&lt;/code&gt; 和删除请求存储。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;只写 retention_period 而不开 compactor，日志只进不出，磁盘迟早被撑满&amp;lt;/span&amp;gt;——这是新手最常见的坑。上面配的 720h 即 30 天，按自己的磁盘大小和排障习惯调整。&lt;/p&gt;
&lt;h2&gt;Promtail 配置：采集与打标签&lt;/h2&gt;
&lt;p&gt;Promtail 是每台机器装一个的采集代理，负责三件事：发现日志在哪、给日志打标签、推给 Loki。配置里最重要的是 &lt;code&gt;scrape_configs&lt;/code&gt;，下面给两个最常用的 job：一个用 Docker 服务发现自动采集全部容器日志，一个采集宿主机上的普通日志文件。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: docker
    docker_sd_configs:
      - host: unix:///var/run/docker.sock
        refresh_interval: 5s
    relabel_configs:
      - source_labels: [__meta_docker_container_name]
        regex: /(.*)
        target_label: container
      - source_labels: [__meta_docker_container_label_com_docker_compose_service]
        target_label: service
    pipeline_stages:
      - docker: {}

  - job_name: system
    static_configs:
      - targets: [localhost]
        labels:
          job: varlogs
          host: server-01
          __path__: /var/log/*.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几点说明。&lt;code&gt;positions&lt;/code&gt; 文件记录每个日志文件读到哪一行，Promtail 重启后从断点续读，不会把历史日志重推一遍。&lt;code&gt;docker_sd_configs&lt;/code&gt; 会自动发现新容器，配合 relabel 把容器名、Compose 服务名提取成 &lt;code&gt;container&lt;/code&gt;、&lt;code&gt;service&lt;/code&gt; 标签，查日志时就靠它们定位。&lt;code&gt;pipeline_stages&lt;/code&gt; 是流水线处理环节：&lt;code&gt;docker: {}&lt;/code&gt; 把 Docker 的 JSON 日志外壳拆掉、只留正文和时间戳；日志本身是 JSON 格式的应用可以再加 &lt;code&gt;json&lt;/code&gt; 阶段把字段抽出来，是纯文本的可以用 &lt;code&gt;regex&lt;/code&gt; 阶段按正则提取等级、状态码等字段——抽出来的字段是查询时临时解析的「已解析字段」，不进索引，这一点和标签要分清。&lt;/p&gt;
&lt;p&gt;文件型日志的轮转、截断等基础处理逻辑，可以和 &lt;a href=&quot;/posts/linux-log-management/&quot;&gt;Linux 日志管理篇&lt;/a&gt; 对照着看；而 Docker 自带的日志驱动与轮转配置，在 &lt;a href=&quot;/posts/docker-logging/&quot;&gt;Docker 日志篇&lt;/a&gt; 里已经系统讲过，Promtail 是在那之上的集中化方案。&lt;/p&gt;
&lt;h2&gt;LogQL：查日志的语言&lt;/h2&gt;
&lt;p&gt;LogQL 长得像 PromQL，分两段：前半段是流选择器，用标签圈定范围；后半段是管道，对圈进来的日志逐行过滤和解析。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 圈定某个容器的日志流
{job=&quot;docker&quot;, container=&quot;nginx&quot;}

# 在流内做文本包含过滤
{job=&quot;docker&quot;} |= &quot;error&quot;

# 正则过滤，忽略大小写匹配超时与异常
{container=~&quot;api-.*&quot;} |~ &quot;(?i)timeout|exception&quot;

# JSON 日志：解析后按字段过滤
{job=&quot;docker&quot;} | json | status &amp;gt;= 500

# 纯文本日志：按 logfmt 解析后过滤
{job=&quot;docker&quot;} | logfmt | level=&quot;error&quot;

# 还能当指标用：统计每 5 分钟的错误行数
rate({job=&quot;docker&quot;} |= &quot;error&quot; [5m])
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;日常排障最顺手的组合是：先用 &lt;code&gt;{host=&quot;...&quot;, container=&quot;...&quot;}&lt;/code&gt; 把范围缩到出事的那个服务，把 Grafana 的时间窗拉到报警前后各十分钟，再 &lt;code&gt;|=&lt;/code&gt; 关键字逐层收窄。最后那条 &lt;code&gt;rate()&lt;/code&gt; 是 LogQL 的彩蛋——它把日志行数变成一条指标曲线，可以直接画进 Grafana 面板甚至配告警，等于日志顺手补上了指标的活。&lt;/p&gt;
&lt;h2&gt;在 Grafana 里和指标同屏&lt;/h2&gt;
&lt;p&gt;Loki 装好后，在 Grafana 里加一个 Loki 数据源，地址填 &lt;code&gt;http://loki:3100&lt;/code&gt;（同 compose 网络内用容器名即可），保存后进 Explore 就能跑上面的 LogQL。真正的杀手锏是关联：Prometheus 和 Loki 的标签体系是同一套思路，把两边同名标签对齐（比如都用 &lt;code&gt;job&lt;/code&gt;、&lt;code&gt;instance&lt;/code&gt;），就能在看指标面板时框选异常时间段，直接跳到同一时间窗的日志；反过来查日志时也能一键回到指标曲线。本系列 &lt;a href=&quot;/posts/monitoring-grafana/&quot;&gt;Grafana 篇&lt;/a&gt; 讲的面板与数据源基础在这里直接复用，指标、日志同屏之后，排障时在两个系统之间来回跳的次数明显减少。日志再往下走一步是链路追踪，三大支柱凑齐的思路见 &lt;a href=&quot;/posts/monitoring-tracing/&quot;&gt;链路追踪篇&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;标签设计：低基数是红线&lt;/h2&gt;
&lt;p&gt;Loki 的一切性能都建立在「日志流数量可控」上：每一组不同的标签组合就是一条独立的流，流越多，索引越大、查询越慢。标签该放什么、不该放什么，是用 Loki 的第一纪律。&lt;/p&gt;
&lt;p&gt;:::warning
标签只放低基数维度：&lt;code&gt;job&lt;/code&gt;、&lt;code&gt;host&lt;/code&gt;、&lt;code&gt;container&lt;/code&gt;、&lt;code&gt;service&lt;/code&gt;、&lt;code&gt;level&lt;/code&gt; 这类取值有限的字段。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不要把用户 ID、请求 ID、订单号、IP 地址这类高基数字段放进标签&amp;lt;/span&amp;gt;——每多一个取值就多一条流，几万个请求 ID 就能把索引撑爆，这是 Loki 头号事故，官方文档反复警告。需要按请求 ID 查时，把它留给管道过滤（&lt;code&gt;|=&lt;/code&gt; 或解析字段），那才是它的正确位置。
:::&lt;/p&gt;
&lt;p&gt;判断标准很简单：这个字段的全部可能取值能不能数得过来？服务名、主机名、日志等级可以，用户 ID、追踪 ID 不行。拿不准的字段一律先不打标签，用 &lt;code&gt;| json&lt;/code&gt;、&lt;code&gt;| logfmt&lt;/code&gt; 在查询时临时解析，等确认取值确实有限再提升为标签也不迟。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Promtail 读不到 Docker 日志。&lt;/strong&gt; 先查三件事：compose 里 &lt;code&gt;/var/run/docker.sock&lt;/code&gt; 有没有挂进去；Promtail 容器内的用户对 socket 有没有读权限（宿主机上 socket 的属组权限经常是元凶）；打开 Promtail 自己的 &lt;code&gt;http://localhost:9080/targets&lt;/code&gt; 页面，看目标是不是 active、last error 写了什么。文件型日志读不到同理，先看 targets 页和 positions 文件是否可写。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Grafana 里查不到日志。&lt;/strong&gt; 十有八九不是丢了，是没查对。先确认流选择器的标签和 Promtail 实际打的标签完全一致（标签名拼写、值都对上），再确认 Grafana 右上角的时间范围覆盖日志产生的时间——LogQL 查询严格按时间窗走，差一分钟都查不到。还不行就用 Loki 的接口直接验证：&lt;code&gt;curl &apos;http://localhost:3100/loki/api/v1/labels&apos;&lt;/code&gt; 看标签在不在，逐层缩小问题范围。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Loki 启动就报配置错误。&lt;/strong&gt; 多数是版本与 schema 不匹配：新版本镜像配了老教程的配置（boltdb-shipper、过时的 schema 版本号）最容易翻车。对策是配置以你实际拉取的镜像版本对应的官方文档为准，改 schema 时只新增一段 &lt;code&gt;configs&lt;/code&gt;、不要改动已生效的历史段，索引段一旦写错，老数据就查不出来了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;磁盘涨得比预期快。&lt;/strong&gt; 先算流的数量：标签基数失控时，chunk 文件会碎成海量小文件。去 Grafana 里用 &lt;code&gt;{job=~&quot;.+&quot;}&lt;/code&gt; 配合 &lt;code&gt;count_over_time&lt;/code&gt; 粗看各流的量，或者直接查 Loki 的 &lt;code&gt;/metrics&lt;/code&gt; 里按流统计的指标，揪出异常膨胀的标签组合。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Loki 的取舍非常清晰：放弃全文索引，换来极低的存储与运维成本，用「标签缩小范围＋管道过滤」覆盖绝大多数真实排障场景。如果你本来就在用 Prometheus＋Grafana，它几乎是零学习成本的补完——同一套标签哲学、同一套标签哲学、同一个 Grafana、同一套时间窗。已经在用 ELK 且依赖全文检索与复杂聚合的团队没必要迁；但如果你的日志还散在各台机器上、或者 ELK 的资源开销让你肉疼，Loki 是目前最省心的答案。把日志收拢到一处、和指标同屏、按标签一查到底，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;凌晨两点排障时，日志和指标终于有了同一个入口&amp;lt;/span&amp;gt;，那种开六个终端拼时间线的日子，就算是翻篇了。&lt;/p&gt;
</content:encoded></item><item><title>监控与可观测性：node_exporter 主机指标全解</title><link>https://www.anexns.cloudns.org/posts/monitoring-node-exporter/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-node-exporter/</guid><description>Prometheus 装好只是空架子，主机指标全靠 node_exporter：Docker 部署、collector 开关、textfile 自定义指标与关键指标解读一篇讲透。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先列个清单：Prometheus 装完，你还缺什么&lt;/h2&gt;
&lt;p&gt;上一篇把 Prometheus 跑起来之后，打开它的查询界面，你会发现一件事：能查的只有它自己的运行指标，宿主机本身的 CPU、内存、磁盘、网络一概没有。这不是装错了，而是分工本来就这样：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Prometheus 负责抓取、存储和查询，自己不采集主机数据&lt;/li&gt;
&lt;li&gt;主机指标由 &lt;strong&gt;node_exporter&lt;/strong&gt; 负责暴露，它就是一个常驻小进程，把内核与硬件状态翻译成 Prometheus 能读的文本格式&lt;/li&gt;
&lt;li&gt;每台被监控的机器装一个 node_exporter，Prometheus 定期来拉&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;项目地址：https://github.com/prometheus/node_exporter&lt;/p&gt;
&lt;p&gt;所以本篇的主线很明确：把 node_exporter 部署到每一台服务器上，讲清它的 collector 机制和自定义指标玩法，最后把最常看的那批主机指标逐个解读一遍。下一篇写 &lt;a href=&quot;/posts/monitoring-promql/&quot;&gt;PromQL 查询语言&lt;/a&gt; 时，所有例子都会用到这里出现的指标名，先混个脸熟。&lt;/p&gt;
&lt;h2&gt;它是怎么工作的&lt;/h2&gt;
&lt;p&gt;node_exporter 启动后监听 &lt;strong&gt;9100&lt;/strong&gt; 端口，访问 &lt;code&gt;http://&amp;lt;主机&amp;gt;:9100/metrics&lt;/code&gt; 就能看到当前全部指标，格式就是一行一个的文本：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# HELP node_memory_MemAvailable_bytes Memory information field MemAvailable_bytes.
# TYPE node_memory_MemAvailable_bytes gauge
node_memory_MemAvailable_bytes 6.214e+09
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它的数据来源是 Linux 内核暴露的 &lt;code&gt;/proc&lt;/code&gt;、&lt;code&gt;/sys&lt;/code&gt; 和根文件系统信息。负责采集每一类数据的模块叫 &lt;strong&gt;collector&lt;/strong&gt;：cpu、meminfo、filesystem、diskstats、netdev、loadavg 等等一批默认开启，各自读取对应的内核文件。理解了这一点，后面容器部署为什么要挂载宿主机目录、为什么有些指标在容器里读不准，就都顺理成章了。&lt;/p&gt;
&lt;h2&gt;Docker 部署：挂载是关键&lt;/h2&gt;
&lt;p&gt;官方镜像是 &lt;code&gt;prom/node-exporter&lt;/code&gt;。compose 写法如下，注意 volumes 与 command 两处配合，缺一不可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  node-exporter:
    image: prom/node-exporter:latest
    container_name: node-exporter
    restart: unless-stopped
    network_mode: host
    pid: host
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/host/rootfs:ro
    command:
      - &quot;--path.procfs=/host/proc&quot;
      - &quot;--path.sysfs=/host/sys&quot;
      - &quot;--path.rootfs=/host/rootfs&quot;
      - &quot;--collector.filesystem.mount-points-exclude=^/(sys|proc|dev|host|etc)($$|/)&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个要点逐条说清：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;三个挂载全部只读&lt;/strong&gt;（&lt;code&gt;:ro&lt;/code&gt;）。node_exporter 只读不写，给只读权限就够了，这也是它在安全上相对省心的原因之一。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--path.procfs&lt;/code&gt; 等参数告诉它去容器内的 &lt;code&gt;/host/*&lt;/code&gt; 路径读数据；不加这三个参数，它读的就是容器自己的 &lt;code&gt;/proc&lt;/code&gt;，采到的全是容器视角的假数据。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;network_mode: host&lt;/code&gt; 让它直接用宿主机网络，9100 端口不用再做映射；官方文档也推荐这种方式，或者至少共享宿主机 PID 命名空间（&lt;code&gt;pid: host&lt;/code&gt;），否则像进程、网络连接类 collector 的视角会受限。&lt;/li&gt;
&lt;li&gt;最后一条 &lt;code&gt;mount-points-exclude&lt;/code&gt; 把容器自身的系统挂载点从 filesystem collector 里排除，避免和宿主机真实分区重复、混杂。&lt;code&gt;$$&lt;/code&gt; 是 compose 里对 &lt;code&gt;$&lt;/code&gt; 的转义，别写丢。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;不用 Docker 也可以：GitHub Release 页有编译好的二进制，解压后直接 &lt;code&gt;./node_exporter&lt;/code&gt; 就能跑，systemd 托管一下即可，参数与上面完全一致。&lt;/p&gt;
&lt;p&gt;启动后先自检：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -s http://localhost:9100/metrics | head -20
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;能刷出一大片 &lt;code&gt;node_&lt;/code&gt; 开头的指标就说明采集正常。然后在 Prometheus 的 &lt;code&gt;prometheus.yml&lt;/code&gt; 里给每台机器加一个 target（&lt;a href=&quot;/posts/monitoring-prometheus/&quot;&gt;Prometheus 的部署与配置&lt;/a&gt; 里讲过 scrape_configs 的写法）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;scrape_configs:
  - job_name: &quot;node&quot;
    static_configs:
      - targets: [&quot;192.168.1.11:9100&quot;, &quot;192.168.1.12:9100&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
node_exporter 的 9100 端口和 Prometheus 一样&lt;strong&gt;没有任何鉴权&lt;/strong&gt;，谁能访问谁就能把你机器的硬件与系统信息看个底掉。多机部署时让它只走内网网段；确实需要跨网段访问的，用防火墙只放行 Prometheus 服务器的 IP，或者套一层带 Basic Auth 的反向代理。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不要把 /metrics 直接暴露到公网&amp;lt;/span&amp;gt;——网上长期有扫描器专门收集裸奔的 exporter。
:::&lt;/p&gt;
&lt;h2&gt;collector：按需开关采集模块&lt;/h2&gt;
&lt;p&gt;collector 是 node_exporter 的核心概念。用开关参数可以逐个控制：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 关掉某个默认开启的 collector
--no-collector.netdev

# 开启一个默认关闭的 collector
--collector.systemd
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;常用的几个值得单独认识：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;collector&lt;/th&gt;
&lt;th&gt;默认&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;cpu / meminfo / loadavg&lt;/td&gt;
&lt;td&gt;开&lt;/td&gt;
&lt;td&gt;CPU 时间、内存、负载，最基础的一批&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;filesystem / diskstats&lt;/td&gt;
&lt;td&gt;开&lt;/td&gt;
&lt;td&gt;分区容量、inode、磁盘读写&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;netdev / netstat&lt;/td&gt;
&lt;td&gt;开&lt;/td&gt;
&lt;td&gt;网卡流量与网络统计&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;systemd&lt;/td&gt;
&lt;td&gt;关&lt;/td&gt;
&lt;td&gt;各 systemd 单元的状态，做服务存活监控时很有用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;textfile&lt;/td&gt;
&lt;td&gt;开&lt;/td&gt;
&lt;td&gt;读取指定目录下的 &lt;code&gt;.prom&lt;/code&gt; 文件，把里面的指标一并暴露&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;processes&lt;/td&gt;
&lt;td&gt;关&lt;/td&gt;
&lt;td&gt;进程数量与状态统计，容器部署时视角受限&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;在 Docker 部署里加开关，就是往上面的 &lt;code&gt;command&lt;/code&gt; 列表里追加对应行。关掉用不上的 collector 能略微降低采集开销，不过更现实的意义是减少指标基数，让 Prometheus 的存储和查询都轻一点。&lt;/p&gt;
&lt;p&gt;还有一个补救位置在 Prometheus 那一侧：某个 collector 暂时关不掉、或者同一 exporter 要喂给多个用途时，可以在 scrape 配置里用 &lt;code&gt;metric_relabel_configs&lt;/code&gt; 在入库前丢弃不需要的指标序列。比如只关心真实磁盘、想在源头就扔掉回环网卡流量时，按 &lt;code&gt;device=&quot;lo&quot;&lt;/code&gt; 做 drop 即可。原则是能在 exporter 端关的优先关，关不掉的再在抓取端过滤，双管齐下把基数压住。&lt;/p&gt;
&lt;h2&gt;textfile collector：把脚本结果变成指标&lt;/h2&gt;
&lt;p&gt;这是 node_exporter 最实用的扩展点。它会读取一个目录（默认 &lt;code&gt;/var/lib/node_exporter/textfile_collector&lt;/code&gt;，可用 &lt;code&gt;--collector.textfile.directory&lt;/code&gt; 改）下所有 &lt;code&gt;.prom&lt;/code&gt; 文件，把内容合并进 &lt;code&gt;/metrics&lt;/code&gt; 输出。于是任何脚本能算出来的东西，都能变成 Prometheus 指标：证书剩余天数、备份是否成功、某个目录的大小……&lt;/p&gt;
&lt;p&gt;以「上次备份距今多久」为例，备份脚本跑完后顺手写一个文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
DIR=/var/lib/node_exporter/textfile_collector
echo &quot;backup_last_success_timestamp_seconds $(date +%s)&quot; &amp;gt; &quot;$DIR/backup.prom.$$&quot;
mv &quot;$DIR/backup.prom.$$&quot; &quot;$DIR/backup.prom&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个细节：先写临时文件再 &lt;code&gt;mv&lt;/code&gt; 覆盖，是为了避免 node_exporter 读到写了一半的内容；文件名必须以 &lt;code&gt;.prom&lt;/code&gt; 结尾。之后在 Grafana 里对这个时间戳做个告警，超过 26 小时没更新就报警，备份任务静默失败的问题就兜住了——这类「业务巡检指标化」的思路，和 &lt;a href=&quot;/posts/linux-server-monitoring/&quot;&gt;Linux 服务器监控&lt;/a&gt; 里用脚本巡检的做法是一脉相承的，只是现在结果进了时序库，能画图、能告警、能回溯。&lt;/p&gt;
&lt;h2&gt;关键指标解读&lt;/h2&gt;
&lt;p&gt;指标成百上千，日常真正盯的就这么一批。先记住一个分类：名字带 &lt;code&gt;_total&lt;/code&gt; 的是 &lt;strong&gt;counter&lt;/strong&gt;（只增不减的累计值，看速率要用 &lt;code&gt;rate()&lt;/code&gt; 加工）；其余多为 &lt;strong&gt;gauge&lt;/strong&gt;（瞬时值，直接看数）。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;指标&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;看什么异常&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;node_cpu_seconds_total&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;CPU 累计时间，按 &lt;code&gt;mode&lt;/code&gt; 标签拆分（user/system/idle/iowait…）&lt;/td&gt;
&lt;td&gt;idle 占比持续过低说明 CPU 吃紧；iowait 高是磁盘在拖后腿&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;node_memory_MemAvailable_bytes&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;内核估算的可用内存（含可回收缓存）&lt;/td&gt;
&lt;td&gt;持续走低逼近 0 是内存耗尽前兆；别用 MemFree 判断，它不含缓存会误报&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;node_filesystem_avail_bytes&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;分区可用空间，带 &lt;code&gt;mountpoint&lt;/code&gt;、&lt;code&gt;fstype&lt;/code&gt; 标签&lt;/td&gt;
&lt;td&gt;可用比例低于 10% 就该处理；注意排除 overlay、tmpfs 等伪文件系统&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;node_filesystem_files_free&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;剩余 inode 数&lt;/td&gt;
&lt;td&gt;空间还有但 inode 耗尽同样写不进文件，小文件多的机器重点看&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;node_disk_read_bytes_total&lt;/code&gt; / &lt;code&gt;node_disk_written_bytes_total&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;磁盘累计读/写字节数，按 &lt;code&gt;device&lt;/code&gt; 拆分&lt;/td&gt;
&lt;td&gt;rate 长期顶格说明 IO 饱和；异常写入暴增要查是谁在写&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;node_network_receive_bytes_total&lt;/code&gt; / &lt;code&gt;node_network_transmit_bytes_total&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;网卡累计收/发字节数，按 &lt;code&gt;device&lt;/code&gt; 拆分&lt;/td&gt;
&lt;td&gt;流量突增突降都是信号；记得排除 &lt;code&gt;lo&lt;/code&gt; 回环&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;node_load1&lt;/code&gt; / &lt;code&gt;node_load5&lt;/code&gt; / &lt;code&gt;node_load15&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;1/5/15 分钟平均负载&lt;/td&gt;
&lt;td&gt;持续超过 CPU 核数说明任务在排队；结合 CPU 使用率判断是算力还是 IO 问题&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;node_boot_time_seconds&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;开机时刻的 Unix 时间戳&lt;/td&gt;
&lt;td&gt;用 &lt;code&gt;time() - node_boot_time_seconds&lt;/code&gt; 算运行时长；时间戳突然变新＝机器重启过&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;其中最容易记错的是内存：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;判断内存够不够，只看 MemAvailable，不要看 MemFree&amp;lt;/span&amp;gt;。Linux 会拿空闲内存做缓存，MemFree 很小是常态，MemAvailable 才是「应用真要用时能拿到多少」的估算值。&lt;/p&gt;
&lt;p&gt;CPU 使用率则是典型的 counter 加工题：&lt;code&gt;node_cpu_seconds_total&lt;/code&gt; 本身是个累计秒数，两个时间点的差除以时间间隔才是占比，再按 mode 聚合，就能拆出 user、system、iowait 各占多少——这正是下一篇 PromQL 要动手练的第一类查询。&lt;/p&gt;
&lt;h2&gt;排障小节&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;容器里采到的指标和宿主机对不上。&lt;/strong&gt; 十有八九是挂载或路径参数漏了：检查 &lt;code&gt;/proc&lt;/code&gt;、&lt;code&gt;/sys&lt;/code&gt;、根目录三个挂载是否都在、是否只读，&lt;code&gt;--path.procfs&lt;/code&gt; 等三个参数是否与挂载点对应。少任何一个，它就退回读容器自身的数据。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;磁盘、分区指标出现一堆重复设备。&lt;/strong&gt; 容器运行时会带来 overlay、shm 等挂载点，和真实分区混在一起。用前面 compose 里的 &lt;code&gt;mount-points-exclude&lt;/code&gt; 排除系统路径，查询时再用 &lt;code&gt;fstype&lt;/code&gt; 标签过滤掉 &lt;code&gt;overlay&lt;/code&gt;、&lt;code&gt;tmpfs&lt;/code&gt;；磁盘设备同理，&lt;code&gt;device&lt;/code&gt; 标签里只保留 &lt;code&gt;sd*&lt;/code&gt;、&lt;code&gt;nvme*&lt;/code&gt;、&lt;code&gt;vd*&lt;/code&gt; 这类真实盘。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Prometheus 里 target 显示 DOWN。&lt;/strong&gt; 先在 Prometheus 所在机器上直接 &lt;code&gt;curl http://&amp;lt;目标&amp;gt;:9100/metrics&lt;/code&gt;，通不通立刻见分晓：不通是网络或防火墙问题（9100 没放行最常见），通了再回头查 prometheus.yml 里 target 地址写错没有。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;某些 collector 指标缺失。&lt;/strong&gt; 先确认部署方式：systemd collector 在容器里基本采不到宿主机的单元状态，这类需求建议二进制＋systemd 方式部署；其次查启动参数有没有被 &lt;code&gt;--no-collector&lt;/code&gt; 误关，或者版本太旧还没有该 collector。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;textfile 指标不出现。&lt;/strong&gt; 依次查：文件是不是 &lt;code&gt;.prom&lt;/code&gt; 后缀、目录与 &lt;code&gt;--collector.textfile.directory&lt;/code&gt; 是否一致、文件格式是否合法（一行一个指标、数值可解析）、写入时是否用了临时文件＋改名的原子写法。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;node_exporter 在整个监控体系里站的是「数据源」这一环：部署的关键只有一句——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;让它读到宿主机的 /proc、/sys 与根文件系统&amp;lt;/span&amp;gt;，其余都是围绕这件事的细节。collector 决定采什么，textfile collector 让任意脚本结果也能入列，而真正要花心思的是最后那张指标表：先把 CPU、MemAvailable、分区与 inode、磁盘与网络速率、负载这几样看熟，后面无论是写 PromQL 还是在 &lt;a href=&quot;/posts/monitoring-grafana/&quot;&gt;Grafana 里做仪表盘&lt;/a&gt;，用的都是它们。&lt;/p&gt;
</content:encoded></item><item><title>监控与可观测性：Prometheus 部署实战，从第一个 Target 到热重载</title><link>https://www.anexns.cloudns.org/posts/monitoring-prometheus/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-prometheus/</guid><description>用 Docker Compose 部署 Prometheus：写好 prometheus.yml、抓起第一个 Target、留存与热重载参数一次配齐，把服务从「挂没挂」监控到「怎么一点点坏的」。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;面板说「挂了」，但你想知道它是怎么坏的&lt;/h2&gt;
&lt;p&gt;凌晨三点，探针面板弹出一条告警：某台服务器离线。你打开面板，能看到的只有一条平直的心跳线和一个红色的状态点——它只能告诉你「挂了」，挂掉之前 CPU 是慢慢爬满的、内存是被某个进程一口口吃掉的、还是磁盘 I/O 先一步堵死，它一概不知。等你 SSH 上去，现场早就凉了，连复盘都无从下手。&lt;/p&gt;
&lt;p&gt;Prometheus 解决的正是这个问题。它按固定间隔把每个服务的指标抓下来存成时间序列，事后你可以把任意一段时间拉出来回放：故障前十分钟内存曲线的斜率、接口延迟从 P50 到 P99 的爬升过程、错误率第一次抖动的确切时刻。上一篇我们聊过&lt;a href=&quot;/posts/monitoring-concepts/&quot;&gt;监控与可观测性的基本概念&lt;/a&gt;，这一篇动手把 Prometheus 本体部署起来，抓起第一个 Target，并把留存时间、热重载这些迟早要踩的配置一次配齐。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/prometheus/prometheus&lt;/p&gt;
&lt;h2&gt;先理解它的工作方式：主动来抓&lt;/h2&gt;
&lt;p&gt;Prometheus 和很多监控工具最大的不同是&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;拉取模型：不是被监控对象把数据推过来，而是 Prometheus 按配置主动去抓&amp;lt;/span&amp;gt;。每个被监控对象（官方叫 Target）只需在一个 HTTP 端点上暴露自己的指标，约定路径是 &lt;code&gt;/metrics&lt;/code&gt;，内容是纯文本格式。Prometheus 按 &lt;code&gt;scrape_interval&lt;/code&gt; 设定的节奏逐个访问这些端点，把返回的数值连同时间戳存进自带的时间序列数据库（TSDB）。&lt;/p&gt;
&lt;p&gt;这个模型带来几个实际好处：目标活没活，抓取成功与否本身就是答案，抓不到就是 DOWN，不需要额外心跳；抓取节奏、超时、重试全在服务端一处配置，目标端无状态、无需改造；多台 Prometheus 抓同一个目标互不干扰。代价是短命任务（跑完就退出的批处理作业）可能等不到下一次抓取就消失了，那种场景要用 Pushgateway 中转，本系列后面会单独讲。&lt;/p&gt;
&lt;p&gt;部署形态上，Prometheus 官方提供二进制和 Docker 镜像两种方式。本站一贯的习惯是容器化：官方镜像 &lt;code&gt;prom/prometheus&lt;/code&gt;，默认端口 9090，配置和数据都外置挂载，升级换镜像即可。&lt;/p&gt;
&lt;h2&gt;部署：一个 Compose 搞定&lt;/h2&gt;
&lt;p&gt;先建目录，把配置文件和数据目录规划好：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p /opt/prometheus/data
cd /opt/prometheus
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;写 prometheus.yml&lt;/h3&gt;
&lt;p&gt;这是 Prometheus 的主配置文件，先写一个能跑通的最小版本：全局参数加上第一个抓取任务——抓它自己。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;global:
  scrape_interval: 15s        # 默认抓取间隔
  scrape_timeout: 10s         # 单次抓取超时，必须小于间隔
  evaluation_interval: 15s    # 告警规则的评估间隔

alerting:
  alertmanagers:
    - static_configs:
        - targets: []
          # 后续接入 Alertmanager 时填地址，如 alertmanager:9093

rule_files:
  # - &quot;rules/*.yml&quot;           # 告警与记录规则文件，后续篇目再加

scrape_configs:
  - job_name: &quot;prometheus&quot;
    static_configs:
      - targets: [&quot;localhost:9090&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个字段先认清，后面所有篇目都围着它转：&lt;code&gt;global&lt;/code&gt; 段是全局默认值，单个 job 可以覆盖；&lt;code&gt;scrape_configs&lt;/code&gt; 里每一项是一个 job，&lt;code&gt;job_name&lt;/code&gt; 是这组目标的名字，会成为指标上 &lt;code&gt;job&lt;/code&gt; 标签的值；&lt;code&gt;static_configs&lt;/code&gt; 是静态写死的目标列表，&lt;code&gt;targets&lt;/code&gt; 里填 &lt;code&gt;主机:端口&lt;/code&gt;。自监控 job 是个好习惯——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Prometheus 先抓自己，你才能从它自身的指标判断抓取链路是否健康&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h3&gt;写 docker-compose.yml&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    restart: unless-stopped
    command:
      - &quot;--config.file=/etc/prometheus/prometheus.yml&quot;
      - &quot;--storage.tsdb.path=/prometheus&quot;
      - &quot;--storage.tsdb.retention.time=30d&quot;
      - &quot;--web.enable-lifecycle&quot;
    ports:
      - &quot;127.0.0.1:9090:9090&quot;
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus-data:/prometheus

volumes:
  prometheus-data:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动并确认状态：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose ps
docker compose logs --tail=50 prometheus
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;http://服务器地址:9090&lt;/code&gt;，能看到 Prometheus 自带的 Web UI 就说明本体起来了。这个界面不花哨，但查指标、看 Target 状态、临时验证 PromQL 表达式都靠它，是后面几篇的常用工具。&lt;/p&gt;
&lt;h3&gt;两个启动参数现在就配上&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;--storage.tsdb.retention.time=30d&lt;/code&gt; 是数据留存时间。TSDB 默认按时间留存 15 天，对个人服务器来说，看故障复盘经常需要往前翻一个月，这里直接设 30 天。留存越长吃磁盘越多，这是一笔要算的账：粗略估算，单个 Target 每秒约产生 1–2 字节的压缩后数据，一百个 Target、15 秒间隔，30 天大约在 10–20 GB 量级，具体取决于指标基数。先给数据卷留够空间，并养成看磁盘水位的习惯，具体排查方法在排障一节。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;--web.enable-lifecycle&lt;/code&gt; 开启生命周期接口。开启后，改完 &lt;code&gt;prometheus.yml&lt;/code&gt; 不必重启容器，一条命令热重载：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -X POST http://localhost:9090/-/reload
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回 200 就说明新配置已生效。这个参数默认关闭，很多人第一次改配置发现不生效，就是卡在这里——没开这个参数，又没重启容器。注意它和 &lt;code&gt;--web.enable-admin-api&lt;/code&gt; 是两回事，后者包含删数据等危险操作，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要顺手打开 admin API&amp;lt;/span&amp;gt;，本系列用不到它。&lt;/p&gt;
&lt;h2&gt;验证：Targets 页面验活&lt;/h2&gt;
&lt;p&gt;部署对不对，去 UI 的 Status → Targets 页面看。自监控 job 应该显示为 UP，Last Scrape 是十几秒内的时间，Scrape Duration 是毫秒级耗时。这一页以后每加一个 job 都要回来确认一次：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;UP&lt;/strong&gt;：抓取正常，指标在持续入库。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;DOWN&lt;/strong&gt;：抓取失败，右边会给出具体错误，如 connection refused（目标没监听）、context deadline exceeded（超时）、404（路径不对）等，照着错误查即可。&lt;/li&gt;
&lt;li&gt;目标刚加进来时短暂显示 UNKNOWN 是正常的，等一个抓取周期即可。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;再随手验证一条查询：在 Graph 页面的查询框输入 &lt;code&gt;up&lt;/code&gt;，应该能查到 &lt;code&gt;up{job=&quot;prometheus&quot;} = 1&lt;/code&gt;。&lt;code&gt;up&lt;/code&gt; 是 Prometheus 为每次抓取自动生成的指标，1 表示成功、0 表示失败，它是你以后写可用性告警的根基。&lt;/p&gt;
&lt;h2&gt;再往前一步：抓一个别的服务&lt;/h2&gt;
&lt;p&gt;自监控跑通后，加目标就是往 &lt;code&gt;scrape_configs&lt;/code&gt; 里追加 job。假设另一台服务器上已经跑着一个暴露 &lt;code&gt;/metrics&lt;/code&gt; 的服务，配置这样写：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;  - job_name: &quot;example-service&quot;
    scrape_interval: 30s
    static_configs:
      - targets: [&quot;192.168.1.20:9100&quot;]
        labels:
          env: &quot;prod&quot;
          host: &quot;srv-02&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意三处细节：这个 job 单独把间隔放宽到 30 秒，覆盖了全局的 15 秒——不是所有目标都值得高频抓取，间隔越短，存储和目标端压力越大；&lt;code&gt;labels&lt;/code&gt; 里手动补了 &lt;code&gt;env&lt;/code&gt; 和 &lt;code&gt;host&lt;/code&gt; 两个标签，之后查询时可以按环境、按机器筛选和聚合，这是静态配置下区分同类目标的常用手法；每个 job 的目标各自独立验活，一个 DOWN 不影响其他 job 的抓取。改完照旧先校验再热重载：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec prometheus promtool check config /etc/prometheus/prometheus.yml
curl -X POST http://localhost:9090/-/reload
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后回 Targets 页面确认新 job 是 UP。至此，一套「改配置 → 校验 → 热重载 → 验活」的标准动作就成型了，后面接入 Node Exporter、各种应用 Exporter 时，重复的都是这套动作，区别只在目标端怎么把指标暴露出来。&lt;/p&gt;
&lt;h2&gt;指标四种类型，先混个脸熟&lt;/h2&gt;
&lt;p&gt;打开任意一个成熟 Exporter 的 &lt;code&gt;/metrics&lt;/code&gt;，你会看到成百上千行指标。它们归为四种类型，理解类型才知道该用什么函数处理（查询语言 PromQL 会在&lt;a href=&quot;/posts/monitoring-promql/&quot;&gt;PromQL 查询入门&lt;/a&gt;里系统讲，这里先认脸）：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;典型例子&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Counter&lt;/td&gt;
&lt;td&gt;只增不减的计数器，重启才归零&lt;/td&gt;
&lt;td&gt;请求总数、错误总数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gauge&lt;/td&gt;
&lt;td&gt;可上可下的瞬时值&lt;/td&gt;
&lt;td&gt;内存使用量、当前连接数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Histogram&lt;/td&gt;
&lt;td&gt;分桶统计分布，可算分位数&lt;/td&gt;
&lt;td&gt;请求延迟、响应大小&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Summary&lt;/td&gt;
&lt;td&gt;客户端预先算好的分位数&lt;/td&gt;
&lt;td&gt;延迟 P50/P99（客户端侧）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一句话区分：Counter 看的是「速率」，用 &lt;code&gt;rate()&lt;/code&gt; 算每秒增量；Gauge 看的是「当前值」，直接画线；Histogram 和 Summary 都为延迟这类分布型数据而生，区别在分位数在哪一侧计算——Histogram 在服务端算、可以跨实例聚合，Summary 在客户端算、精度高但不能聚合，所以实际部署里 Histogram 用得更多。&lt;/p&gt;
&lt;h2&gt;安全提醒&lt;/h2&gt;
&lt;p&gt;:::warning
Prometheus 的 9090 端口&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;默认没有任何身份验证&amp;lt;/span&amp;gt;，谁能访问这个端口，谁就能查到你全部监控数据，还能通过生命周期接口重载配置。&lt;strong&gt;不要把 9090 裸奔在公网&lt;/strong&gt;：像上面的 Compose 示例一样只绑定 &lt;code&gt;127.0.0.1&lt;/code&gt;，远程查看时走 SSH 隧道，或者套一层带鉴权的反向代理（如 Nginx Proxy Manager 加访问控制）再对外。监控数据泄露出去，等于把整套服务的运行状态、接口路径和版本信息拱手送人。
:::&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Target 一直是 DOWN。&lt;/strong&gt; 先看 Targets 页面给出的错误原文。connection refused 多半是目标进程没起来或端口写错，在 Prometheus 容器内 &lt;code&gt;wget -qO- http://目标:端口/metrics&lt;/code&gt; 能否拿到文本可以快速定界；如果目标在另一台机器，先确认防火墙与安全组放行了抓取端口；路径 404 则检查目标暴露的是不是 &lt;code&gt;/metrics&lt;/code&gt;，有些应用挂在别的路径下，需要在 job 里用 &lt;code&gt;metrics_path&lt;/code&gt; 指定。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;改了 prometheus.yml 不生效。&lt;/strong&gt; 三种可能：没开 &lt;code&gt;--web.enable-lifecycle&lt;/code&gt; 又没调 &lt;code&gt;/-/reload&lt;/code&gt;，配置根本没重载；配置文件是通过单文件挂载进容器的，某些编辑器保存时换了 inode，容器里看到的还是旧文件，改用重建容器或目录挂载解决；YAML 语法写错导致重载失败，此时 &lt;code&gt;/-/reload&lt;/code&gt; 会返回错误，容器日志里也有明确行号，先用官方自带的校验工具过一遍：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec prometheus promtool check config /etc/prometheus/prometheus.yml
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;养成习惯：每次改完配置先 &lt;code&gt;promtool check&lt;/code&gt;，通过了再 reload，能省掉一半折腾。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;磁盘被 TSDB 吃满。&lt;/strong&gt; 先确认是不是 Prometheus 的数据目录在涨：&lt;code&gt;du -sh&lt;/code&gt; 看数据卷，再到 UI 的 Status → TSDB Status 页面看每个 job 的指标基数（Cardinality），基数爆炸通常是某个 Exporter 或业务指标把高变值（如用户 ID、完整 URL）打进了标签。处置顺序：先把 &lt;code&gt;retention.time&lt;/code&gt; 调小并重启争取空间，再定位高基数指标，在抓取侧用 &lt;code&gt;metric_relabel_configs&lt;/code&gt; 丢弃。切记&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要在容器运行时手动删 TSDB 的数据块文件&amp;lt;/span&amp;gt;，删坏块结构会导致 Prometheus 启动失败，只能整库重来。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;抓取总是超时。&lt;/strong&gt; Targets 页面看 Scrape Duration，若逼近 &lt;code&gt;scrape_timeout&lt;/code&gt;，多半是目标端 &lt;code&gt;/metrics&lt;/code&gt; 生成太慢（常见于数据量大的 Exporter 全量计算），或网络跨地域延迟高。对策是给这个 job 单独放宽 &lt;code&gt;scrape_interval&lt;/code&gt; 与 &lt;code&gt;scrape_timeout&lt;/code&gt;，而不是改全局值拖慢所有 job。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇把 Prometheus 本体立了起来：拉取模型、Compose 部署、30 天留存、生命周期热重载、自监控验活，再加上指标四类型的初步印象。此时它只在盯着自己看，真正的价值要等数据进来——下一篇我们给每台服务器装上 &lt;a href=&quot;/posts/monitoring-node-exporter/&quot;&gt;Node Exporter&lt;/a&gt;，把 CPU、内存、磁盘、网络这些主机指标全部接入；如果你之前跟过 Docker 系列的监控篇，也可以对照看看&lt;a href=&quot;/posts/docker-monitoring-prometheus/&quot;&gt;Docker 场景下的 Prometheus 部署&lt;/a&gt;有何异同。地基已经打好，后面就是往里接数据、写查询、配告警三步走。&lt;/p&gt;
</content:encoded></item><item><title>监控与可观测性：PromQL 实战手册——先抄模板，再理解语法</title><link>https://www.anexns.cloudns.org/posts/monitoring-promql/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-promql/</guid><description>从数据类型、标签选择器、rate() 到 histogram_quantile()，用一套可直接套用的 PromQL 模板解决 CPU、内存、磁盘、网络、HTTP 与容器监控查询。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;PromQL 劝退的不是难度，是没人先给你模板&lt;/h2&gt;
&lt;p&gt;PromQL 第一次看很像把 SQL、正则表达式和数学函数揉在了一起：括号套括号，标签一长串，最后还分不清为什么查询结果是空的。其实它没有那么神秘，大多数日常查询只是在重复几件事：先按标签选出指标，再对 Counter 计算变化率，接着聚合、做除法，最后得到使用率、吞吐量或错误比例。&lt;/p&gt;
&lt;p&gt;所以这篇不从抽象语法开始背，而是先把常用模板摆出来，再回头解释每个部件。配合&lt;a href=&quot;/posts/monitoring-node-exporter/&quot;&gt;上一篇的 Node Exporter 指标&lt;/a&gt;和&lt;a href=&quot;/posts/monitoring-prometheus/&quot;&gt;Prometheus 基础&lt;/a&gt;，你可以直接把模板放进 Grafana 面板或告警规则里改标签使用。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;PromQL 的核心顺序只有一句：先选对指标和标签，再选对函数，最后才做聚合与运算。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;参考文档：https://prometheus.io/docs/prometheus/latest/querying/basics/&lt;/p&gt;
&lt;h2&gt;先认清四种数据&lt;/h2&gt;
&lt;p&gt;PromQL 表达式的结果主要有四种类型。先分清它们，很多“为什么不能这样写”的问题就自动消失了。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;例子&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;瞬时向量（Instant Vector）&lt;/td&gt;
&lt;td&gt;某一时刻的一组时间序列&lt;/td&gt;
&lt;td&gt;&lt;code&gt;node_cpu_seconds_total{mode=&quot;idle&quot;}&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;区间向量（Range Vector）&lt;/td&gt;
&lt;td&gt;一段时间范围内的一组样本&lt;/td&gt;
&lt;td&gt;&lt;code&gt;node_cpu_seconds_total[5m]&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;标量（Scalar）&lt;/td&gt;
&lt;td&gt;一个没有标签的数字&lt;/td&gt;
&lt;td&gt;&lt;code&gt;time()&lt;/code&gt;、&lt;code&gt;42&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;字符串（String）&lt;/td&gt;
&lt;td&gt;一段文本，使用场景很有限&lt;/td&gt;
&lt;td&gt;&lt;code&gt;&quot;ready&quot;&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;最容易混淆的是前两种。&lt;code&gt;up&lt;/code&gt; 是瞬时向量，表示查询时刻每条序列的值；&lt;code&gt;up[5m]&lt;/code&gt; 是区间向量，表示过去 5 分钟内的样本集合。区间向量通常不能直接画成一条普通曲线，它更像是交给 &lt;code&gt;rate()&lt;/code&gt;、&lt;code&gt;increase()&lt;/code&gt;、&lt;code&gt;avg_over_time()&lt;/code&gt; 等函数的原材料。&lt;/p&gt;
&lt;p&gt;指标名本身也是一种标签选择。Prometheus 内部把指标名存放在 &lt;code&gt;__name__&lt;/code&gt; 标签中，所以选择器本质上是在按标签筛选时间序列。&lt;/p&gt;
&lt;h2&gt;选择器与标签匹配：先把范围缩小&lt;/h2&gt;
&lt;p&gt;选择器由指标名和花括号中的标签条件组成：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;node_network_receive_bytes_total{
  instance=&quot;server-01:9100&quot;,
  device!=&quot;lo&quot;,
  device!~&quot;veth.*|docker.*&quot;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;四种标签匹配符必须分清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;匹配符&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;典型用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;完全相等&lt;/td&gt;
&lt;td&gt;固定实例、状态码、磁盘设备&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;!=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不相等&lt;/td&gt;
&lt;td&gt;排除空闲模式或回环网卡&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;=~&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;正则匹配&lt;/td&gt;
&lt;td&gt;一次匹配多个状态码或设备&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;!~&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;正则不匹配&lt;/td&gt;
&lt;td&gt;排除一组临时设备&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;有三个细节值得记住。第一，PromQL 的正则表达式是&lt;strong&gt;完全锚定&lt;/strong&gt;的，&lt;code&gt;device=~&quot;eth&quot;&lt;/code&gt; 只匹配值恰好为 &lt;code&gt;eth&lt;/code&gt; 的标签，不会匹配 &lt;code&gt;eth0&lt;/code&gt;，应写成 &lt;code&gt;device=~&quot;eth.*&quot;&lt;/code&gt; 或 &lt;code&gt;device=~&quot;eth.+&quot;&lt;/code&gt;。第二，负向匹配可能选中“根本没有这个标签”的序列，所以排除前最好先在 Explore 里看看结果包含哪些序列。第三，不要一上来就用过宽的正则扫描高基数标签，查询范围越大，Prometheus 的计算压力越高。&lt;/p&gt;
&lt;p&gt;例如，HTTP 5xx 状态码可以写成：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;http_requests_total{status=~&quot;5..&quot;}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里的 &lt;code&gt;5..&lt;/code&gt; 表示以 5 开头、后面跟任意两个字符，比逐个列出 500、502、503 更简洁。&lt;/p&gt;
&lt;h2&gt;区间向量与 rate()：Counter 的正确打开方式&lt;/h2&gt;
&lt;p&gt;Counter 是只增不减的累计值，例如进程启动以来收到的总字节数、处理过的总请求数。直接看 Counter 的绝对值通常没意义，我们关心的是单位时间增加了多少，这正是 &lt;code&gt;rate()&lt;/code&gt; 的工作：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;rate(http_requests_total[5m])
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它计算区间内每秒平均增长量。&lt;code&gt;increase()&lt;/code&gt; 则估算整个区间内的总增量，两者关系可以近似理解为：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;increase(http_requests_total[5m])
# 约等于 rate(http_requests_total[5m]) * 300
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;irate()&lt;/code&gt; 同样计算每秒速率，但只取最后两个样本，反应更灵敏，噪声也更大。看长期趋势、做告警，优先用 &lt;code&gt;rate()&lt;/code&gt;；观察刚刚发生的尖峰，才考虑 &lt;code&gt;irate()&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;Prometheus 会自动处理 Counter 重置。进程重启后 Counter 从 0 重新计数，&lt;code&gt;rate()&lt;/code&gt; 会把这种下降识别为重置并进行修正，你不需要自己写判断。但自动处理不等于没有限制：区间里至少要有两个样本，函数才能算出变化；样本太少时，结果可能为空或不稳定。Prometheus 还会对区间两端做外推，因此 &lt;code&gt;increase()&lt;/code&gt; 的结果可能不是整数，它表示估算增量，不是账本式的精确计数。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;code&gt;rate()&lt;/code&gt; 的时间窗口建议至少是抓取间隔的 4 倍。抓取间隔为 15 秒时，不要用 &lt;code&gt;[15s]&lt;/code&gt; 或 &lt;code&gt;[30s]&lt;/code&gt;，至少用 &lt;code&gt;[1m]&lt;/code&gt;，日常面板和告警更推荐 &lt;code&gt;[5m]&lt;/code&gt;：窗口太短不仅容易没样本，还会把曲线画得剧烈抖动。
:::&lt;/p&gt;
&lt;p&gt;还有一条铁律：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要对 Gauge 使用 rate()。&amp;lt;/span&amp;gt;Gauge 是可上可下的瞬时值，例如内存可用量、温度、队列长度。对它求“每秒增长”没有业务含义；要看平均值、最大值或最小值，应使用 &lt;code&gt;avg_over_time()&lt;/code&gt;、&lt;code&gt;max_over_time()&lt;/code&gt;、&lt;code&gt;min_over_time()&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;聚合：先决定保留哪些标签&lt;/h2&gt;
&lt;p&gt;聚合函数把多条序列合并。常用的是 &lt;code&gt;sum&lt;/code&gt;、&lt;code&gt;avg&lt;/code&gt;、&lt;code&gt;max&lt;/code&gt;、&lt;code&gt;min&lt;/code&gt; 和 &lt;code&gt;count&lt;/code&gt;。真正的难点不在函数，而在聚合后保留哪些标签。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sum by (instance) (
  rate(node_cpu_seconds_total{mode=&quot;idle&quot;}[5m])
)

sum without (cpu, mode) (
  rate(node_cpu_seconds_total[5m])
)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;by&lt;/code&gt; 表示“只保留列出的标签”，&lt;code&gt;without&lt;/code&gt; 表示“删掉列出的标签，其余都保留”。计算整台机器的 CPU 时，通常要去掉 &lt;code&gt;cpu&lt;/code&gt; 和 &lt;code&gt;mode&lt;/code&gt;，但保留 &lt;code&gt;instance&lt;/code&gt;；计算整个集群总量时，才继续去掉 &lt;code&gt;instance&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;写聚合前先问一句：结果里的每条序列应该代表什么？一台机器、一个接口，还是一个服务？答案决定 by 里留什么。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;如果把维度丢错，结果会悄悄变质。例如统计 HTTP 请求时写了 &lt;code&gt;sum by (status)&lt;/code&gt;，你只能看到各状态码总量，看不到每个接口的错误分布；反过来，保留了 &lt;code&gt;path&lt;/code&gt;、&lt;code&gt;user_id&lt;/code&gt; 这类高基数标签，又可能生成成千上万条序列，面板难读，查询也慢。&lt;/p&gt;
&lt;h2&gt;算术与比较运算：比例和阈值都靠它们&lt;/h2&gt;
&lt;p&gt;PromQL 支持 &lt;code&gt;+&lt;/code&gt;、&lt;code&gt;-&lt;/code&gt;、&lt;code&gt;*&lt;/code&gt;、&lt;code&gt;/&lt;/code&gt;、&lt;code&gt;%&lt;/code&gt; 和 &lt;code&gt;^&lt;/code&gt;。最常见的用法是两个相同口径的量做除法，得到使用率或错误比例：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sum(rate(http_requests_total{status=~&quot;5..&quot;}[5m]))
/
sum(rate(http_requests_total[5m]))
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;默认情况下，向量与向量运算会按相同标签集合进行匹配。两边的标签不一致时，Prometheus 可能返回空结果，或者直接报向量匹配错误。做除法前先用聚合把两边整理到相同维度，是最稳妥的办法。&lt;/p&gt;
&lt;p&gt;比较运算符默认起“过滤器”作用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;node_filesystem_avail_bytes / node_filesystem_size_bytes &amp;lt; 0.1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它只返回满足条件、也就是磁盘剩余不足 10% 的序列，原值仍然保留。加上 &lt;code&gt;bool&lt;/code&gt; 修饰符后，它不再过滤，而是把结果改写成 0 或 1：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;(
  node_filesystem_avail_bytes / node_filesystem_size_bytes &amp;lt; bool 0.1
)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;前一种写法适合在 Grafana 里只看异常对象，后一种适合把“是否异常”作为 0/1 曲线或进一步参与计算。把阈值规则真正发送成通知，还要交给&lt;a href=&quot;/posts/monitoring-alertmanager/&quot;&gt;Alertmanager&lt;/a&gt;处理。&lt;/p&gt;
&lt;h2&gt;用 histogram_quantile() 计算 p95 与 p99&lt;/h2&gt;
&lt;p&gt;平均延迟最会骗人：99 个请求只要 10ms，1 个请求慢到 5 秒，平均值看起来仍然不高。观察延迟应该看分位数，而分位数要基于 Histogram 指标的 &lt;code&gt;_bucket&lt;/code&gt; 序列计算。&lt;/p&gt;
&lt;p&gt;Histogram 的 bucket 是累计计数，每个 bucket 带一个 &lt;code&gt;le&lt;/code&gt; 标签，表示“小于等于这个秒数”。计算 p95 的标准姿势是先对 bucket 做 &lt;code&gt;rate()&lt;/code&gt;，再按 &lt;code&gt;le&lt;/code&gt; 聚合，最后交给 &lt;code&gt;histogram_quantile()&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;histogram_quantile(
  0.95,
  sum by (le) (
    rate(http_request_duration_seconds_bucket[5m])
  )
)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;p99 只需把第一个参数换成 &lt;code&gt;0.99&lt;/code&gt;。如果要按服务或接口拆分，就在 &lt;code&gt;by&lt;/code&gt; 中同时保留业务标签和 &lt;code&gt;le&lt;/code&gt;，例如 &lt;code&gt;sum by (service, le)&lt;/code&gt;。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;聚合 bucket 时绝不能丢掉 le 标签&amp;lt;/span&amp;gt;，没有它，Prometheus 就不知道每个 bucket 的上界，分位数自然算不出来。&lt;/p&gt;
&lt;p&gt;还要注意，&lt;code&gt;histogram_quantile()&lt;/code&gt; 是根据 bucket 分布估算分位数，不是把每一次请求耗时排序后取精确值。bucket 划分越合理，估算越可信；如果绝大多数请求都落进同一个宽 bucket，结果只能看趋势，不能当成精密测量。&lt;/p&gt;
&lt;h2&gt;offset 与 @：看过去，钉住某个时刻&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;offset&lt;/code&gt; 可以把查询整体往过去平移，例如用今天的请求量和一周前对比：&lt;code&gt;sum(rate(http_requests_total[5m] offset 7d))&lt;/code&gt;。&lt;code&gt;@&lt;/code&gt; 修饰符则把选择器固定到某个时间点，常用于报表和可复现查询。这两个修饰符在日常面板里用得不多，知道它们解决的是“时间位置”问题即可。&lt;/p&gt;
&lt;h2&gt;可直接抄的 PromQL 模板&lt;/h2&gt;
&lt;p&gt;下面的模板以 Node Exporter、Prometheus HTTP 指标和 kube-state-metrics 的常见命名为例。真正使用时，先把指标名粘到 Prometheus Explore 中确认存在，再替换实例、设备和接口标签。将这些模板做成面板变量后，就能配合&lt;a href=&quot;/posts/monitoring-grafana/&quot;&gt;Grafana&lt;/a&gt;快速切换服务器。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;PromQL 模板&lt;/th&gt;
&lt;th&gt;解读&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;CPU 使用率&lt;/td&gt;
&lt;td&gt;&lt;code&gt;100 * (1 - avg by (instance) (rate(node_cpu_seconds_total{mode=&quot;idle&quot;}[5m])))&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;用 100% 减去空闲比例，按实例保留一条曲线。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;内存使用率&lt;/td&gt;
&lt;td&gt;&lt;code&gt;100 * (1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;用内核估算的可用内存计算，比简单拿空闲内存更符合实际。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;磁盘剩余比例&lt;/td&gt;
&lt;td&gt;&lt;code&gt;100 * node_filesystem_avail_bytes{fstype!~&quot;tmpfs|overlay|squashfs&quot;} / node_filesystem_size_bytes{fstype!~&quot;tmpfs|overlay|squashfs&quot;}&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;排除临时文件系统后看每个挂载点还剩多少空间。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;inode 剩余比例&lt;/td&gt;
&lt;td&gt;&lt;code&gt;100 * node_filesystem_files_free{fstype!~&quot;tmpfs|overlay&quot;} / node_filesystem_files{fstype!~&quot;tmpfs|overlay&quot;}&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;空间没满但 inode 耗尽同样无法创建文件，这条要和容量一起看。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;网络接收吞吐&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sum by (instance) (rate(node_network_receive_bytes_total{device!~&quot;lo|veth.*|docker.*&quot;}[5m]))&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;单位是字节每秒，排除回环和容器虚拟网卡后更接近物理流量。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;网络发送吞吐&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sum by (instance) (rate(node_network_transmit_bytes_total{device!~&quot;lo|veth.*|docker.*&quot;}[5m]))&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;与接收吞吐分开看，才能发现单向跑满或异常外发。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;磁盘读写吞吐&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sum by (instance, device) (rate(node_disk_read_bytes_total{device!~&quot;loop.*|dm-.*&quot;}[5m]))&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;把模板中的 &lt;code&gt;read&lt;/code&gt; 换成 &lt;code&gt;written&lt;/code&gt; 可看写入，保留 device 便于定位是哪块盘忙。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;磁盘 IOPS&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sum by (instance, device) (rate(node_disk_reads_completed_total[5m]) + rate(node_disk_writes_completed_total[5m]))&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;读写次数合并后表示每秒完成的 I/O 操作数。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HTTP 请求量&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sum by (method, status) (rate(http_requests_total[5m]))&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;结果是每秒请求数，按方法和状态码拆分最容易看出流量结构。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HTTP 5xx 比例&lt;/td&gt;
&lt;td&gt;&lt;code&gt;100 * sum(rate(http_requests_total{status=~&quot;5..&quot;}[5m])) / sum(rate(http_requests_total[5m]))&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;分子和分母都先聚合成同一维度，再相除得到整体错误率。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HTTP p95 延迟&lt;/td&gt;
&lt;td&gt;&lt;code&gt;histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket[5m])))&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;表示约 95% 的请求不慢于这个估算值，适合做服务质量面板。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;容器重启次数&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sum by (namespace, pod, container) (increase(kube_pod_container_status_restarts_total[1h]))&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;统计过去 1 小时各容器重启增量，持续增长通常意味着 CrashLoop。&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;有三个使用习惯能省掉很多调试时间。第一，先查原始指标，再逐层往外加函数，出错时逐段删，定位到底是哪一层把结果弄空。第二，吞吐量模板返回的单位多半是 bytes/s，Grafana 里还要设置单位为 bytes/s，别把字节误读成 bit。第三，模板里的 &lt;code&gt;[5m]&lt;/code&gt; 不是圣旨：抓取间隔是 30 秒或 1 分钟的系统，应相应放大窗口。&lt;/p&gt;
&lt;h2&gt;常见错误：三个新手高频坑&lt;/h2&gt;
&lt;h3&gt;1. 对 Gauge 使用 rate()&lt;/h3&gt;
&lt;p&gt;看到指标名里有 &lt;code&gt;total&lt;/code&gt; 不一定就是 Counter，也不能只凭名字判断。应查看指标的 HELP 和 TYPE，或观察一段时间：进程重启后会清零、长期只增的才是 Counter。内存、温度、连接数、队列深度这类当前值是 Gauge，想看趋势直接画原值，想看一段时间均值用 &lt;code&gt;avg_over_time()&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;2. rate() 窗口小于或贴近抓取间隔&lt;/h3&gt;
&lt;p&gt;如果 Prometheus 每 15 秒抓一次，却写 &lt;code&gt;rate(metric[20s])&lt;/code&gt;，窗口内可能只有一个样本，结果就会断断续续。更隐蔽的是 &lt;code&gt;[1m]&lt;/code&gt; 虽然能算，却对短时抖动极其敏感，告警会频繁触发又恢复。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;面板求稳用 5m，告警更要配合持续时间，不要拿几十秒的窗口追每一个毛刺。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h3&gt;3. sum 时把标签维度丢错&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;sum(metric)&lt;/code&gt; 会把所有序列合成一个总数，省事但丢信息；&lt;code&gt;sum by (instance)&lt;/code&gt; 保留机器维度，却可能在聚合前把同一机器的 CPU 核、状态码或设备加在一起。错误通常不是语法报错，而是图“能出，但不对”。写完聚合后，检查结果的标签集合：每条序列是否正好对应你想观察的对象？如果不是，调整 &lt;code&gt;by&lt;/code&gt; 或 &lt;code&gt;without&lt;/code&gt;，不要靠改图例掩盖问题。&lt;/p&gt;
&lt;p&gt;另外两个小坑也经常出现：一是正则忘了完全锚定，&lt;code&gt;device=~&quot;eth&quot;&lt;/code&gt; 查不到 &lt;code&gt;eth0&lt;/code&gt;；二是做除法时两边标签不一致，分子按接口聚合、分母却保留状态码，结果为空。遇到空结果时，分别单独运行分子和分母，看标签差异最有效。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;PromQL 不需要一次学完。日常工作里，先掌握选择器把范围选准，理解 Counter 与 Gauge 的区别，熟练使用 &lt;code&gt;rate()&lt;/code&gt;、聚合和除法，再会用 &lt;code&gt;histogram_quantile()&lt;/code&gt; 看延迟分位数，已经能覆盖绝大多数基础设施与应用监控查询。&lt;/p&gt;
&lt;p&gt;真正要养成的习惯是：每个模板都先在 Explore 里验证指标、标签和单位，再放进面板或告警。模板负责让你快速开始，理解数据类型和标签维度，才是避免“图画出来了，但结论是错的”的关键。&lt;/p&gt;
</content:encoded></item><item><title>监控与可观测性：链路追踪入门——一次请求的时间花在了谁身上</title><link>https://www.anexns.cloudns.org/posts/monitoring-tracing/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-tracing/</guid><description>从 Trace、Span 与上下文传播讲起，用 OpenTelemetry 加 Jaeger 把一次跨服务请求的时间账算清，再对比 Grafana Tempo、采样策略与 Exemplars，并说清什么规模才值得上链路追踪。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;一个请求转了五手，两秒花在哪了&lt;/h2&gt;
&lt;p&gt;周五晚上，订单接口的 p99 延迟突然从 300 毫秒涨到 2 秒。指标面板很诚实：它只告诉你「慢了」，不告诉你慢在哪一环。你去翻日志：网关说自己 30 毫秒就返回了，订单服务说大部分时间在等下游，库存服务说自己只干了 80 毫秒的活，支付和风控各执一词。五个服务的日志摊在五个窗口里，时间戳对不齐，请求 ID 也对不上——两秒钟像是掉进了一个没有灯的房间。&lt;/p&gt;
&lt;p&gt;这正是链路追踪（Distributed Tracing）要解决的问题：给一次请求发一张全程通行证，让它穿过的每个服务都留下进出时间，最后拼成一棵完整的调用树，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;一眼看清这一次请求的时间具体花在了谁身上&amp;lt;/span&amp;gt;。这一篇把核心概念、OpenTelemetry 的位置、Jaeger 与 Grafana Tempo 的选型、采样策略一次讲清，最后聊排障和「什么时候不值得上」。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/jaegertracing/jaeger&lt;/p&gt;
&lt;h2&gt;先分工：指标、日志、链路各管一段&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;支柱&lt;/th&gt;
&lt;th&gt;回答的问题&lt;/th&gt;
&lt;th&gt;粒度&lt;/th&gt;
&lt;th&gt;短板&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;指标&lt;/td&gt;
&lt;td&gt;系统慢不慢、错不错&lt;/td&gt;
&lt;td&gt;全局聚合&lt;/td&gt;
&lt;td&gt;不知道是哪一次请求出的事&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;日志&lt;/td&gt;
&lt;td&gt;某个点上发生了什么&lt;/td&gt;
&lt;td&gt;单机、单服务、单个事件&lt;/td&gt;
&lt;td&gt;跨服务拼不成完整路径&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;链路&lt;/td&gt;
&lt;td&gt;一次请求的时间花在谁身上&lt;/td&gt;
&lt;td&gt;单次请求的全程&lt;/td&gt;
&lt;td&gt;需要埋点，且要靠采样控成本&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一句话：指标发现问题，日志解释局部，链路定位路径。本系列第一篇（&lt;a href=&quot;/posts/monitoring-concepts/&quot;&gt;三大支柱与监控选型&lt;/a&gt;）讲过三者的分工，这一篇专攻链路这一支。&lt;/p&gt;
&lt;h2&gt;核心概念：一棵树和一张通行证&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Trace&lt;/strong&gt;：一次完整请求的全程记录，拥有全局唯一的 Trace ID。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Span&lt;/strong&gt;：一个工作单元——一次 HTTP 调用、一条 SQL、一回 Redis 查询都算一个 Span，有名字、起止时间、状态和属性；Span 之间父子嵌套。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;上下文传播（Context Propagation）&lt;/strong&gt;：把 Trace ID 和当前 Span ID 随请求一起带给下游，下游的 Span 才能挂到同一棵树上。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;拼出来大概长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Trace 4bf92f3577b34da6（一次下单请求，共 1.98s）
├─ Span 网关路由            30ms
├─ Span 订单服务处理        1.90s
│  ├─ Span 库存查询         80ms
│  ├─ Span 风控校验         120ms
│  └─ Span 支付调用         1.68s   ← 时间大头在这里
└─ Span 写操作日志          20ms
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;传播靠的是标准请求头：W3C Trace Context 定义的 &lt;code&gt;traceparent&lt;/code&gt; 头会随 HTTP 请求自动带到下游。用 OpenTelemetry 的自动埋点时，常见 Web 框架和 HTTP 客户端都会帮你注入和提取；但自研客户端、消息队列、异步任务这些地方，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;上下文没有随请求透传&amp;lt;/span&amp;gt;，是后面排障里最高频的断链原因。Span 上还能挂属性（服务名、HTTP 状态码、数据库类型、错误标记），在 UI 里点开任意一个 Span 就能看到当时的现场。&lt;/p&gt;
&lt;h2&gt;OpenTelemetry：埋点只写一次，后端随便换&lt;/h2&gt;
&lt;p&gt;过去每个后端都有自己的埋点 SDK，换后端等于把所有服务重埋一遍。OpenTelemetry（OTel）把这件事标准化了，它在整条链路里的位置是这样：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;部件&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;API / SDK&lt;/td&gt;
&lt;td&gt;应用内的埋点接口：产生 Span、传播上下文、做采样决策&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;OTLP&lt;/td&gt;
&lt;td&gt;统一的数据协议，链路、指标、日志都按它发出&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Collector&lt;/td&gt;
&lt;td&gt;独立进程：接收（Receiver）、加工（Processor，如批处理、尾部采样）、转发（Exporter）到任意后端&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;应用只依赖 OTel SDK 并说 OTLP，后端今天用 Jaeger、明天换 Tempo，只改 Collector 的 Exporter，业务代码一行不动。Collector 不是必需品，应用可以直连后端；但多服务时强烈建议带上，它能把批处理、重试、采样这些脏活从应用里摘出去统一管理。对自建玩家来说，先按 OTel 埋点，是不会错的起手式。&lt;/p&gt;
&lt;p&gt;落地时先用自动埋点：Java、Python、Node.js、Go 等主流语言都有现成的自动埋点包，挂上之后常见 Web 框架、HTTP 客户端、数据库驱动的 Span 就自动有了；业务关键路径再用手动埋点补自定义 Span 和属性。先广覆盖、再补深度，比一上来全手写推进得快得多。&lt;/p&gt;
&lt;h2&gt;后端二选一：Jaeger 还是 Tempo&lt;/h2&gt;
&lt;h3&gt;Jaeger：开箱即用，先跑起来&lt;/h3&gt;
&lt;p&gt;Jaeger 是 CNCF 毕业项目，它的 all-in-one 镜像把收集、存储、查询和 UI 打包进一个容器：查询 UI 在 16686 端口，OTLP 接入走 4317（gRPC）和 4318（HTTP）。小规模直接用内存存储就能跑，先把调用树看清楚再说：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  jaeger:
    image: jaegertracing/all-in-one:1.62
    container_name: jaeger
    restart: unless-stopped
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    ports:
      - &quot;16686:16686&quot;
      - &quot;4317:4317&quot;
      - &quot;4318:4318&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;docker compose up -d&lt;/code&gt; 之后，浏览器打开 &lt;code&gt;http://服务器IP:16686&lt;/code&gt; 就是查询界面。另外注意：16686 的 UI 本身没有登录鉴权，本机或内网用用没问题，要从公网访问就套一层带鉴权的反向代理，别把查询界面直接暴露出去。内存存储的代价要心里有数：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;容器重启后所有链路数据都会消失&amp;lt;/span&amp;gt;，只适合试水和低频排障；要长期留存就得换 Elasticsearch、OpenSearch 或 Cassandra 做后端，运维成本随之而来——这也是很多人后来转向 Tempo 的原因。&lt;/p&gt;
&lt;p&gt;应用侧接入用 OTel SDK 的通用环境变量就能指过来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;OTEL_SERVICE_NAME=order-service
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.2
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;手头还没有埋好的服务时，可以先手写一条 Span 验证 Jaeger 通不通：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -X POST http://127.0.0.1:4318/v1/traces \
  -H &quot;Content-Type: application/json&quot; \
  -d &apos;{&quot;resourceSpans&quot;:[{&quot;resource&quot;:{&quot;attributes&quot;:[{&quot;key&quot;:&quot;service.name&quot;,&quot;value&quot;:{&quot;stringValue&quot;:&quot;manual-test&quot;}}]},&quot;scopeSpans&quot;:[{&quot;spans&quot;:[{&quot;traceId&quot;:&quot;5b8efff798038103d269b633813fc60c&quot;,&quot;spanId&quot;:&quot;eee19b7ec3c1b174&quot;,&quot;name&quot;:&quot;manual-span&quot;,&quot;kind&quot;:2,&quot;startTimeUnixNano&quot;:&quot;1730000000000000000&quot;,&quot;endTimeUnixNano&quot;:&quot;1730000001000000000&quot;}]}]}]}&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;发完去 UI 里按服务名 &lt;code&gt;manual-test&lt;/code&gt; 搜，能看到这条一秒钟的 Span，就说明接收链路是通的。&lt;/p&gt;
&lt;h3&gt;Tempo：和 Grafana 全家桶长在一起&lt;/h3&gt;
&lt;p&gt;Grafana Tempo 的设计哲学完全不同：它只按 Trace ID 存取数据，后端直接用对象存储（S3、GCS 或自建 MinIO），不依赖大型索引数据库，链路存几个月的成本低得多，查询语言是 TraceQL。它的杀手锏是与 Grafana 生态的打通——在 Grafana 里从一条 &lt;a href=&quot;/posts/monitoring-loki/&quot;&gt;Loki 日志&lt;/a&gt;点一下就能跳到对应 Trace，从指标图的尖峰点也能直达，三大支柱在同一个界面里互相跳转。代价是 Tempo 本身没有独立 UI，一切查询都在 Grafana 里完成；除了按 Trace ID 取全程之外，复杂条件检索不如 Jaeger 加 Elasticsearch 灵活。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;Jaeger（all-in-one）&lt;/th&gt;
&lt;th&gt;Grafana Tempo&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;存储&lt;/td&gt;
&lt;td&gt;内存 / Elasticsearch / Cassandra&lt;/td&gt;
&lt;td&gt;对象存储（S3 / MinIO 等）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;UI&lt;/td&gt;
&lt;td&gt;自带，16686 端口&lt;/td&gt;
&lt;td&gt;无，靠 Grafana&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;查询方式&lt;/td&gt;
&lt;td&gt;服务名、操作名、标签过滤&lt;/td&gt;
&lt;td&gt;TraceQL&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;与日志、指标联动&lt;/td&gt;
&lt;td&gt;弱&lt;/td&gt;
&lt;td&gt;强，Loki 与 Exemplars 可互相跳转&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合&lt;/td&gt;
&lt;td&gt;快速上手、小规模、独立部署&lt;/td&gt;
&lt;td&gt;已有 Grafana 栈、要长期留存&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选型建议很直接：还没有 Grafana 栈、只想先看清调用链的，用 Jaeger；已经按本系列把 Prometheus、&lt;a href=&quot;/posts/monitoring-grafana/&quot;&gt;Grafana&lt;/a&gt; 和 Loki 搭起来的，Tempo 是更顺的归宿。&lt;/p&gt;
&lt;h2&gt;采样：别把每一次请求都存下来&lt;/h2&gt;
&lt;p&gt;全量上报在测试环境没问题，进了生产就是灾难：高流量服务每秒几千次请求，每条链路几十个 Span，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;全量采样会先把 Collector 的 CPU、网络和后端磁盘吃满&amp;lt;/span&amp;gt;，监控系统自己先成为事故源。采样就是在「看见」和「成本」之间做交换，两种基本策略：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;策略&lt;/th&gt;
&lt;th&gt;决策时机&lt;/th&gt;
&lt;th&gt;特点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;头部采样（Head Sampling）&lt;/td&gt;
&lt;td&gt;请求刚进来时按比例决定采不采&lt;/td&gt;
&lt;td&gt;简单、开销低；但慢请求和错误请求不一定被留下&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;尾部采样（Tail Sampling）&lt;/td&gt;
&lt;td&gt;整条链路走完后按规则决定&lt;/td&gt;
&lt;td&gt;能只留出错的、慢的，信息量最高；需要在 Collector 里缓存整条链路，内存成本高&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;实务上是组合拳：头部先按 5% 到 20% 比例粗筛，Collector 再开尾部采样保住全部错误和慢请求。注意 OTel 里 &lt;code&gt;parentbased&lt;/code&gt; 的含义：采样决定以链路源头为准并全程传播，同一个 Trace 不会出现一半服务采、一半不采的残缺树。采样率也不是一次定死的：发版、大促这类高风险时段可以临时调高，平稳期再降下来，前提是 Collector 和后端的余量心里有数。&lt;/p&gt;
&lt;p&gt;:::warning
不要图省事把采样率设成 1.0 全量采集。先从 0.05 到 0.1 起步，看 Collector 与后端的负载再往上加；错误链路靠尾部采样保全，而不是靠全量硬扛把磁盘和性能吃掉。
:::&lt;/p&gt;
&lt;h2&gt;Exemplars：从指标尖峰一键跳到现场&lt;/h2&gt;
&lt;p&gt;Exemplars（范例）是把指标和链路缝起来的小机制：应用记录延迟直方图时，把当前请求的 Trace ID 挂在个别数据点上。于是 Grafana 的延迟图上，一个尖峰点不再只是数字——点开它就能直达那一次慢请求的完整链路（前提是后端能按 Trace ID 取链路，且 Grafana 数据源开启了 Exemplars 跳转）。排障动线因此变成：指标发现尖峰，Exemplar 跳到 Trace，看树定位慢的 Span，再跳回 Loki 看那台服务当时的日志。这也是本系列把 Grafana 放在链路之前讲的原因：没有统一的展示层，三大支柱就只是三个孤岛。&lt;/p&gt;
&lt;h2&gt;务实边界：不是所有系统都值得上&lt;/h2&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;链路追踪的价值随调用链深度增长；单体应用装上它，得到的只是一棵只有一层的方法调用树。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;单体应用&lt;/strong&gt;：内部只有函数调用，用日志加指标再配合本地剖析就够了，链路收益有限。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;三五个小服务&lt;/strong&gt;：调用关系一眼看穿，先给日志带上统一的请求 ID 手工串联，能解决八成问题。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;十几个服务起步&lt;/strong&gt;：跨团队、异步消息混杂，一次请求转五手以上，链路追踪从锦上添花变成排障必需品。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;不要为了凑齐「三大支柱」的说法硬上工具链——多一个系统就多一份埋点维护、采样调优和存储成本。先有复杂度，再上工具；先把多台机器纳管明白（见 &lt;a href=&quot;/posts/monitoring-fleet/&quot;&gt;多机监控纳管&lt;/a&gt;），再谈深水区。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;UI 里搜不到任何链路。&lt;/strong&gt; 按顺序查：应用真的产生并上报了吗，先看 Collector 或 Jaeger 的容器日志有没有连接和报错；采样率是不是被设成了 0 或极低；UI 的时间窗和时区有没有覆盖请求发生的时间——十次里有几次是时间窗选错。再确认服务名过滤和 &lt;code&gt;OTEL_SERVICE_NAME&lt;/code&gt; 写的一致。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Span 断链，一棵树碎成好几棵。&lt;/strong&gt; 十有八九是上下文没透传：自研 HTTP 客户端没带 &lt;code&gt;traceparent&lt;/code&gt; 头、跨线程池或协程时上下文丢了、消息队列的消费者没从消息头里恢复上下文。修法是统一走 OTel 自动埋点，或在封装层集中注入提取，别在每个调用点手写。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Collector 连不上、后端没数据。&lt;/strong&gt; 多半是端口和协议对不上：4317 是 gRPC、4318 是 HTTP，SDK 的 Endpoint 写错协议会直接失败，而且日志里往往只有含糊的连接错误。逐段验证：应用到 Collector、Collector 到后端，各打一条手工 Span，断点立刻现形。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;只有根 Span，没有子 Span。&lt;/strong&gt; 根服务埋了、下游没埋；或者下游埋了，但漏装了对应组件的 instrumentation 包——数据库、Redis、HTTP 客户端各有各的包，漏哪个就缺哪一层。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;延迟数字对不上。&lt;/strong&gt; 各机器时钟没同步（NTP）会让 Span 的起止时间漂移，出现子 Span 比父 Span 还长的怪象。先保证全舰队时间同步，再怀疑代码。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Trace 是一次请求的全程，Span 是其中的工作单元，上下文传播是把它们串成一棵树的那根线。&lt;/li&gt;
&lt;li&gt;OpenTelemetry 统一了埋点与协议：应用说 OTLP，Collector 负责接收、加工、转发，后端随时可换。&lt;/li&gt;
&lt;li&gt;后端二选一：Jaeger 开箱即用，适合上手与小规模；Tempo 靠对象存储加 Grafana 联动，适合长期留存。&lt;/li&gt;
&lt;li&gt;采样是必修课：头部比例粗筛加尾部保住错误与慢请求，拒绝全量硬扛。&lt;/li&gt;
&lt;li&gt;Exemplars 让指标尖峰能一键跳到具体 Trace，三大支柱至此真正合流。&lt;/li&gt;
&lt;li&gt;调用链有多深，链路追踪的价值就有多大；复杂度没到之前，先把指标和日志做扎实。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>监控与可观测性：VictoriaMetrics——1 核 1G 的小机器也能长期存数据</title><link>https://www.anexns.cloudns.org/posts/monitoring-victoriametrics/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/monitoring-victoriametrics/</guid><description>单二进制的轻量时序数据库 VictoriaMetrics：资源占用明显低于 Prometheus，兼容 remote_write 与 PromQL 生态，用 Docker Compose 在小内存 VPS 上长期保留监控数据。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先算一笔账：Prometheus 的内存账单有点贵&lt;/h2&gt;
&lt;p&gt;上一篇我们用 &lt;a href=&quot;/posts/monitoring-prometheus/&quot;&gt;Prometheus&lt;/a&gt; 把指标抓了起来，跑是能跑，但账要算清楚。一台 1 核 1G 的小 VPS，系统和杂七杂八的服务先吃掉三四百 MB，Prometheus 本体再稳稳占住两三百 MB 起步，指标一多、保留时间一拉长，内存曲线就跟着往上爬，时不时还要和 OOM Killer 打个照面。监控本来是给业务保命的，结果它自己先成了内存大户，这笔账怎么算都不划算。&lt;/p&gt;
&lt;p&gt;VictoriaMetrics 就是冲着这笔账来的：同样是存监控指标，它的内存和磁盘占用明显比 Prometheus 低一截，单机就能把数据留上一年半载。对小机器来说，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;省下来的内存就是能多跑一个服务的余量&amp;lt;/span&amp;gt;，这才是它真正的卖点。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/VictoriaMetrics/VictoriaMetrics&lt;/p&gt;
&lt;h2&gt;它是什么：一个二进制解决存储&lt;/h2&gt;
&lt;p&gt;VictoriaMetrics 是一个用 Go 写的时序数据库，最大的特点是简单：核心就是一个二进制文件，官方镜像 &lt;code&gt;victoriametrics/victoria-metrics&lt;/code&gt; 拉下来就能跑，默认监听 8428 端口，不需要外挂任何依赖。它有单机版和集群版两种形态，集群版是把读写和存储拆开横向扩展的，几台小 VPS 的规模根本用不上，本文只讲单机版（社区里常叫 vmsingle）。&lt;/p&gt;
&lt;p&gt;它和 Prometheus 生态的关系可以概括为「全面兼容、局部替代」：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;写入兼容&lt;/strong&gt;：Prometheus 可以通过 remote_write 直接把数据写进来；也可以让它自己的 vmagent 按 Prometheus 的 scrape 配置去抓取目标，连 Prometheus 本体都省了。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;查询兼容&lt;/strong&gt;：查询语言叫 MetricsQL，语法兼容 PromQL 并做了一些扩展，原来写的 PromQL 表达式基本可以原样搬过来。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;自带界面&lt;/strong&gt;：内置一个叫 vmui 的简易 Web 界面，能查指标、看表达式结果，临时排障够用，正式看板还是交给 Grafana。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;同生态组件&lt;/strong&gt;：vmagent 负责采集抓取，vmalert 负责执行告警规则并把告警发给 Alertmanager，整条链和 Prometheus 那套一一对应。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;Docker Compose 部署&lt;/h2&gt;
&lt;p&gt;先只起存储本体，两个关键参数要记牢：&lt;code&gt;-storageDataPath&lt;/code&gt; 是数据落盘目录，&lt;code&gt;-retentionPeriod&lt;/code&gt; 是数据保留时长。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  victoriametrics:
    image: victoriametrics/victoria-metrics:latest
    container_name: victoriametrics
    command:
      - &quot;-storageDataPath=/storage&quot;
      - &quot;-retentionPeriod=12&quot;
      - &quot;-httpListenAddr=:8428&quot;
    ports:
      - &quot;127.0.0.1:8428:8428&quot;
    volumes:
      - ./vmdata:/storage
    restart: unless-stopped
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动后浏览器打开 &lt;code&gt;http://服务器IP:8428/vmui&lt;/code&gt; 就是自带界面。这里的 &lt;code&gt;-retentionPeriod=12&lt;/code&gt; 按官方口径是保留 12 个月，写 &lt;code&gt;365d&lt;/code&gt; 效果一样，这个参数的单位坑后面排障部分会专门讲。&lt;/p&gt;
&lt;p&gt;如果采集端也想一起换掉，再把 vmagent 加进同一个 Compose 文件。它读取的 scrape 配置格式与 Prometheus 的 &lt;code&gt;prometheus.yml&lt;/code&gt; 兼容，原来给 Prometheus 写的抓取任务可以直接复用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;  vmagent:
    image: victoriametrics/vmagent:latest
    container_name: vmagent
    command:
      - &quot;-promscrape.config=/etc/vmagent/scrape.yml&quot;
      - &quot;-remoteWrite.url=http://victoriametrics:8428/api/v1/write&quot;
    volumes:
      - ./scrape.yml:/etc/vmagent/scrape.yml:ro
    restart: unless-stopped
    depends_on:
      - victoriametrics
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;scrape.yml&lt;/code&gt; 的写法和 Prometheus 完全一致，&lt;code&gt;job_name&lt;/code&gt;、&lt;code&gt;static_configs&lt;/code&gt;、&lt;code&gt;targets&lt;/code&gt; 照抄即可。vmagent 抓到数据后通过 remote_write 推给 VictoriaMetrics，自己只保留很小的缓冲队列，内存占用比 Prometheus 本体低得多，这也是它能替代 Prometheus 做采集的原因。&lt;/p&gt;
&lt;p&gt;启动后先做两个验证：执行 &lt;code&gt;curl http://127.0.0.1:8428/health&lt;/code&gt;，返回 &lt;code&gt;OK&lt;/code&gt; 说明存储本体活着；过几分钟去 vmui 里查任意一个 exporter 的指标，能出曲线就说明写入链路通了。vmagent 那边看它 8429 端口的 &lt;code&gt;/targets&lt;/code&gt; 页面，每个抓取目标的健康状态和最后抓取时间都列在那里，比翻日志直观得多。&lt;/p&gt;
&lt;h2&gt;两条写入路线，怎么选&lt;/h2&gt;
&lt;p&gt;把数据送进 VictoriaMetrics 有两条路，按你现在的家底选：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;路线一：vmagent 直接抓取。&lt;/strong&gt; 适合新装或者愿意换掉 Prometheus 的场景。node_exporter、&lt;a href=&quot;/posts/monitoring-cadvisor/&quot;&gt;cAdvisor&lt;/a&gt; 这些 exporter 照常跑，vmagent 按 scrape 配置挨个抓，写进 VictoriaMetrics。链路最短，组件最少，资源占用也最低。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;路线二：Prometheus remote_write 转发。&lt;/strong&gt; 适合已经有一套 Prometheus 在跑、暂时不想动采集层的场景。在 Prometheus 的配置里加一段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;remote_write:
  - url: http://127.0.0.1:8428/api/v1/write
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Prometheus 照常抓取，同时把数据实时转发一份到 VictoriaMetrics。过渡期可以两边各存一份，等 Grafana 的数据源切过去、确认查询无误后，再把 Prometheus 停掉、采集层换成 vmagent，存储就彻底迁完了。两条路线不冲突，迁移过程可以平滑衔接，不需要停机切换。&lt;/p&gt;
&lt;h2&gt;查询与看板：Grafana 几乎零成本&lt;/h2&gt;
&lt;p&gt;MetricsQL 兼容 PromQL，所以 &lt;a href=&quot;/posts/monitoring-grafana/&quot;&gt;Grafana&lt;/a&gt; 那边不需要学新东西：添加数据源时类型仍然选 Prometheus，URL 填 &lt;code&gt;http://服务器IP:8428&lt;/code&gt; 就行，Grafana 会自己在后面拼 &lt;code&gt;/api/v1&lt;/code&gt; 的查询路径。之前给 Prometheus 做的看板、变量和告警表达式，换个数据源就能继续用。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;查询侧的迁移成本基本为零，换的只是底层存储&amp;lt;/span&amp;gt;，这是它比很多同类方案省事的地方。&lt;/p&gt;
&lt;p&gt;临时查数据则用 vmui 更快：打开 &lt;code&gt;/vmui&lt;/code&gt;，输入表达式就能看曲线，还能浏览当前库里都有哪些指标名，比对着文档猜指标名方便得多。&lt;/p&gt;
&lt;p&gt;有个细节先提醒：MetricsQL 在 PromQL 之外补了些扩展，比如多了处理缺失值的 &lt;code&gt;default&lt;/code&gt; 运算符、部分函数的默认行为也更宽容。迁移后如果某个老表达式跑出的结果和原来对不上，先去对照 MetricsQL 的文档，多半是这类细节差异，而不是数据本身出了问题。&lt;/p&gt;
&lt;h2&gt;告警链：vmalert 接 Alertmanager&lt;/h2&gt;
&lt;p&gt;VictoriaMetrics 本体只管存储和查询，告警规则由同生态的 vmalert 执行：它定时拿规则文件里的表达式去查 VictoriaMetrics，触发后把告警发给 Alertmanager，后续的分组、抑制、通知渠道都和 Prometheus 那套完全一样，规则文件的语法也兼容 Prometheus 的告警规则格式。如果你暂时还留着 Prometheus + Alertmanager 的组合，也可以先只换存储，告警链原样不动，等稳定后再考虑把规则执行迁到 vmalert。&lt;/p&gt;
&lt;p&gt;vmalert 的启动方式同样是一个容器加几个参数：&lt;code&gt;-datasource.url&lt;/code&gt; 指向 VictoriaMetrics 的 8428 端口，&lt;code&gt;-rule&lt;/code&gt; 指向规则文件，&lt;code&gt;-notifier.url&lt;/code&gt; 指向 Alertmanager 的 9093 端口。规则文件就是 Prometheus 的 YAML 告警规则格式，原来给 Prometheus 写的可以直接搬过来，上手成本很低。&lt;/p&gt;
&lt;h2&gt;与 Prometheus 对比&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;Prometheus&lt;/th&gt;
&lt;th&gt;VictoriaMetrics（单机版）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;资源占用&lt;/td&gt;
&lt;td&gt;内存随指标量上涨明显，小机器吃紧&lt;/td&gt;
&lt;td&gt;同等数据量下内存与磁盘占用明显更低&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;查询语言&lt;/td&gt;
&lt;td&gt;PromQL&lt;/td&gt;
&lt;td&gt;MetricsQL，兼容 PromQL 并有扩展&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;生态&lt;/td&gt;
&lt;td&gt;exporter、看板、文档最齐全，事实标准&lt;/td&gt;
&lt;td&gt;兼容 Prometheus 的写入与查询生态，自身组件较新&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;高可用&lt;/td&gt;
&lt;td&gt;本地存储单机为主，高可用靠双写等外部方案&lt;/td&gt;
&lt;td&gt;单机版无高可用，集群版可扩展但部署复杂&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;告警链&lt;/td&gt;
&lt;td&gt;本体执行规则 + Alertmanager&lt;/td&gt;
&lt;td&gt;vmalert 执行规则 + Alertmanager&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;结论很直白：Prometheus 胜在生态和资料，VictoriaMetrics 胜在资源账单。如果你的瓶颈是「机器太小、数据留不久」，换存储比换更大的机器划算；如果你的场景复杂、依赖大量 Prometheus 周边工具，那继续用 Prometheus 也没问题。舰队里多台机器汇总监控的场景，可以配合&lt;a href=&quot;/posts/monitoring-fleet/&quot;&gt;舰队总览&lt;/a&gt;那篇一起看。&lt;/p&gt;
&lt;h2&gt;从 Prometheus 迁移的推荐路径&lt;/h2&gt;
&lt;p&gt;不用一步到位，按三步走最稳：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;先部署 VictoriaMetrics，用 remote_write 让 Prometheus 转发一份数据过来，双写观察几天，确认磁盘占用和查询结果都正常。&lt;/li&gt;
&lt;li&gt;把 Grafana 的数据源切到 VictoriaMetrics，看板和告警表达式逐个验一遍，重点看用了 PromQL 函数的面板在 MetricsQL 下结果是否一致。&lt;/li&gt;
&lt;li&gt;采集层从 Prometheus 换成 vmagent，scrape 配置直接复用；Prometheus 下线，迁移完成。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;历史数据如果想一并搬走，可以用官方的 vmctl 工具从 Prometheus 的数据目录导入，也可以走导入接口批量灌入，排障部分会提到入口。只是补历史曲线的话，其实双写跑上一两周，新库的数据也就够用了，历史包袱不搬也行。&lt;/p&gt;
&lt;p&gt;:::warning
两个安全与可靠性的提醒必须说在前面。第一，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;8428 端口本身没有任何鉴权&amp;lt;/span&amp;gt;，和 Prometheus 一样，谁能访问这个端口谁就能查全部指标、甚至调用管理接口删数据，所以务必像上面的 Compose 示例那样只绑 &lt;code&gt;127.0.0.1&lt;/code&gt;，对外访问走反向代理加认证或者干脆只在内网开放，绝不能把 8428 裸奔在公网。第二，单机版没有高可用，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;数据就一份躺在本地磁盘上，盘坏了监控历史就全没了&amp;lt;/span&amp;gt;，重要环境记得把 &lt;code&gt;vmdata&lt;/code&gt; 目录纳入定期备份，或者至少接受「监控数据丢了不致命」这个前提再上单机。
:::&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Grafana 连不上或查不到数据。&lt;/strong&gt; 先确认数据源类型选的是 Prometheus、URL 只写到端口为止。很多人习惯性地把地址写成 &lt;code&gt;http://服务器IP:8428/api/v1&lt;/code&gt;，结果 Grafana 又在后面拼了一段路径，请求落到不存在的地址上，表现就是数据源测试报错或者面板全空。vmsingle 的 Prometheus 兼容接口就在根路径下，URL 写 &lt;code&gt;http://服务器IP:8428&lt;/code&gt; 即可；容器间互访时把 IP 换成服务名 &lt;code&gt;http://victoriametrics:8428&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;retention 参数单位不对，数据被提前删了。&lt;/strong&gt; 这是最常见的坑：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;code&gt;-retentionPeriod&lt;/code&gt; 的纯数字按「月」计算，不是天&amp;lt;/span&amp;gt;。写 &lt;code&gt;12&lt;/code&gt; 是留 12 个月，写 &lt;code&gt;1&lt;/code&gt; 是只留 1 个月；想按天控制就老老实实写带单位的形式，比如 &lt;code&gt;90d&lt;/code&gt;、&lt;code&gt;365d&lt;/code&gt;。从 Prometheus 迁过来的人最容易在这里栽跟头，Prometheus 的 &lt;code&gt;--storage.tsdb.retention.time=15d&lt;/code&gt; 写惯了，到这边顺手填个数字，数据一个月就没了。改完参数记得重启容器才生效。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;vmagent 抓不到目标。&lt;/strong&gt; 先看 vmagent 的日志和它自带的 &lt;code&gt;/targets&lt;/code&gt; 页面（默认 8429 端口），抓取失败的目标和报错原因都列在那里，九成是目标地址不通或者 scrape 配置缩进写错。配置格式兼容不等于可以乱改，&lt;code&gt;scrape_configs&lt;/code&gt; 的层级要和 Prometheus 时一模一样。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;导入历史数据。&lt;/strong&gt; 官方工具 vmctl 支持从 Prometheus、InfluxDB 等来源迁移数据，命令是 &lt;code&gt;vmctl prometheus --vm-addr=http://服务器IP:8428&lt;/code&gt; 并指向 Prometheus 的数据目录；少量补数据也可以直接往 &lt;code&gt;/api/v1/import/prometheus&lt;/code&gt; 接口 POST 文本格式的指标。导入时注意时间戳单位是毫秒，别把秒级时间戳灌进去，否则数据会落到 1970 年附近，怎么查都查不到。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;磁盘涨得比预期快。&lt;/strong&gt; 先去 vmui 里看各指标的基数（cardinality），监控数据占空间的大头从来不是时间跨度，而是标签组合爆炸：某个指标带了高基数标签（比如把请求 ID、完整 URL 当标签），数据量会指数级膨胀。解决办法是在 vmagent 的 scrape 配置里用 &lt;code&gt;metric_relabel_configs&lt;/code&gt; 把这类标签丢掉，而不是一味调大磁盘。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;VictoriaMetrics 的定位很清楚：它不试图取代 Prometheus 的整个生态，而是把其中最吃资源的那一环——存储——做得更便宜。单二进制部署、兼容 remote_write 写入、兼容 PromQL 查询、vmagent 和 vmalert 补齐采集与告警，让它在小机器上成了一个非常务实的选择。1 核 1G 的 VPS 想把监控数据留上一年，Prometheus 做不到的事，它能做。选型结论就是一句话：机器小、想留长、生态依赖不深，直接上 VictoriaMetrics；反之，留在 Prometheus 也完全没问题。&lt;/p&gt;
</content:encoded></item><item><title>Aerial 超详细拆箱：给国产电视换一块没有广告的 tvOS 风桌面（附全部安装命令）</title><link>https://www.anexns.cloudns.org/posts/selfhost-aerial-tv/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-aerial-tv/</guid><description>Aerial（aerial-tv）是参照 Apple TV 设计的开源 Android TV 桌面：无广告、无推荐流，开机自动接管，支持小米、TCL、创维、索尼等国产电视与盒子、投影仪。本文把功能、接管原理、三个版本的区别、四种部署方式的全部命令、源码构建与机型适配一次讲透。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;打开国产电视，先迎接你的是什么？满屏的剧集推荐、会员入口、限免角标，自己的 App 反而要翻三层才能找到。Aerial 想解决的就是这件事：它是一个参照 Apple TV（tvOS）设计的开源 Android TV 桌面，装上之后开机自动接管——没有广告，没有推荐流，只有你的 App、壁纸和航拍屏保。它不用 root，不动系统应用，随时可以还原，却能把小米、TCL、创维、索尼这些「只认自家桌面」的电视一一拿下。本文按超详细规格来拆：功能、原理、版本、部署命令、源码构建、机型名单，一次讲全。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/pengchujin/aerial-tv&lt;/p&gt;
&lt;h2&gt;先看清这是什么&lt;/h2&gt;
&lt;p&gt;Aerial 的包名是 &lt;code&gt;app.orchard.tv&lt;/code&gt;，官网在 aerial.qust.me，MIT 开源。几个关键数据（2026 年 11 月查于仓库主页）：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;项目&lt;/th&gt;
&lt;th&gt;数据&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Star&lt;/td&gt;
&lt;td&gt;约 12.1k&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Fork&lt;/td&gt;
&lt;td&gt;约 1.0k&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;版本发布&lt;/td&gt;
&lt;td&gt;92 个 Release&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;提交数&lt;/td&gt;
&lt;td&gt;948&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;许可证&lt;/td&gt;
&lt;td&gt;MIT&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;系统要求&lt;/td&gt;
&lt;td&gt;Android 5.0+（另有 4.0–4.4 的 Lite 版）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;支持设备&lt;/td&gt;
&lt;td&gt;小米、TCL、雷鸟、创维、海信、索尼等电视，以及盒子、投影仪&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;它和普通「换个启动器」的区别在于目标定得非常明确：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;不是多一个桌面选项，而是让电视从开机那一刻起就只剩这块干净桌面&amp;lt;/span&amp;gt;。原厂桌面、会员体系、小爱同学、电视账号、有线电视全都保留，只是退到幕后——想用原桌面，从 App 列表里照样能进。&lt;/p&gt;
&lt;p&gt;换与不换，差别一目了然：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;电视自带桌面&lt;/th&gt;
&lt;th&gt;Aerial&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;首屏内容&lt;/td&gt;
&lt;td&gt;剧集推荐、会员广告、限免角标&lt;/td&gt;
&lt;td&gt;你的 App、壁纸、时钟&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;找 App&lt;/td&gt;
&lt;td&gt;多层菜单里翻&lt;/td&gt;
&lt;td&gt;首页玻璃底板 + 全部 App 网格&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;屏保&lt;/td&gt;
&lt;td&gt;厂商广告或静态图&lt;/td&gt;
&lt;td&gt;Apple TV 同款 114 段航拍影片&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;整理方式&lt;/td&gt;
&lt;td&gt;遥控器逐个挪&lt;/td&gt;
&lt;td&gt;遥控器长按，或手机扫码拖动&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;开机广告&lt;/td&gt;
&lt;td&gt;固件播的，去不掉&lt;/td&gt;
&lt;td&gt;同样去不掉（这是实话，先说清）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;功能全拆解&lt;/h2&gt;
&lt;h3&gt;首页与玻璃底板&lt;/h3&gt;
&lt;p&gt;第一排常用 App 放在屏幕下方的玻璃底板上，往下滚动是全部 App 的网格。值得一提的是，它连小米「应用中心」「米家」这类被厂商藏起来的系统 App 都能列出来——很多第三方桌面只显示普通应用，系统应用是缺的。&lt;/p&gt;
&lt;h3&gt;整理：文件夹、隐藏与开机直达&lt;/h3&gt;
&lt;p&gt;长按 OK 键（或按菜单键）进入整理：移动位置、放进文件夹、隐藏、卸载都可以。最实用的一项是「开机时打开」：可以指定开机、待机醒来后直接进某个 App 或某个信号源——比如开机直达机顶盒的 HDMI，或者直达 &lt;a href=&quot;/posts/selfhost-jellyfin/&quot;&gt;Jellyfin&lt;/a&gt; 客户端，电视就变回一台纯粹的播放终端。&lt;/p&gt;
&lt;p&gt;固定到主屏幕的 HDMI 信号源可以选设备类型（Apple TV、PlayStation、Switch、Xbox、电脑等），磁贴会换成对应图标，还能在手机上给它起名字。&lt;/p&gt;
&lt;h3&gt;用手机整理桌面&lt;/h3&gt;
&lt;p&gt;在电视上扫二维码，手机里打开的就是和电视一模一样的图标网格：按住拖动排序，点一下改名、换图标、放进文件夹或隐藏，也能把 HDMI 等信号源加到主屏幕。用遥控器逐格挪图标有多痛苦，用过的人都懂，这个功能是真正的效率分水岭。&lt;/p&gt;
&lt;h3&gt;图标库&lt;/h3&gt;
&lt;p&gt;常用 App 直接配好了 16:9 磁贴图，一个 App 可以有好几张可选，在手机上点开就能挑，每张都标注来源。图的来源有四路：社区画师 le5inioo 的一整套作品、App 自己的 tvOS 版图标、Aerial 为系统 App 自绘的图标，以及当贝桌面的图。&lt;/p&gt;
&lt;h3&gt;控制中心&lt;/h3&gt;
&lt;p&gt;在第一排按上键、到右上角打开控制中心：信号源、网络、设置、音量、亮度、个性化都在这里。1.32 版起，新版本提示也出现在这里，点进去就能下载安装升级（后文详述）。&lt;/p&gt;
&lt;h3&gt;屏保：114 段航拍影片&lt;/h3&gt;
&lt;p&gt;屏保是 Apple TV 标志性的航拍影片，共 114 段，电视支持时可以播 4K 或 4K 杜比视界版本，影片由 Apple 的服务器直接播放。也可以换成照片、时钟，或者从手机添加的本地视频。&lt;/p&gt;
&lt;h3&gt;壁纸&lt;/h3&gt;
&lt;p&gt;壁纸来源有四种：必应每日精选、14 张内置壁纸、用手机扫码传的照片和视频，以及航拍模式——停在主屏幕 10 秒后，航拍会在磁贴后面自动播放，按任意键就停在当前画面当壁纸。&lt;/p&gt;
&lt;h3&gt;个性化&lt;/h3&gt;
&lt;p&gt;每排 4、5 或 6 个 App、单排或双排布局、时钟大小和位置、App 名称显示、焦点样式、按键声音，都能改。老电视或内存小的电视从 1.48 版起会自动切换到「流畅」效果（面板纯色、去掉高光），也可以在个性化里手动选——这一点和 &lt;a href=&quot;/posts/selfhost-home-assistant/&quot;&gt;Home Assistant&lt;/a&gt; 那种「先跑起来再谈美观」的家庭设备思路一致：先保证不卡。&lt;/p&gt;
&lt;h2&gt;它怎么接管桌面：原理&lt;/h2&gt;
&lt;p&gt;这是 Aerial 最硬核的部分。国产电视大多只认自家桌面，待机时还会清理第三方 App，光靠 Android 标准的「设为默认桌面」根本站不住。Aerial 的解法是三层：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;层&lt;/th&gt;
&lt;th&gt;机制&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;桌面守护&lt;/td&gt;
&lt;td&gt;无障碍服务&lt;/td&gt;
&lt;td&gt;只看哪个窗口在前台，原桌面一出现就切回 Aerial&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;复活&lt;/td&gt;
&lt;td&gt;通知使用权监听&lt;/td&gt;
&lt;td&gt;被系统清理后，靠通知监听让系统把 Aerial 重新拉起来&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;兜底&lt;/td&gt;
&lt;td&gt;用量统计&lt;/td&gt;
&lt;td&gt;老小米（Android 6）的桌面不报告窗口变化，改看系统用量统计判断前台&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;两个隐私边界写得很清楚：无障碍服务&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;只判断哪个窗口在前台，不读屏幕内容&amp;lt;/span&amp;gt;；通知监听&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不读通知内容&amp;lt;/span&amp;gt;，只借它做复活通道。有些酷开、创维固件不按标准方式启动桌面，守护也专门认了它们自家的桌面组件。原生 Android TV 没有这些对抗，直接设成默认桌面即可，不需要守护。&lt;/p&gt;
&lt;h2&gt;三个版本先分清&lt;/h2&gt;
&lt;p&gt;下载页有三个 APK，装错版本是新手最常见的坑：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;版本&lt;/th&gt;
&lt;th&gt;包名&lt;/th&gt;
&lt;th&gt;用在哪&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;aerial-standard.apk&lt;/td&gt;
&lt;td&gt;app.orchard.tv&lt;/td&gt;
&lt;td&gt;Android 5.0+，先装这个&lt;/td&gt;
&lt;td&gt;完整版，绝大多数电视用它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;aerial-guard.apk&lt;/td&gt;
&lt;td&gt;app.orchard.tv（守护变体）&lt;/td&gt;
&lt;td&gt;standard 装不上、提示不允许安装桌面类 App 时&lt;/td&gt;
&lt;td&gt;靠守护机制接管的版本&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;aerial-lite.apk&lt;/td&gt;
&lt;td&gt;app.orchard.tv.lite&lt;/td&gt;
&lt;td&gt;Android 4.0–4.4 老电视、老盒子&lt;/td&gt;
&lt;td&gt;测试版（1.0），功能有删减，见后文&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;部署方式总览&lt;/h2&gt;
&lt;p&gt;Aerial 的「部署」不是往服务器上装，而是往电视上装。官方给了四条路径，难度从低到高：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方式&lt;/th&gt;
&lt;th&gt;需要什么&lt;/th&gt;
&lt;th&gt;适合谁&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Agent 代装&lt;/td&gt;
&lt;td&gt;一台能跑命令的电脑 + 任意编程 Agent&lt;/td&gt;
&lt;td&gt;完全不想碰命令的人&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;一行命令&lt;/td&gt;
&lt;td&gt;macOS / Linux 电脑&lt;/td&gt;
&lt;td&gt;有终端经验的人&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;手动 ADB&lt;/td&gt;
&lt;td&gt;任意电脑 + platform-tools&lt;/td&gt;
&lt;td&gt;想搞清每一步的人&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;U 盘安装&lt;/td&gt;
&lt;td&gt;U 盘&lt;/td&gt;
&lt;td&gt;没有电脑，或先试个水&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;四条路径的共同前置条件只有两个：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;电脑和电视连同一个网络&amp;lt;/span&amp;gt;，以及在电视上打开 ADB 调试。下面先讲前置，再逐条拆四种部署。&lt;/p&gt;
&lt;h2&gt;前置一：打开电视的 ADB 调试&lt;/h2&gt;
&lt;p&gt;各品牌开 ADB 的入口完全不同，这是整个安装里最需要查表的一步：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;电视&lt;/th&gt;
&lt;th&gt;怎么打开&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;小米 / Redmi&lt;/td&gt;
&lt;td&gt;设置 → 关于 → 连续按「产品型号/产品类型」进开发者模式，再到 设置 → 账号与安全，打开「ADB 调试」和「安装未知来源的应用」&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TCL / 雷鸟&lt;/td&gt;
&lt;td&gt;设置 → 关于 → 本机信息，快速按遥控器「上下左右」，在底部「更多」里打开 ADB&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;海尔 / 模卡&lt;/td&gt;
&lt;td&gt;按机身信号源键，再用遥控器按「左左上右」，在工厂菜单里打开「ADB 调试开关」，别动其他选项&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;海信 / Vidda&lt;/td&gt;
&lt;td&gt;设置 → 声音关杜比全景声，在专业音响设置 → 声音平衡里快速交替按「确认」「菜单」，出现 M 后按「菜单」进工厂菜单，把 To Fac 从 U 改成 M 后重启；再连按「菜单」打开原生设置，连按版本号后在开发者选项里打开「USB 调试」和「无线调试」&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;OPPO（含 S1）&lt;/td&gt;
&lt;td&gt;设置 → 系统 → 关于本机 → 设备型号，按「上上右右」再确认；再到开发者选项打开「USB 调试」；IP 在 设置 → 网络 → 已连接的网络 最下面&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;其他 Android TV&lt;/td&gt;
&lt;td&gt;设置 → 设备偏好设置 → 关于 → 连按「内部版本号」7 次，再在开发者选项里打开「USB 调试」&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;电视 IP 在「设置 → 网络 → 已连接的网络」里查。第一次连接时，有 USB 调试开关的电视会弹窗问是否允许调试，选「始终允许」。更细的分品牌说明（包括打不开 ADB 的机型）在仓库的 docs/devices/adb-by-brand.md 里。&lt;/p&gt;
&lt;p&gt;:::warning
工厂菜单是高危区：海信的 To Fac &amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;只改一次&amp;lt;/span&amp;gt;——反复改可能让 USB 失灵、只能重置电视。其他品牌的工厂菜单也一样，只动 ADB 开关那一项，改完立刻退出，不要好奇乱翻其他选项。
:::&lt;/p&gt;
&lt;h2&gt;前置二：只有无线调试的电视先配对&lt;/h2&gt;
&lt;p&gt;部分 Android 11+ 电视（例如索尼 BRAVIA 的 Android 14）只有「无线调试」、没有旧式 ADB 开关，不提供明文端口，不能直接 &lt;code&gt;adb connect &amp;lt;IP&amp;gt;:5555&lt;/code&gt;，第一次连接必须先配对。在电视上打开 设置 → 系统 → 开发者选项 → 无线调试 → 使用配对码配对设备，然后在电脑上：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;adb pair 192.168.1.20:37115
# 提示 Enter pairing code 时，输入电视屏幕上的 6 位配对码

adb connect 192.168.1.20:39201
# 这里用的是无线调试主页面上显示的另一组 IP:端口，与配对端口不同
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;连上之后，建议再运行一次 &lt;code&gt;adb tcpip 5555&lt;/code&gt;，把电视切回经典的 5555 端口模式，以后所有命令都能直接用 &lt;code&gt;&amp;lt;电视IP&amp;gt;:5555&lt;/code&gt;，配过对的电脑不用再配对。注意：部分 TCL 固件（Q10M、Q10L、鹤 6 Ultra 等）没有配对码入口，只能先用数据线连电脑授权一次，再 &lt;code&gt;adb tcpip 5555&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;部署方式一：交给 Agent 装（官方推荐）&lt;/h2&gt;
&lt;p&gt;这是官方放在第一位的安装方式：把一段现成的指令发给能在电脑上运行命令的 Agent（Claude Code、Codex、Trae、WorkBuddy、豆包电脑版、千问电脑版等），由它读官方安装说明、在你的电脑上亲自执行命令，装完按验收标准贴出原始输出：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;请帮我把开源电视桌面 Aerial 装到我的电视上，并设为开机进入的桌面。

电视 IP：&amp;lt;电视IP&amp;gt;

保持 ADB 常开：要

安装说明在这里：https://aerial.qust.me/agent.md
（打不开时用 https://raw.githubusercontent.com/pengchujin/aerial-tv/main/site/agent.md ）

请先完整读完安装说明再动手，然后在我的电脑上亲自运行命令，不要只把步骤告诉我。需要我在电视上操作时提醒我。

最后按说明里的「验收」，把这几条命令的原始输出原样贴给我：
- adb shell &quot;cmd package resolve-activity --brief -a android.intent.action.MAIN -c android.intent.category.HOME&quot;
- adb shell settings get secure enabled_accessibility_services
- 按主页键后的 adb shell &quot;dumpsys window | grep mCurrentFocus&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三个验收点分别确认：系统默认桌面解析到了谁、无障碍守护在不在启用列表里、按主页键后前台窗口到底是谁。判断装没装好，只看最后一条的输出里有没有 &lt;code&gt;app.orchard.tv&lt;/code&gt;。手机上的聊天 App 只会把步骤「告诉」你、不会执行，必须用电脑版或工作版 Agent。没有电脑时，有用户用手机上的甲壳虫 ADB 助手、超级小爱装成功过，但仓库没有逐一实测。&lt;/p&gt;
&lt;h2&gt;部署方式二：一行命令（macOS / Linux）&lt;/h2&gt;
&lt;p&gt;有终端经验的人，这条最快：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -fsSL https://aerial.qust.me/install.sh | KEEP_ADB=1 TV=192.168.1.20 bash
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个环境变量的含义：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;变量&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;TV&lt;/td&gt;
&lt;td&gt;电视的 IP，换成你自己的&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;KEEP_ADB=1&lt;/td&gt;
&lt;td&gt;保持 ADB 常开。小米待机后会关掉 ADB，加上它，Aerial 会负责重新打开，方便以后升级维护&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;脚本会自动判断电视的 Android 版本：发现是 4.x 会自动装 Lite 版。无线调试的电视先把配对信息 export 出来再跑同一条命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;export ADB_PAIR=&amp;lt;配对屏 IP:端口&amp;gt; ADB_CODE=&amp;lt;6 位配对码&amp;gt; ADB_CONNECT=&amp;lt;无线调试主页 IP:端口&amp;gt;
curl -fsSL https://aerial.qust.me/install.sh | KEEP_ADB=1 TV=192.168.1.20 bash
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;部署方式三：手动 ADB（把每一步看清）&lt;/h2&gt;
&lt;p&gt;手动方式适合想搞清原理的人。先从官网下载 aerial-standard.apk，然后逐条执行（Windows 用户建议走 Agent 方式，或查阅官网安装说明里的 Windows 步骤）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;adb connect 192.168.1.20:5555

adb install -r aerial-standard.apk

adb shell pm grant app.orchard.tv android.permission.WRITE_SECURE_SETTINGS

adb shell cmd notification allow_listener app.orchard.tv/app.orchard.tv.guard.RevivalListener

adb shell appops set app.orchard.tv SYSTEM_ALERT_WINDOW allow

adb shell am start -n app.orchard.tv/.MainActivity

adb shell cmd package compile -m speed -f app.orchard.tv
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;每条命令在干什么：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;adb connect&lt;/td&gt;
&lt;td&gt;连上电视的 ADB&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;adb install -r&lt;/td&gt;
&lt;td&gt;安装（-r 表示覆盖安装，升级时设置不丢）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;pm grant … WRITE_SECURE_SETTINGS&lt;/td&gt;
&lt;td&gt;授予写安全设置的权限，守护与亮度等功能要用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;cmd notification allow_listener&lt;/td&gt;
&lt;td&gt;把 Aerial 的 RevivalListener 加入通知监听白名单，启用「复活」通道&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;appops set … SYSTEM_ALERT_WINDOW allow&lt;/td&gt;
&lt;td&gt;允许悬浮窗，守护切回前台要用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;am start … MainActivity&lt;/td&gt;
&lt;td&gt;立刻启动 Aerial 主界面&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;cmd package compile -m speed&lt;/td&gt;
&lt;td&gt;提前做 AOT 编译，让 Aerial 在电视上更流畅；等界面显示出来 5 秒后再运行，要几十秒；不运行也可以，它会在下次从控制中心升级时补上&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;装完按主页键：原生 Android TV 一般会弹「使用哪个应用」，选 Aerial 再选「始终」就设好了。国产电视大多不弹、直接回原桌面，这时从「我的应用」打开 Aerial，它会弹出「设为主屏幕」引导你去打开桌面守护（无障碍）和通知使用权；电视设置里找不到这些入口时，Aerial 只能当普通 App 用，要接管主页键还得用上面的命令或 Agent 再设置一次（覆盖安装，不丢设置）。&lt;/p&gt;
&lt;p&gt;电视提示不允许安装桌面类 App 时，改用守护版：一行命令最后加 &lt;code&gt;-s guard&lt;/code&gt;，或手动下载 aerial-guard.apk 安装。&lt;/p&gt;
&lt;h2&gt;部署方式四：U 盘安装（不用电脑）&lt;/h2&gt;
&lt;p&gt;把 APK 拷进 U 盘，插到电视上用文件管理器打开安装即可，三个版本对应前面的版本表。这条路最省事，但要注意：只装 APK 时，按主页键、开机和待机后大概率还是原桌面——接管所需的授权（无障碍、通知监听）还没设置。1.32 版起「我的应用」里有 Aerial 图标，打开后会提示怎么设为主屏幕；要完整接管，最终还是建议用命令或 Agent 补设置一次。&lt;/p&gt;
&lt;h2&gt;升级方式&lt;/h2&gt;
&lt;p&gt;1.32 版起，有新版本时控制中心会出现「有新版本」，点进去选「下载并安装」，在电视自己的安装界面确认即可（已在小米、TCL 上验证），装完回到 Aerial，设置全部保留。电视不允许 App 内安装应用时，升级就是再运行一次安装命令；升级页上有二维码，手机扫码能直接复制这台电视的专属命令。1.31 及以前的版本没有这个按钮，第一次升级仍要跑一次安装命令，之后就有了。&lt;/p&gt;
&lt;h2&gt;还原方式&lt;/h2&gt;
&lt;p&gt;不想要了，随时能退回去，一行命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -fsSL https://aerial.qust.me/install.sh | TV=192.168.1.20 bash -s restore
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;末尾加 &lt;code&gt;--uninstall&lt;/code&gt; 会顺便把 Aerial 卸载干净。不能运行 bash 的 Windows 环境，官网安装说明里有逐条对应的 adb 还原命令。同样可以把还原任务交给 Agent，官方也准备了现成的还原指令文本，验收标准是还原后 &lt;code&gt;mCurrentFocus&lt;/code&gt; 不再指向 Aerial、无障碍列表里不再有它。&lt;/p&gt;
&lt;h2&gt;Aerial Lite：给 Android 4.0–4.4 老电视的版本&lt;/h2&gt;
&lt;p&gt;老电视、老盒子的界面框架装不了完整版（最低 Android 5.0），所以有单独的 Lite 版，包名 &lt;code&gt;app.orchard.tv.lite&lt;/code&gt;，外观和完整版一样。目前是第一版（1.0），属于测试版：只在 Android 4.0.4 / 4.4.4 虚拟机和小米、TCL 的新电视上测过，还没在真实的 4.x 电视上验证过，官方明确说可能有不少小问题。&lt;/p&gt;
&lt;p&gt;安装命令和完整版是同一条脚本（识别到 4.x 自动装 Lite），也可以明确指定：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -fsSL https://aerial.qust.me/install.sh | TV=192.168.1.20 bash -s lite
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;手动安装：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;adb connect 192.168.1.20:5555

adb install -r aerial-lite.apk

adb shell pm grant app.orchard.tv.lite android.permission.WRITE_SECURE_SETTINGS
# 这条是给调亮度用的；Android 4.0 上会报错，可以忽略

adb shell am start -n app.orchard.tv.lite/.HomeActivity
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;装好后按主页键，系统问「使用哪个应用」时选 Aerial Lite 并选「始终」。不弹选择、直接回原桌面，说明固件把主页键锁死在自家桌面，Lite 只能从应用列表打开当普通 App 用——小米电视 2、华为盒子都栽在这一关，属于固件层面的无解。&lt;/p&gt;
&lt;p&gt;和完整版的区别：没有桌面守护（无障碍接管），开机和主页键全靠系统默认桌面机制；没有航拍壁纸、「我的视频」壁纸和信号源磁贴（4.x 没有电视输入框架，信号源按钮打开的是电视自己的信号源面板）；没有应用内升级（升级就是再装一次，设置保留）。航拍屏保、照片与每日一图、时钟、文件夹、长按菜单、控制中心、个性化、手机配置页都有。还原：设置 → 应用 → Aerial Lite → 清除默认设置，再按主页键选回原桌面；或 &lt;code&gt;adb uninstall app.orchard.tv.lite&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;源码构建与自部署（开发）&lt;/h2&gt;
&lt;p&gt;想自己改、自己编译的人，仓库给的开发环境要求是 JDK 17 与 Android SDK 36，构建命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;./gradlew assembleStandardRelease assembleGuardRelease
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;一次打出 standard 与 guard 两个 Release 包。编译完直接部署到电视调试：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;BUILD=1 KEEP_ADB=1 TV=&amp;lt;电视IP&amp;gt; tools/install.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;BUILD=1 表示用本地刚构建的包而不是下载官方 APK，其余参数与正式安装一致。仓库的结构也值得一提：app 是主应用，lite 是 Lite 版，site 是官网与安装脚本（aerial.qust.me 的内容就来自这里，仓库用 Cloudflare 的 wrangler 配置托管），tools 放安装与诊断脚本。深入之前先读两份文档：ARCHITECTURE.md 讲代码结构，HANDOFF.md 讲现状与规则，各机型的实测笔记在 docs/devices/ 目录里。仓库根目录还放了 AGENTS.md 和 CLAUDE.md——这个项目本身就是用编程 Agent 协作开发的，前面「让 Agent 装」的一键指令能成立，靠的也是这套文档化传统。&lt;/p&gt;
&lt;h2&gt;机型支持概览&lt;/h2&gt;
&lt;p&gt;仓库维护了一份很长的实测机型表（大多来自用户反馈），这里按品牌给结论速览，细节以仓库表格为准：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;品牌&lt;/th&gt;
&lt;th&gt;总体情况&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;小米 / Redmi&lt;/td&gt;
&lt;td&gt;支持最全：Android 5.1 到 14 大量机型实测可用，老 Android 6 机型 1.43 起支持，个别低内存机型回桌面要等几秒&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TCL / 雷鸟&lt;/td&gt;
&lt;td&gt;多数可用，但固件差异大：部分机型只能 USB 线连 ADB、部分必须用 guard 版；雷鸟个别机型固件每分钟清无障碍，接管不了&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;索尼&lt;/td&gt;
&lt;td&gt;国行 BRAVIA 多数可用；个别老机型固件锁主页键，需要 Agent 额外写 filterHomeAlways&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;创维 / 酷开&lt;/td&gt;
&lt;td&gt;参半：不少机型开机先出酷开桌面几秒再切回；个别机型黑屏或拿不到焦点，不支持&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;海信 / Vidda&lt;/td&gt;
&lt;td&gt;多数可用，部分开机直达；开 ADB 要走工厂菜单，是门槛最高的一家&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;极米 / 当贝等投影与盒子&lt;/td&gt;
&lt;td&gt;大多可用；当贝部分固件按主页键会强停第三方 App，Aerial 要 7–12 秒才回来&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;长虹 / 坚果等&lt;/td&gt;
&lt;td&gt;有明确不支持案例：不弹 ADB 授权框、没有无障碍入口、固件不让写无障碍设置&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;明确不支持的平台：LG webOS、三星 Tizen、华为鸿蒙智慧屏，以及 Android 4.0 以前的系统。打不开 ADB 的老乐视、荣耀智慧屏、老康佳（看不到版本号）也基本无解。&lt;/p&gt;
&lt;h3&gt;装好了但不对劲：适配求助&lt;/h3&gt;
&lt;p&gt;按主页键回原桌面、待机后停在原桌面、信号源开错口、亮度条没反应——这类机型适配问题有三条反馈路径：把官网 adapt.md 的指令发给 Agent 让它自检并当场修（比如信号源编号），报告经你确认后再提交；或者在电视上走控制中心 → 个性化 → 扫码，手机页底部「反馈问题」会自动把型号版本填进 GitHub 模板；电脑上也能自己跑两个官方脚本取诊断输出：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -fsSL https://aerial.qust.me/tools/report.sh | TV=&amp;lt;电视IP&amp;gt; bash
# 只读诊断

curl -fsSL https://aerial.qust.me/tools/selftest.sh | TV=&amp;lt;电视IP&amp;gt; bash
# 自检：模拟按主页键、打开设置，看 Aerial 能不能自己回来
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;诊断信息不含账号、IP、Wi-Fi 名称和 App 列表，可以放心贴。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;创维 &lt;code&gt;adb install&lt;/code&gt; 报 INSTALL_FAILED_USER_RESTRICTED。&lt;/strong&gt; 先执行 &lt;code&gt;adb shell settings put global verifier_verify_adb_installs 0&lt;/code&gt; 关掉安装校验，再重新安装（用户反馈的解法，官网安装说明有详细版）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;TCL 弹出「多屏互动」。&lt;/strong&gt; 按遥控器「右」再按确认，选「同意」——这是 TCL 的推送安装通道，guard 版在不少 TCL 机型上正是靠它装进去的。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;只用 U 盘装了 APK，按主页键还是原桌面。&lt;/strong&gt; 正常现象：接管需要的授权还没给。用一行命令或 Agent 补跑一次设置（覆盖安装，不丢设置），或按 Aerial 里「设为主屏幕」的引导去开无障碍与通知使用权。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;55V2 Pro 等机型 adb 装不上。&lt;/strong&gt; 先 &lt;code&gt;adb shell setprop persist.tcl.debug.installapk 1&lt;/code&gt; 再装，这是 TCL 部分固件的隐藏开关。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;找不到 ADB 开关。&lt;/strong&gt; 先查仓库 docs/devices/adb-by-brand.md 的分品牌说明；表里没有的机型，大概率藏在工厂菜单或需要遥控器暗号，别在设置里盲翻。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;老电视很卡。&lt;/strong&gt; 1.48 起低内存机型会自动切「流畅」效果；手动路径是 个性化 → 效果 → 流畅。斐讯 T1 这类老盒子切完后网格滚动会顺很多。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;原来的桌面和内容还在吗。&lt;/strong&gt; 都在。Aerial 只换桌面：原桌面在 App 列表里（小米影视、PatchWall 从「桌面」磁贴进），小爱同学、小米账号、有线电视照常使用。唯一去不掉的是开机广告——那是固件播的，和桌面无关，任何桌面都解决不了。这一点和 &lt;a href=&quot;/posts/selfhost-getting-started/&quot;&gt;自建服务入门&lt;/a&gt;里讲的「先分清问题在哪一层」是同一个道理。&lt;/p&gt;
&lt;h2&gt;许可与数据来源&lt;/h2&gt;
&lt;p&gt;项目本体是 MIT 许可证，可以自由使用和修改。几个组成部分的出处也交代得很清楚：界面字体 Inter 走 SIL 开放字体许可；系统 App 图标用的是 Material Symbols（Apache 2.0）；图标库里的磁贴图归各自作者（le5inioo 那套是 MIT，tvOS 版图标与当贝的图归各 App 与当贝，手机页上每张都注明来源）；天气用的国内城市表来自 GeoNames（CC BY 4.0），天气数据来自 Open-Meteo。航拍影片的版权归 Apple、由 Apple 服务器直接播放，必应每日精选来自必应——Aerial 与 Apple、小米、TCL 等公司无关，是独立的开源项目。这种把出处逐项列明的习惯，和它严格的机型实测表是同一种气质：可信是攒出来的。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Aerial 是那种目标单一但完成度极高的开源项目：一块干净的电视桌面。它把 tvOS 的界面语言搬进国产电视，用无障碍守护加通知复活的组合拳解决了「固件只认自家桌面」这个真正的难题，再用手机整理页、图标库和 114 段航拍屏保把体验补完整。部署上有四条路：怕命令的交给 Agent，有终端的一行命令，想看清每一步的手动 ADB，只有 U 盘的也能先装起来。装之前查一眼机型表、开 ADB 时对照分品牌说明、工厂菜单只动那一个开关，这三件事做到，基本一次成功。家里有台被广告桌面折磨的国产电视，值得一试。&lt;/p&gt;
</content:encoded></item><item><title>自建服务实战：MHub 把多平台歌单收进一个播放器</title><link>https://www.anexns.cloudns.org/posts/selfhost-mhub/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-mhub/</guid><description>在自己的服务器上部署 MHub：把 Apple Music、网易云、QQ 音乐等平台的搜索、歌单与推荐聚合到一个浏览器播放器里，用自己的账号听自己的歌单，附 Docker 部署、跨设备同步、无损播放与反向代理安全的完整实战。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;歌单散在三个平台，听歌先要做一道选择题&lt;/h2&gt;
&lt;p&gt;手机里装着三个音乐 App：通勤歌单在网易云，华语老歌收藏在 QQ 音乐，Apple Music 里还躺着一张订阅后慢慢攒起来的专辑列表。想听歌，第一步不是选歌，而是选 App——打开错了就得退出重开，队列更是各管各的，在这个平台排好的顺序，切到另一个平台全部作废。歌单想同步？只能手动一张一张对照着搬。&lt;/p&gt;
&lt;p&gt;MHub 的解法是把入口再收拢一层：它是一个自托管的多平台音乐播放器，把 Apple Music、网易云、QQ 音乐等平台的搜索、歌单与推荐聚合进同一个队列，在浏览器里直接播放，界面布局与交互按 Apple Music 网页版复刻，熟悉苹果生态的人几乎零学习成本。用自己的平台账号登录，听的还是自己歌单里的歌、自己订阅权益内的曲库，只是入口从三个变成了一个。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;自建 MHub 的核心价值就一句话：账号和歌单还是各平台自己的，但搜索、队列与播放入口只剩一个。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;认识 MHub 的功能全景 → 看懂架构与一首歌的数据流 → Docker 部署全流程 → 配置要点 → 反向代理与公网安全 → 日常维护 → 排障收尾&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/jizizr/mhub&lt;/p&gt;
&lt;h2&gt;功能全景：聚合、同步、无损、离线&lt;/h2&gt;
&lt;p&gt;MHub 是 2026 年 10 月才开源的新项目（AGPL-3.0，Rust 后端＋Vue 3 前端），功能密度却不低：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;多平台聚合&lt;/strong&gt;：一个搜索框同时查多个平台；歌单可从各平台导入，导入时自动做跨平台匹配，把原歌单里的歌对到其他平台的曲库上；同平台导入的歌单每天自动跟随原歌单同步，原歌单加了新歌，这边自动跟上。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;队列玩法完整&lt;/strong&gt;：追加、替换、下一首播放、拖动排序、随机、循环一应俱全；队列播完后自动续播走 Apple Music 的 AutoPlay 电台，不可用时退回同歌手与相似歌手的歌曲接上，不会冷场。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;无损播放&lt;/strong&gt;：ALAC 格式在浏览器里用 WASM 解码，按采样帧精确排程到 Web Audio 输出；其余格式走原生 audio 元素。后台播放靠双 audio 元素预载接力加 Media Session 接口，锁屏、切后台都不中断，锁屏界面还能控制切歌。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;歌词与氛围&lt;/strong&gt;：逐字歌词、封面取色生成的流动背景、简繁转换，歌词引擎是 AMLL、简繁转换用 OpenCC。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;离线与 PWA&lt;/strong&gt;：音频与歌词缓存进浏览器的 IndexedDB，可安装为 PWA，缓存过的歌断网也能听。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;可选账号体系&lt;/strong&gt;：支持通行密钥（Passkey）登录；个人资料库用 Yjs 文档经 WebSocket 在多台设备间实时同步，断网时本地编辑、联网后自动合并；还有「接着听」，换设备从上次的位置继续。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;可选音源网关&lt;/strong&gt;：同机部署的其他服务（比如 Telegram 机器人）可以经回环接口共用 MHub 同一份平台账号与缓存，一首歌只下载一次，多处受益。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;实际用起来，歌单导入的流程是这样的：在 MHub 里粘贴原平台的歌单链接，它先按原平台曲库把歌单原样收进来，再做一轮跨平台匹配——同一首歌在其他平台也有的话，条目上会多出可切换的来源，某个平台的版本不可用时直接换源播，不用重新搜。导入完成后，同平台那份歌单进入每日自动同步名单，原歌单的增删会跟随过来；跨平台匹配出的条目则固定在导入那一刻，算作一份跨源快照。&lt;/p&gt;
&lt;p&gt;要先说清楚一条边界：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;仓库不提供任何账号、会话或媒体文件&amp;lt;/span&amp;gt;，所有平台账号都要自备；Apple Music 的播放还需要自备账号并自建 wrapper / wrapper-lite 解密服务。最终能播什么，取决于你自己的平台账号、所在地区与上游接口状态。&lt;/p&gt;
&lt;h2&gt;架构：一首歌从点击到出声经历了什么&lt;/h2&gt;
&lt;p&gt;MHub 的技术栈先摆出来，后面讲数据流时好对位：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;层&lt;/th&gt;
&lt;th&gt;技术&lt;/th&gt;
&lt;th&gt;负责什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;后端&lt;/td&gt;
&lt;td&gt;Rust（Axum ＋ Tokio）&lt;/td&gt;
&lt;td&gt;平台接口聚合、播放任务调度、解密与缓存管理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;索引&lt;/td&gt;
&lt;td&gt;sqlx ＋ MySQL（可选）&lt;/td&gt;
&lt;td&gt;music_cache 表：缓存文件与 Telegram file_id 的索引&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;同步&lt;/td&gt;
&lt;td&gt;yrs（Yjs 的 Rust 实现）＋ WebSocket&lt;/td&gt;
&lt;td&gt;资料库文档多设备实时同步与离线合并&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;登录&lt;/td&gt;
&lt;td&gt;webauthn-rs&lt;/td&gt;
&lt;td&gt;Passkey 通行密钥认证&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;前端&lt;/td&gt;
&lt;td&gt;Vue 3 ＋ Pinia ＋ Vite&lt;/td&gt;
&lt;td&gt;播放器界面、队列状态、PWA 与离线缓存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;播放&lt;/td&gt;
&lt;td&gt;WASM 解码 ＋ Web Audio&lt;/td&gt;
&lt;td&gt;ALAC 在浏览器内解码并按采样帧排程输出&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;理解它最好的方式，是跟一遍点播一首歌的完整链路：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;建任务&lt;/strong&gt;：你点击播放，前端按「平台＋歌曲 ID＋音质」向后端创建一个播放任务；同一首歌被重复点播时任务去重，不会重复下载。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;选源&lt;/strong&gt;：后端根据任务去对应平台取源，拿到音频流。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;边下边解边播&lt;/strong&gt;：音频边下载边解密边送往浏览器，首个分片解密完成即可开播，不用等整首下完；ALAC 在浏览器端由 WASM 解码并精确排程，起播延迟压得很低。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;落盘缓存&lt;/strong&gt;：完整文件同时写入本地缓存；如果配了 Telegram 文件仓库，后台会把文件上传给 Bot，Bot API 返回的 file_id 连同元信息记入 MySQL 的 music_cache 表做索引。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;命中直达&lt;/strong&gt;：下次再播同一首歌，查索引命中缓存后直接转发文件，不再走解密流程，出声更快，也少打扰上游。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;这套「任务＋缓存＋索引」的设计，决定了 MHub 的两个性格：一是越听越快，常听的歌第二次起基本是本地速度；二是同机其他服务能通过音源网关蹭这份缓存，家里只存一份文件。音源网关的逻辑是：MHub 对外（仅限本机回环）留了一个取源接口，同机的 Telegram 机器人之类的服务要播或要发某首歌时，先问 MHub 要——命中缓存直接拿文件，没命中就由 MHub 按任务流程取源、落盘后再交付。平台账号只在 MHub 里配一份，解密流程只跑一遍，多个服务共用成果，这是它和「每个工具各配一遍账号」的玩法最不一样的地方。和本系列之前写的 &lt;a href=&quot;/posts/selfhost-jellyfin/&quot;&gt;Jellyfin&lt;/a&gt; 对比一句就能定位：Jellyfin 管的是你硬盘里已有的本地文件库，MHub 聚合的是各平台账号里的在线曲库，两者互补而不互替。&lt;/p&gt;
&lt;h2&gt;Docker 部署：首次构建要有耐心&lt;/h2&gt;
&lt;p&gt;官方推荐 Docker Compose 部署。注意第一次启动要现场编译 Rust 后端、ALAC 的 WASM 解码器与前端，耗时取决于机器性能，老机器等上十几分钟也正常，之后升级就快了。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git clone https://github.com/jizizr/mhub.git
cd mhub
cp config.example.toml config.toml
cp .env.example .env
docker compose up -d --build
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;起来后访问 &lt;code&gt;http://localhost:8000&lt;/code&gt;，先做两个验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl --fail http://localhost:8000/health
docker compose logs --tail=100 music
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;健康检查返回成功、日志没有报错，就可以打开页面开始配账号了。部署上有几个刻意的设计值得知道：配置文件以只读方式挂载进容器，改配置必须在宿主机上改完再重启容器；缓存放在命名卷 music-data 里；容器以非 root 用户运行、根文件系统只读，安全基线比一般的自建小服务要讲究。&lt;/p&gt;
&lt;p&gt;首次上手的顺序建议这样走：先在配置里填好一个平台的账号并重启服务，确认搜索与播放都通；再导入一张自己常用的歌单，检查跨平台匹配的结果对不对；最后才逐个补齐其他平台与可选组件（MySQL、Telegram 仓库、Passkey 同步）。一次全配满再排障，出了问题很难定位是哪一环。&lt;/p&gt;
&lt;h2&gt;配置要点：账号与解密服务都要自备&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;config.toml&lt;/code&gt; 是主配置，&lt;code&gt;.env&lt;/code&gt; 放环境变量类的敏感项，两个示例文件里的注释就是最好的说明书，这里只点关键处：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;平台账号&lt;/strong&gt;：逐个填入你自己的 Apple Music、网易云、QQ 音乐等账号凭据，用哪个平台配哪个，没配的平台不出现在搜索与歌单里。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;wrapper 解密服务&lt;/strong&gt;：Apple Music 的音频需要解密，自建 wrapper 或 wrapper-lite 后把地址填进配置；没有这一步，Apple Music 只能浏览不能播放。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;MySQL（可选）&lt;/strong&gt;：启用后 music_cache 索引落在 MySQL 里，配合 Telegram 文件仓库使用；不用 TG 仓库的话，本地缓存索引就够了。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Telegram 文件仓库（可选）&lt;/strong&gt;：填 Bot Token 与目标会话，缓存文件会后台上传，file_id 入库索引；这一步相当于把 Telegram 当成自家的对象存储，服务器磁盘紧张时很实用。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;账号体系（可选）&lt;/strong&gt;：想要多设备同步就开启 Passkey 登录与 Yjs 同步；纯单人单机使用可以不开，本地模式足够。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;监听地址&lt;/strong&gt;：确认服务的端口映射只绑回环地址，这是后面公网安全一节的前提。Compose 里对应的写法是把端口写成带 IP 的形式：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;ports:
  - &quot;127.0.0.1:8000:8000&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这样即使服务器有公网 IP，8000 端口也只对本机开放，外网访问只能走反向代理这一条受控通道。&lt;/p&gt;
&lt;p&gt;再强调一次口径：AGPL-3.0 只覆盖 MHub 的代码本身，不授予任何音乐内容的权利；用自己的账号、在平台服务条款允许的范围内使用，是这个项目正确的打开方式。&lt;/p&gt;
&lt;h2&gt;反向代理与公网安全：这一节别跳过&lt;/h2&gt;
&lt;p&gt;:::warning
MHub 的音乐 API 本身没有用户鉴权，服务默认只绑回环地址是有意为之。需要从外网访问时，必须套一层带访问控制的 HTTPS 反向代理（如 Basic Auth、IP 白名单或与本系列 NPM 方案结合的访问控制），&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝不能把配了自己平台账号的实例匿名暴露到公网&amp;lt;/span&amp;gt;——那等于把你的账号会话借给全互联网。另外注意：反向代理不要对音频流开启缓冲（proxy buffering），否则边下边播会被攒成整段下载，起播明显变慢。
:::&lt;/p&gt;
&lt;p&gt;用本系列写过的 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager&lt;/a&gt; 做反代时，关键配置思路如下（自带 NPM 的高级配置里追加）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 关闭代理缓冲，保证音频流式传输
proxy_buffering off;
# WebSocket 支持：跨设备同步与实时状态要用
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection &quot;upgrade&quot;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再在 NPM 里给这个站点开启访问控制列表，只放行自己的 IP 或加一道 Basic Auth，并申请好 HTTPS 证书。家里宽带没有公网 IP 的，用内网穿透或组网工具访问也完全可以，原则不变：任何路径下都要有鉴权。&lt;/p&gt;
&lt;h2&gt;日常维护：升级、备份与观察&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;升级&lt;/strong&gt;：拉新代码后重新构建即可，&lt;code&gt;git pull &amp;amp;&amp;amp; docker compose up -d --build&lt;/code&gt;；构建产物更新时前端与 WASM 会一并重编。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;备份&lt;/strong&gt;：真正要保的是两样——&lt;code&gt;config.toml&lt;/code&gt; 与 &lt;code&gt;.env&lt;/code&gt; 两个配置文件，以及命名卷 music-data（缓存与本地索引）。日常 &lt;code&gt;docker compose down&lt;/code&gt; 不会动命名卷，但 &amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;docker compose down -v 会连卷一起删，缓存清零&amp;lt;/span&amp;gt;，手滑之前想清楚。系统化的备份思路可参考 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;备份与迁移&lt;/a&gt; 一篇。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;观察&lt;/strong&gt;：&lt;code&gt;/health&lt;/code&gt; 端点适合接进 Uptime Kuma 之类的监控做存活探测；出问题先看 &lt;code&gt;docker compose logs --tail=100 music&lt;/code&gt;，绝大多数故障（账号失效、上游接口变化、解密服务不通）都会在日志里留下线索。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;缓存管理&lt;/strong&gt;：常听的歌都会落盘，music-data 卷会随使用慢慢变大；磁盘紧张时优先把 Telegram 文件仓库打开，让完整文件多一份在 TG 侧，本地卷的压力会小很多。定期看一眼卷的占用，把很久没播的缓存清掉即可，不必追求全量留存——缓存的意义是加速二播，不是收藏。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;与下载工具分工&lt;/strong&gt;：想把歌真正下成文件归档，用 &lt;a href=&quot;/posts/selfhost-music-dl/&quot;&gt;go-music-dl&lt;/a&gt; 那类工具；MHub 的定位是在线聚合播放，缓存是为加速而非为归档。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;和同类方案摆在一起看&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;MHub&lt;/th&gt;
&lt;th&gt;Jellyfin&lt;/th&gt;
&lt;th&gt;各平台官方客户端&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;内容来源&lt;/td&gt;
&lt;td&gt;自己各平台账号的在线曲库&lt;/td&gt;
&lt;td&gt;自己硬盘里的本地文件&lt;/td&gt;
&lt;td&gt;自家平台曲库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;歌单&lt;/td&gt;
&lt;td&gt;多平台导入、跨平台匹配、同平台每日同步&lt;/td&gt;
&lt;td&gt;本地文件自建歌单&lt;/td&gt;
&lt;td&gt;只管自家歌单&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;播放入口&lt;/td&gt;
&lt;td&gt;一个浏览器页面、一个队列&lt;/td&gt;
&lt;td&gt;一个客户端、一个本地库&lt;/td&gt;
&lt;td&gt;几个 App 之间来回切&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;无损&lt;/td&gt;
&lt;td&gt;ALAC 浏览器 WASM 解码，取决于账号权益&lt;/td&gt;
&lt;td&gt;取决于本地文件本身&lt;/td&gt;
&lt;td&gt;取决于会员与平台策略&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;离线&lt;/td&gt;
&lt;td&gt;IndexedDB 缓存＋PWA&lt;/td&gt;
&lt;td&gt;本地文件天然离线&lt;/td&gt;
&lt;td&gt;各平台各自的下载缓存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;部署成本&lt;/td&gt;
&lt;td&gt;自备服务器＋自备账号与解密服务&lt;/td&gt;
&lt;td&gt;自备服务器＋自备文件&lt;/td&gt;
&lt;td&gt;零部署&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;表里最要紧的一行是第一行：MHub 不生产内容，它是你已有账号权益的一个聚合前台；文件不在你手里、想长期归档的，还是走本地库那条线。&lt;/p&gt;
&lt;h2&gt;常见问题排障&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;现象&lt;/th&gt;
&lt;th&gt;排查方向&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;首次启动迟迟打不开&lt;/td&gt;
&lt;td&gt;大概率还在编译，&lt;code&gt;docker compose logs&lt;/code&gt; 看构建进度，老机器耐心等&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;某平台搜不到结果&lt;/td&gt;
&lt;td&gt;该平台账号没配或已失效；也可能受账号地区与上游接口状态影响，重新登录账号再试&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Apple Music 能浏览不能播&lt;/td&gt;
&lt;td&gt;wrapper / wrapper-lite 解密服务没配或地址不对，先单独验证解密服务可用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;起播很慢、像在整首下载&lt;/td&gt;
&lt;td&gt;反向代理开了缓冲，关掉 proxy buffering；或缓存未命中且上游较慢，二播应明显变快&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;锁屏后播放中断&lt;/td&gt;
&lt;td&gt;检查浏览器是否允许后台播放与 Media Session；双 audio 预载接力需要浏览器不冻结页面媒体&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;同步不生效&lt;/td&gt;
&lt;td&gt;账号体系未开启或 WebSocket 被反代拦了，确认反代放行了 Upgrade 头&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;歌单不自动更新&lt;/td&gt;
&lt;td&gt;只有同平台导入的歌单才每日跟随原歌单同步；跨平台匹配出来的歌单是静态快照&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;清理空间想删缓存&lt;/td&gt;
&lt;td&gt;删 music-data 卷或在设置里清缓存即可，别用 &lt;code&gt;down -v&lt;/code&gt; 误伤配置外的其他卷&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;MHub 把「多平台账号、多份歌单」这个现代听歌的碎片化问题，用一个自托管聚合层解掉了：搜索、队列、歌词、同步、离线一站齐活，无损边下边播，缓存还能给同机其他服务复用。它的门槛也写在明处：账号与解密服务自备、首次构建慢、API 无鉴权决定了反代必须做对。把这三件事处理好，它就是家里服务器上很值得常驻的一个服务。&lt;/p&gt;
&lt;p&gt;适合部署的人很明确：手里有两个以上平台的账号、歌单分散、又愿意在自己服务器上维护一套账号配置的人。如果你只用一个平台，官方客户端就是最优解，没必要多养一个服务；跨平台听歌越频繁，MHub 省下的切换成本就越值，也越能体会「所有歌只排一个队列」的好处。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;选型一句话：本地文件库用 Jellyfin，在线多平台聚合用 MHub，先把鉴权与反代做对，再谈公网访问。&amp;lt;/span&amp;gt;&lt;/p&gt;
</content:encoded></item><item><title>Nginx 架构深挖：进程模型、配置结构与 location 匹配顺序</title><link>https://www.anexns.cloudns.org/posts/webserver-nginx-architecture/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/webserver-nginx-architecture/</guid><description>从 master/worker 进程模型与事件驱动讲起，拆开 Nginx 的配置块与继承关系，讲透 location 匹配的优先级规则与 try_files 的实际行为。</description><pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;很多人第一次装 Nginx 只干了两件事：把 &lt;code&gt;server&lt;/code&gt; 块抄进配置、跑 &lt;code&gt;nginx -t&lt;/code&gt; 没报错就完事。配置能跑，不等于理解它。等到某天出现「这个 location 为什么没命中」「改了配置为什么没生效」「一个请求到底走了哪条路」这类问题时，才发现自己对 Nginx 的认知停留在复制粘贴的层面。这篇就从最底层把 Nginx 的骨架拆开：它是怎么用进程扛起并发的，配置块之间怎么继承，一个请求进来之后按什么顺序被匹配——这些是后面反向代理、负载均衡、缓存等所有进阶内容的地基。&lt;/p&gt;
&lt;h2&gt;master 与 worker：一个管事、多个干活&lt;/h2&gt;
&lt;p&gt;Nginx 启动之后，系统里至少有两个进程：一个 master 进程和若干 worker 进程。可以用 &lt;code&gt;ps aux | grep nginx&lt;/code&gt; 亲眼看一下，输出大概是这个样子：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;root      1234  0.0  0.1  12345  2345 ?  Ss   10:00   0:00 nginx: master process /usr/sbin/nginx -g daemon on;
www-data  1235  0.0  0.2  12345  3456 ?  S    10:00   0:00 nginx: worker process
www-data  1236  0.0  0.2  12345  3456 ?  S    10:00   0:00 nginx: worker process
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;分工很明确：&lt;strong&gt;master 进程不处理任何请求&lt;/strong&gt;，它只负责读配置、开监听端口、管理 worker 的生死——worker 挂了就拉起一个新的，收到重载信号就让 worker 优雅地换配置。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要直接 kill 掉 master 进程&amp;lt;/span&amp;gt;，那样所有 worker 会跟着失去管理，正在处理的请求也会被一并掐断；想停服务用 &lt;code&gt;nginx -s quit&lt;/code&gt; 优雅退出。&lt;strong&gt;worker 进程才是真正干活的&lt;/strong&gt;，每一个 worker 都能独立处理成百上千个并发连接。master 只有一个，worker 有几个由 &lt;code&gt;worker_processes&lt;/code&gt; 决定，通常写 &lt;code&gt;auto&lt;/code&gt;，让 Nginx 按 CPU 核心数自己算。&lt;/p&gt;
&lt;p&gt;这种「一个管事、多个干活」的结构带来两个实打实的好处。第一是&lt;strong&gt;平滑重载&lt;/strong&gt;：执行 &lt;code&gt;nginx -s reload&lt;/code&gt; 时，master 让老 worker 继续把手头正在处理的请求做完、同时用新配置启动新 worker 接新请求，服务全程不断，不断连接也不丢——这也是生产环境改配置的标准姿势。第二是&lt;strong&gt;故障隔离&lt;/strong&gt;：某个 worker 因为个别请求崩掉，只影响它手里的连接，master 马上补一个新 worker 顶上，整个服务不会跟着倒。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;code&gt;nginx -s reload&lt;/code&gt; 不是万能的：它只对能热重载的配置生效，改动监听端口这类涉及 master 的部分、或者配置文件本身有语法错误，都会导致重载失败。每次改完配置先跑 &lt;code&gt;nginx -t&lt;/code&gt; 校验，通过了再 reload；reload 之后也要看一眼错误日志，确认新 worker 真的起来了。
:::&lt;/p&gt;
&lt;h2&gt;事件驱动：一个 worker 怎么同时伺候几千个连接&lt;/h2&gt;
&lt;p&gt;Nginx 能以很小的内存扛起高并发，靠的是事件驱动模型。传统模型是一个连接一个线程，连接一多线程就爆炸；Nginx 的 worker 是单线程的，它不为每个连接单独开线程，而是用操作系统的事件通知机制（Linux 上是 epoll）盯着所有连接：哪个连接有数据到了，就处理一下，处理完立刻去看下一个，中间不阻塞等待。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;worker_connections&lt;/code&gt; 就是单个 worker 能同时盯着的连接数上限，默认值 512，生产环境一般会调大。一个简单的换算关系是：理论最大并发连接数 ≈ &lt;code&gt;worker_processes&lt;/code&gt; × &lt;code&gt;worker_connections&lt;/code&gt;。但这个数字只是天花板，真正能撑多少还要看内存、文件句柄数和后端响应速度，调大之前先确认系统 &lt;code&gt;ulimit -n&lt;/code&gt; 的上限够不够。&lt;/p&gt;
&lt;p&gt;事件驱动还有一个隐含前提：&lt;strong&gt;worker 里不能有长时间阻塞的操作&lt;/strong&gt;。Nginx 的设计哲学是把耗时的工作交给别人——读磁盘用异步 IO、访问后端用非阻塞的网络调用，所以它自己永远不被某个慢请求拖住。这也是为什么 Nginx 做静态文件和反向代理特别快：它做的事全是「转发」而不是「等待」。&lt;/p&gt;
&lt;h2&gt;配置块与继承：先看清这张层级图&lt;/h2&gt;
&lt;p&gt;Nginx 的配置是一层套一层的块结构，从外到内依次是：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;events {
    worker_connections 1024;
}

http {
    include       mime.types;
    sendfile      on;

    server {
        listen 80;
        server_name example.com;

        location / {
            root /var/www/html;
        }

        location /api/ {
            proxy_pass http://127.0.0.1:8080;
        }
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;最外层是 &lt;code&gt;main&lt;/code&gt;（全局上下文），&lt;code&gt;events&lt;/code&gt; 块管连接层面的事，&lt;code&gt;http&lt;/code&gt; 块管 HTTP 服务，&lt;code&gt;server&lt;/code&gt; 块对应一个虚拟主机，&lt;code&gt;location&lt;/code&gt; 块对应这台虚拟主机里的一类请求路径。&lt;code&gt;include&lt;/code&gt; 指令可以把其他文件的内容原地展开，Debian/Ubuntu 上常见的 &lt;code&gt;sites-enabled&lt;/code&gt; 目录就是靠它组织多个站点的。&lt;/p&gt;
&lt;p&gt;理解配置的关键是&lt;strong&gt;继承规则&lt;/strong&gt;。大部分指令是「向下继承」的：在 &lt;code&gt;http&lt;/code&gt; 块里写了 &lt;code&gt;sendfile on&lt;/code&gt;，下面所有 &lt;code&gt;server&lt;/code&gt; 和 &lt;code&gt;location&lt;/code&gt; 默认都继承这个值；如果某个 &lt;code&gt;location&lt;/code&gt; 自己又写了一遍，就以它自己的为准。但有几类指令是例外，&lt;strong&gt;数组型指令不会继承&lt;/strong&gt;，最典型的就是 &lt;code&gt;add_header&lt;/code&gt; 和 &lt;code&gt;proxy_set_header&lt;/code&gt;：只要子块里写了任意一条 &lt;code&gt;add_header&lt;/code&gt;，父块里写的 &lt;code&gt;add_header&lt;/code&gt; 就全部失效，不会合并。这是个经典坑：有人在 &lt;code&gt;http&lt;/code&gt; 块里统一加了安全响应头，又在某个 &lt;code&gt;location&lt;/code&gt; 里单独加了一条，结果全站的安全头全丢了。&lt;/p&gt;
&lt;p&gt;另一个容易踩的坑是 &lt;code&gt;root&lt;/code&gt; 与 &lt;code&gt;alias&lt;/code&gt; 的区别。&lt;code&gt;root&lt;/code&gt; 是把 location 的 URI 拼到路径后面，&lt;code&gt;alias&lt;/code&gt; 是把 location 的前缀替换掉：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location /static/ {
    root /var/www;
}

location /images/ {
    alias /var/www/pictures/;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;请求 &lt;code&gt;/static/a.png&lt;/code&gt; 时，&lt;code&gt;root&lt;/code&gt; 的做法是拼出 &lt;code&gt;/var/www/static/a.png&lt;/code&gt;；请求 &lt;code&gt;/images/b.png&lt;/code&gt; 时，&lt;code&gt;alias&lt;/code&gt; 的做法是把 &lt;code&gt;/images/&lt;/code&gt; 换成 &lt;code&gt;/var/www/pictures/&lt;/code&gt;，得到 &lt;code&gt;/var/www/pictures/b.png&lt;/code&gt;。用 &lt;code&gt;alias&lt;/code&gt; 时注意末尾的斜杠必须成对出现——location 以 &lt;code&gt;/&lt;/code&gt; 结尾，alias 的路径也要以 &lt;code&gt;/&lt;/code&gt; 结尾，否则路径拼接会错位。&lt;/p&gt;
&lt;h2&gt;location 匹配：Nginx 先看谁、再看谁&lt;/h2&gt;
&lt;p&gt;一个请求进来之后，Nginx 先按 &lt;code&gt;server_name&lt;/code&gt; 找到对应的 &lt;code&gt;server&lt;/code&gt; 块，再在这个块里按规则找 &lt;code&gt;location&lt;/code&gt;。location 的匹配分四种写法，优先级从高到低是固定的：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;优先级&lt;/th&gt;
&lt;th&gt;写法&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;&lt;code&gt;location = /exact&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;精确匹配，URI 必须一字不差&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;&lt;code&gt;location ^~ /prefix/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;最长前缀匹配，命中后不再看正则&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;&lt;code&gt;location ~ \.php$&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;正则匹配，按配置文件中出现的顺序逐个试&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;&lt;code&gt;location /prefix/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;普通前缀匹配，取其中最长的那个&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;具体的匹配流程分三步走：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;先找精确匹配&lt;/strong&gt;。如果有 &lt;code&gt;location = /&lt;/code&gt; 这种写法且 URI 完全相等，直接命中，流程结束。精确匹配最常用来处理首页或健康检查路径。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;再找最长前缀匹配&lt;/strong&gt;。把所有普通前缀和 &lt;code&gt;^~&lt;/code&gt; 前缀都比一遍，取最长的那个记下来。如果这个最长的是 &lt;code&gt;^~&lt;/code&gt;，直接命中，不再看正则；如果不是 &lt;code&gt;^~&lt;/code&gt;，先记下来，再继续第三步。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;按顺序试正则&lt;/strong&gt;。从上到下逐个测试正则 location，第一个命中的就是结果。如果一个正则都没命中，就用第二步记下来的最长前缀。&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;location = /health {
    access_log off;
    return 200 &quot;ok&quot;;
}

location ^~ /static/ {
    root /var/www;
    expires 30d;
}

location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;
}

location / {
    root /var/www/html;
    index index.html;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拿几个请求走一遍就明白了。请求 &lt;code&gt;/health&lt;/code&gt;：第一步精确匹配命中，直接返回 &lt;code&gt;ok&lt;/code&gt;，连日志都不记。请求 &lt;code&gt;/static/logo.png&lt;/code&gt;：最长前缀是 &lt;code&gt;^~ /static/&lt;/code&gt;，直接命中，不会再去试后面的正则。请求 &lt;code&gt;/index.php&lt;/code&gt;：前缀匹配记下 &lt;code&gt;/&lt;/code&gt;，然后正则 &lt;code&gt;\.php$&lt;/code&gt; 命中，交给 PHP 处理。请求 &lt;code&gt;/about.html&lt;/code&gt;：没有正则命中，落回最长前缀 &lt;code&gt;/&lt;/code&gt;，按 &lt;code&gt;root&lt;/code&gt; 找文件。&lt;/p&gt;
&lt;p&gt;:::warning
正则 location 是按配置文件中的书写顺序逐个测试的，&lt;strong&gt;不是按正则写得有多精确排序&lt;/strong&gt;。两个正则都能匹配同一个 URI 时，写在前面的那个赢。调整顺序之前，先想清楚有没有更具体的规则被前面的宽泛规则抢走了。
:::&lt;/p&gt;
&lt;p&gt;还有一个细节值得单独提：&lt;code&gt;location /&lt;/code&gt; 这个写法看起来像个兜底，实际上它是「长度为零的前缀」，任何 URI 都能匹配它。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Nginx 选它只是因为没有更长的前缀可选，而不是因为它有什么特殊地位。&amp;lt;/span&amp;gt;Nginx 选它只是因为没有更长的前缀可选，而不是因为它有什么特殊地位。理解这一点，就不会再问「为什么我的请求走了 &lt;code&gt;/&lt;/code&gt; 而不是别的 location」——答案永远是：更具体的那条规则要么不存在，要么没排上。&lt;/p&gt;
&lt;h2&gt;try_files：文件找不到时按顺序试&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;try_files&lt;/code&gt; 是 Nginx 里最常用的「按顺序试」指令，写法是给出一串候选，最后一个是兜底：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location / {
    root /var/www/html;
    try_files $uri $uri/ /index.html;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;请求 &lt;code&gt;/about.html&lt;/code&gt; 时，Nginx 先试 &lt;code&gt;$uri&lt;/code&gt; 对应的文件 &lt;code&gt;/var/www/html/about.html&lt;/code&gt;，存在就直接返回；不存在就试 &lt;code&gt;$uri/&lt;/code&gt; 对应的目录；再不存在就按最后一个参数做内部重定向，去请求 &lt;code&gt;/index.html&lt;/code&gt;。单页应用（SPA）的部署基本都靠这一行：所有前端路由都不存在真实文件，最后统一落到 &lt;code&gt;index.html&lt;/code&gt;，由前端路由接管。&lt;/p&gt;
&lt;p&gt;要注意最后一个参数的两种形态：写成 &lt;code&gt;=404&lt;/code&gt; 就是直接返回 404 状态码，写成 URI 就是内部重定向到那个 URI（会重新走一遍 location 匹配）。用 &lt;code&gt;try_files $uri $uri/ =404&lt;/code&gt; 做静态站点时，目录不存在也不会误判成奇怪的响应。&lt;/p&gt;
&lt;p&gt;还有一个常见误区：&lt;code&gt;try_files&lt;/code&gt; 里不要写 &lt;code&gt;http://&lt;/code&gt; 开头的完整 URL 做兜底，那会触发 302 跳转到外部地址，多数情况下不是想要的效果。内部兜底用相对 URI，外部跳转用 &lt;code&gt;return 301&lt;/code&gt; 显式写清楚。&lt;/p&gt;
&lt;h2&gt;请求处理阶段：一句话带过全貌&lt;/h2&gt;
&lt;p&gt;从请求进入 Nginx 到响应发出去，中间要经过一系列阶段：读请求头、找 server、找 location、做重写、做访问控制、找内容、生成响应、写日志。大部分阶段对使用者是透明的，知道两个结论就够了：&lt;code&gt;rewrite&lt;/code&gt; 指令发生在 location 匹配之后、内容生成之前，所以它能改变请求最终落到哪个 location；而 &lt;code&gt;access_log&lt;/code&gt; 写在流程末尾，所以日志里记录的是处理完成后的最终状态，包括内部重定向之后的 URI。后面讲日志排障时还会回到这个话题。&lt;/p&gt;
&lt;h2&gt;排障：三个最常见的架构级问题&lt;/h2&gt;
&lt;p&gt;前面讲的都是「正常时怎么工作」，这里补三条「出问题时先查什么」。架构层面的故障大多不是配置写错一个单词，而是对上面某个机制理解错了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;改了配置，行为一点没变。&lt;/strong&gt; 先确认两件事：第一，改的是不是正在运行的那个 Nginx 读的配置文件——Debian/Ubuntu 上 &lt;code&gt;sites-enabled&lt;/code&gt; 里是符号链接，改源文件和改链接目标是两回事，用 &lt;code&gt;nginx -T&lt;/code&gt; 可以把实际生效的完整配置打出来核对；第二，改完有没有 reload。只改文件不 reload，master 手里的还是旧配置。&lt;code&gt;nginx -t&lt;/code&gt; 通过只说明语法没错，不代表已生效，reload 之后再看一眼错误日志里有没有新 worker 启动失败的记录。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;请求落到了意料之外的 location。&lt;/strong&gt; 先把匹配流程按本篇的优先级表手算一遍，重点查两处：有没有更具体的正则被写在前面的宽泛正则抢走了，以及 &lt;code&gt;^~&lt;/code&gt; 是不是把正则短路了。拿不准的时候可以临时打开 &lt;code&gt;rewrite_log on&lt;/code&gt; 并把 &lt;code&gt;error_log&lt;/code&gt; 级别调到 &lt;code&gt;notice&lt;/code&gt;，日志里会记录每一次内部重写与 location 的选择过程，复现一次请求就能看清路径。查完记得把日志级别调回去，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;生产环境长期开 debug 级日志会把磁盘写满&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;并发一上来就报 502 或连接被拒绝。&lt;/strong&gt; 先看错误日志里有没有 &lt;code&gt;worker_connections are not enough&lt;/code&gt;，有就是单个 worker 的连接数打满了，调大 &lt;code&gt;worker_connections&lt;/code&gt; 之前先确认 &lt;code&gt;ulimit -n&lt;/code&gt; 给每个 worker 的文件句柄够不够用——句柄数是硬上限，配置写得再大也突破不了它。另一个常见原因是 &lt;code&gt;worker_processes&lt;/code&gt; 只设了 1，单核扛全站流量，改成 &lt;code&gt;auto&lt;/code&gt; 让 Nginx 按核心数起 worker。调完之后用 &lt;code&gt;nginx -t&lt;/code&gt; 校验再 reload，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;调参数之前先看日志定性，不要凭感觉同时改五六个值&amp;lt;/span&amp;gt;，否则出了效果也不知道是哪一个起的作用。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这篇把 Nginx 的骨架拆成了四块：&lt;strong&gt;master/worker 进程模型&lt;/strong&gt;负责稳定与平滑重载，&lt;strong&gt;事件驱动&lt;/strong&gt;负责用一个 worker 扛起大量并发，&lt;strong&gt;配置块与继承规则&lt;/strong&gt;决定了每条指令到底对谁生效，&lt;strong&gt;location 匹配顺序与 try_files&lt;/strong&gt;决定了每个请求最终落到哪里。把这四块记牢，后面几篇讲反向代理、负载均衡、缓存时，每一条配置都能找到它落脚的位置，不再是「抄过来能跑就行」的黑盒。&lt;/p&gt;
&lt;p&gt;下一篇讲反向代理：&lt;code&gt;proxy_pass&lt;/code&gt; 后面那个斜杠到底改变了什么、请求头要怎么传、缓冲开还是关，以及上游连接怎么复用。反向代理的配置如果还停留在 &lt;a href=&quot;/posts/docker-nginx-https/&quot;&gt;《用 Docker 部署 Nginx 反向代理与自动 HTTPS》&lt;/a&gt; 那种「能跑起来」的水平，这篇架构是理解它的前提；如果站点多到手写配置开始吃力，也可以先看 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;《Nginx Proxy Manager：图形化反代与自动 HTTPS》&lt;/a&gt; 了解面板路线的取舍。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：Cindy 开源 AI 智能体</title><link>https://www.anexns.cloudns.org/posts/ai-cindy/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-cindy/</guid><description>Cindy 把 Claude Code、Codex、Pi 三种执行引擎装进同一个开源客户端：订阅与密钥自带、任务跨电脑与手机接续、多智能体分工协作，文件与执行记录留在自己的机器上。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：智能体越来越多，工作却越来越碎&lt;/h2&gt;
&lt;p&gt;这两年能干活的 AI 智能体一个接一个：Claude Code 在终端里写代码是一把好手，Codex 有自己的工作流，手机上又想随时看一眼进度。问题随之而来：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;各用各的订阅。&lt;/strong&gt; 这家买了 Claude 的订阅，那家充了 ChatGPT 的额度，每换一个工具就要重新登录、重新授权，钱花了好几份，额度却散在各处用不满。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;各跑各的机器。&lt;/strong&gt; 任务在公司电脑上跑了一半，回家换到自己的笔记本，只能开一个新对话，把背景、要求、文件再交代一遍。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;上下文搬来搬去。&lt;/strong&gt; 换引擎、换设备、换工具，每换一次就要人工搬运一次上下文，智能体本身很聪明，工作面却是碎的。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;Cindy 是什么 → 三种执行引擎如何同处一室 → 订阅、密钥与本地模型怎么接入 → 任务如何跨设备接续 → 多智能体怎么分工 → 同伴、技能与例行任务怎么养 → 权限与费用怎么算&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/makecindy/cindy ，官网 https://cindy.app/&lt;/p&gt;
&lt;h2&gt;它是什么：一个把设备和引擎都收拢起来的开源智能体&lt;/h2&gt;
&lt;p&gt;Cindy 是一个开源 AI 智能体客户端，Apache-2.0 许可证，覆盖 macOS、Windows、Linux、iOS、Android 五个平台。它的定位不是再造一个模型，也不是替代 Claude Code 这类工具，而是站在它们之上做一层收拢：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;把你的&lt;strong&gt;电脑和手机&lt;/strong&gt;连成一个工作面，任务、文件、模型配置跨设备接续；&lt;/li&gt;
&lt;li&gt;把你&lt;strong&gt;已有的订阅、API 密钥、本地模型&lt;/strong&gt;接进来，不要求你再买一份新的模型服务；&lt;/li&gt;
&lt;li&gt;把&lt;strong&gt;多个执行引擎&lt;/strong&gt;放进同一个任务里，共享任务历史、记忆与技能。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;有一个事实要先说清楚：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;这个仓库开源的是桌面与移动客户端，后端服务在另一个仓库、并不在这个开源范围内&amp;lt;/span&amp;gt;。客户端默认连接 Cindy 官方云服务来完成账号、设备连接与同伴同步；登录界面也提供「Skip Sign-In（跳过登录）」模式，不注册账号就能用本地智能体，只是依赖服务器的能力（跨设备、同伴云同步等）不可用。把它当成「客户端开源、服务官方托管」来理解，就不会对它的开放程度产生误会。&lt;/p&gt;
&lt;h2&gt;多执行引擎同处一室：Harness 与模型是两回事&lt;/h2&gt;
&lt;p&gt;Cindy 最核心的概念，是把&lt;strong&gt;执行引擎（harness）&lt;strong&gt;和&lt;/strong&gt;模型&lt;/strong&gt;拆成两个独立的选择：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Harness 是执行引擎&lt;/strong&gt;，负责组织工作：怎么读文件、怎么调用工具、怎么推进一个多步骤任务。Cindy 内置三种：Claude Code（它自己的智能体工作流）、Codex（编程工作流）、Pi（精简、开源、可扩展，支持多家模型提供商）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;模型是推理来源&lt;/strong&gt;，负责思考与生成：同一个 harness 可以配不同的模型，同一个模型也可以被不同的 harness 调用。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;两者分开选的实际好处是：一个任务做到一半，发现当前引擎不擅长这类活，可以直接切换 harness，会话本身留在 Cindy 里，切换时做的是引擎上下文的交接或重建，不用另开一个对话从头交代背景。任务历史、记忆、技能都是 Cindy 这一层的资产，不绑死在某个引擎内部。&lt;/p&gt;
&lt;p&gt;这与本系列之前聊过的 &lt;a href=&quot;/posts/ai-cli-assistants/&quot;&gt;CLI 智能体助手&lt;/a&gt; 是上下游关系：那篇讲的是各个 CLI 引擎各自怎么用，Cindy 解决的是「都用上之后怎么统一调度」；而与 &lt;a href=&quot;/posts/ai-coding-assistants/&quot;&gt;AI 编程助手横评&lt;/a&gt; 里那些单体编程工具相比，Cindy 不与它们竞争单点能力，它竞争的是工作面的完整度。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;Cindy&lt;/th&gt;
&lt;th&gt;直接单用 Claude Code / Codex&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;引擎选择&lt;/td&gt;
&lt;td&gt;Claude Code、Codex、Pi 三种 harness 同处一室，可在任务中切换&lt;/td&gt;
&lt;td&gt;锁定自家引擎，换引擎等于换工具&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;模型选择&lt;/td&gt;
&lt;td&gt;模型与引擎分开选，可混搭不同提供商&lt;/td&gt;
&lt;td&gt;基本绑定自家模型与订阅&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;跨设备&lt;/td&gt;
&lt;td&gt;电脑与手机同一账号接续同一任务，内置远程桌面&lt;/td&gt;
&lt;td&gt;以本机终端为主，换设备要重新开始&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;订阅利用&lt;/td&gt;
&lt;td&gt;已有订阅登录即用，多家订阅集中到一个入口&lt;/td&gt;
&lt;td&gt;每个工具只认自家的订阅&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;记忆与技能复用&lt;/td&gt;
&lt;td&gt;记忆、技能挂在 Cindy 层，换引擎不丢失&lt;/td&gt;
&lt;td&gt;沉淀在各自工具内，互不相通&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;多智能体协作&lt;/td&gt;
&lt;td&gt;同一任务内可分工：规划、并行执行、独立审查&lt;/td&gt;
&lt;td&gt;单智能体为主，组队要自己拼脚本&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;部署成本&lt;/td&gt;
&lt;td&gt;客户端免费、不用租服务器，任务跑在自己的电脑上&lt;/td&gt;
&lt;td&gt;同样本机运行，但每台机器各自配置&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;模型自带：先用你已经付过钱的东西&lt;/h2&gt;
&lt;p&gt;Cindy 在模型接入上的态度很明确：&lt;strong&gt;鼓励用你自己的订阅和密钥&lt;/strong&gt;。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;订阅登录即用。&lt;/strong&gt; Claude、ChatGPT、SuperGrok、Kimi Code、MiniMax、GitHub Copilot 等支持的订阅，登录授权后就能直接用，你原来为这些服务付的钱不浪费。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;密钥接入。&lt;/strong&gt; 其它支持的编程计划与模型提供商，用自己的 API 密钥连接，费用直接付给提供商，Cindy 不在中间加价。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;官方托管服务可选。&lt;/strong&gt; 不想折腾密钥，也可以买 Cindy 的托管模型服务，登录即用、一个入口通吃主流模型（费用口径见下文）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;本地模型（Beta）。&lt;/strong&gt; Ollama、llama.cpp、LM Studio 这类本地运行时可以接入，效果取决于模型与你的硬件，目前仍标注为 Beta。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;还有一个跨设备的妙用：模型配置可以「借」。比如家里的台式机上配好了某个提供商，笔记本上不必重复配置，只要那台机器在线并为该提供商开启了远程访问，就能借用它的模型通道干活。这里有个权限细节要留意：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;模型共享要求为对应提供商单独开启远程访问，别图省事把所有提供商的远程访问一股脑全开&amp;lt;/span&amp;gt;，用哪个开哪个，是这类「借通道」功能的正确姿势。&lt;/p&gt;
&lt;p&gt;需要泼的冷水也写在前面：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;客户端免费不等于模型免费用量&amp;lt;/span&amp;gt;，无论走订阅、密钥还是本地算力，提供商的计费与限额规则都照常生效。&lt;/p&gt;
&lt;h2&gt;跨设备：换屏幕，不断任务&lt;/h2&gt;
&lt;p&gt;Cindy 的设备观是「所有设备，一个 Cindy」：工作电脑、家里台机、笔记本、手机用同一个账号登录并授权后，彼此连通。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;接续任务。&lt;/strong&gt; 在一台设备上打开的会话，可以从另一台设备继续：看对话、拿文件，不用把材料复制进新对话。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;文件互达。&lt;/strong&gt; 可以浏览、预览、传输任务文件，把电脑上的成果取到手机上，或者从手机给电脑发材料。注意它不是整盘同步，项目文件始终留在它所在的那台电脑上，远程访问只是「连回去用」。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;远程桌面。&lt;/strong&gt; 聊天不够用时，手机上内置远程桌面能看到电脑的真实屏幕，直接打字、操作软件接管处理。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;模型也能旅行。&lt;/strong&gt; 上一节说的借用其它电脑的模型配置，同样建立在这套设备连接之上。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这套模式的前提同样明确：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;远程任务实际执行在你的电脑上，电脑必须开机、在线且保持授权；电脑关机或断网，手机再方便也无活可干&amp;lt;/span&amp;gt;。它省掉的是服务器租金和部署成本，不是物理规律。&lt;/p&gt;
&lt;p&gt;:::warning
「本地优先」不等于「数据不出门」。用在线模型时，必要的对话与文件内容会发给所选的模型服务；同伴的对话、记忆、技能与共享附件会经 Cindy 的服务同步；官方发行版还带有 TapDB 使用统计（只统计设备、版本、启动与活跃等产品级数据，不采集聊天与文件内容），介意的话可以在设置的「关于 / 使用统计」里关掉，本地跳过登录模式则不上报。把这三条数据流向分清楚，再决定哪些任务放进来。
:::&lt;/p&gt;
&lt;h2&gt;多智能体组队：一个任务，三种角色&lt;/h2&gt;
&lt;p&gt;单个智能体不够用时，Cindy 可以在一个任务里组织一支小队，官方给出的典型分工是三段式：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;规划（Plan）。&lt;/strong&gt; 用一个擅长深度推理的引擎加模型组合做架构、任务拆解与验收标准，先把「做什么、做到什么程度算完」定下来。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;并行执行（Execute）。&lt;/strong&gt; 多个 worker 同时开工，各自配适合自己的引擎与模型：一个写实现，一个补回归测试，一个做文档与迁移，互不阻塞。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;审查（Review）。&lt;/strong&gt; 换一个独立的引擎做质量关：看代码 diff、挑边界情况，给出通过还是返工的结论。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;关键不在「人多」，而在于整支队伍共享同一个任务上下文：目标、上下文与验收标准由 Cindy 持有，执行者换了几轮，标准不丢。这与用 &lt;a href=&quot;/posts/ai-dify-workflow/&quot;&gt;Dify&lt;/a&gt; 这类平台编排固定流水线的思路不同：Dify 更像预先画好的流程图，Cindy 的组队是在一个活任务里按角色调度引擎，更适合「边做边定」的开发类工作。&lt;/p&gt;
&lt;h2&gt;可塑性：把她养成队友&lt;/h2&gt;
&lt;p&gt;Cindy 的另一条主线是「养」：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;同伴（Companion）。&lt;/strong&gt; 常用角色可以长期保留：给它起名字、定职责（审查者、研究员、项目搭档）、存记忆、配技能，下次打开接着配合，不用每次重写一遍角色提示词。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;技能与插件。&lt;/strong&gt; SkillHub 是公开的技能与插件市场，可以装现成的，也可以把自己摸索出的好方法写成技能发布复用；插件用来连接日常工具（Slack、飞书、GitHub 等），装之前能看清它要的权限再授权。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;MCP。&lt;/strong&gt; 通过 MCP 可以把自己的内部工具与自建服务接进来，让她在你自己的系统环境里干活。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;例行任务（Automations）。&lt;/strong&gt; 在电脑上设定周期性的检查、处理与报告，聊天渠道里 @ 她也能直接派活。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Cindy 的记忆与技能是可查看、可修改的资产，而不是黑盒里的「感觉她变懂我了」——经验能沉淀下来、能检查、能改进，这是它区别于普通聊天助手的根本点。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;本地优先与权限：活交出去，话事权留住&lt;/h2&gt;
&lt;p&gt;把任务交给智能体，最怕的是它「自作主张」。Cindy 在控制权上给了几道闸：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;按任务设权限。&lt;/strong&gt; 每个任务单独设定访问范围，需要确认的操作会停下来等你批准，人在外面时手机上也能批。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;过程可见。&lt;/strong&gt; 工具调用与结果实时可看，随时可以补充方向或直接叫停；符合条件的本地 Git 任务能看代码 diff，还能用工作树（worktree）与检查点隔离改动。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;数据有归属。&lt;/strong&gt; 工作文件与完整执行记录留在你自己的电脑上，你的电脑就是你的服务器，不用另外租机器、搭后端。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;一句话概括它的取舍：执行可以放手，权限、过程与数据必须在自己手里。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;费用口径：软件免费，模型另算&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Free（0 美元）。&lt;/strong&gt; 客户端软件本身免费，自带密钥或已有订阅时，软件功能完整可用，不另收软件费。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Plus（每月 20 美元起）。&lt;/strong&gt; 官方托管模型服务：登录即用主流模型；按月购买的额度与月费金额对应，包月方案有 20% 的价格优惠，另有更高的 SUPER、ULTRA 档位。注意托管套餐不是无限量用模型，额度用完按其规则走。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Team（即将推出）。&lt;/strong&gt; 面向团队的统一配置与治理，目前在等候名单，用邮箱申请。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Enterprise（联系官方）。&lt;/strong&gt; 自托管网关、完整审计日志、成本归属等企业能力，单独沟通。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;算总账时记住拆开看：&lt;strong&gt;软件费、模型费是两笔账&lt;/strong&gt;。自带订阅的人，新增成本只有「零」；用托管服务的人，买的是省去配密钥的便利。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：已经在用 Claude Code 了，还有必要装 Cindy 吗？&lt;/strong&gt;
A：如果你的工作只发生在一台电脑、一个引擎上，直接用原工具更轻。Cindy 的价值出现在多设备、多订阅、多引擎交叉的场景：任务要跨机器接续、订阅有好几家、想让不同引擎在同一任务里分工，这时统一工作面省下的搬运成本才划算。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：切换 harness 之后，之前的上下文还在吗？&lt;/strong&gt;
A：会话留在 Cindy 里，切换时做的是引擎上下文的交接或重建，不需要你重新交代一遍背景。但要理解：两个引擎的内部状态并不会变得完全一致，切换后第一轮先确认它对任务现状的理解无误，再让它继续。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：手机能让任务在电脑关机后继续跑吗？&lt;/strong&gt;
A：不能。远程任务执行在你的电脑上，电脑需要在线并开启远程访问；手机只是另一个操作入口，不会自动把离线工作搬到云端。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：本地模型接不进来或效果差？&lt;/strong&gt;
A：先确认本地运行时（Ollama、llama.cpp、LM Studio）本身已正常提供服务，再在 Cindy 里连接。官方明确本地模型仍是 Beta，效果取决于模型能力与硬件，复杂任务建议先用在线模型验证流程，再考虑替换成本地。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：「Skip Sign-In」模式下为什么有些功能没有？&lt;/strong&gt;
A：跳过登录用的是纯本地智能体，账号态显示为未登录；跨设备连接、同伴云同步等依赖官方服务的能力在这个模式下不可用，需要这些功能就正常登录账号。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：模型共享在另一台设备上不可用？&lt;/strong&gt;
A：按顺序排查：提供模型的那台电脑是否在线、是否同账号登录、是否为该提供商开启了远程访问权限。三者缺一不可，权限是单独按提供商开的，检查时别只看总开关。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：文件在另一台设备上找不到？&lt;/strong&gt;
A：Cindy 不是整盘网盘同步，项目文件留在它所在的电脑上。在任务里访问的是该任务关联的文件与目录；想取任意文件，用远程桌面或文件传输功能，而不是指望它像网盘一样全盘镜像。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：担心使用统计上报，怎么关？&lt;/strong&gt;
A：桌面端在「设置 → 关于 → 使用统计」里关闭，移动端在设置里关；关闭后桌面端立即停止后续上报。统计只涉及设备、版本与活跃事件，不含聊天与文件内容。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Cindy 不是又一个「更强的模型」，而是一层&lt;strong&gt;把引擎、订阅、设备和经验都收拢起来的工作面&lt;/strong&gt;：三种 harness 同处一室、模型与引擎分开选；已有订阅不浪费，本地模型也能接；任务跨电脑与手机接续，还能组队分工；同伴、记忆与技能让经验沉淀为可复用的资产；权限、过程与数据则牢牢留在自己手里。&lt;/p&gt;
&lt;p&gt;适合谁：手里有两家以上订阅、两台以上设备、并且已经在用 Claude Code 或 Codex 的人——你的痛点不是「不够聪明」，而是「太碎」，Cindy 正是冲着这个痛点来的。只有一个工具、一台机器的人，暂时用不上它这一层。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：命令行里的 AI 助手</title><link>https://www.anexns.cloudns.org/posts/ai-cli-assistants/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-cli-assistants/</guid><description>把 AI 助手放进终端里用：官方 CLI、开源终端助手与本地模型三类工具的选型对比，以及查日志、批量改文件、写脚本、审代码、巡检服务器五个实战场景的完整命令示例。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说主线：为什么要把 AI 放进终端&lt;/h2&gt;
&lt;p&gt;上一篇聊 &lt;a href=&quot;/posts/ai-coding-assistants/&quot;&gt;AI 编程助手实战&lt;/a&gt; 时，把助手按形态分成了补全型、对话型和 Agent 型。这一篇换个切入角度，只讲一个形态：&lt;strong&gt;跑在命令行里的 AI 助手&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;终端有什么特别的？三点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;离文件最近&lt;/strong&gt;。你的代码、日志、配置、脚本本来就躺在终端能摸到的地方，助手不用等你复制粘贴，它自己就能读。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;能直接执行&lt;/strong&gt;。网页版和 IDE 里的助手大多只能&quot;说&quot;，终端助手能&quot;做&quot;：跑命令、改文件、执行测试，再根据真实输出修正自己。这是从&quot;参谋&quot;到&quot;干活的人&quot;的分界线。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;适合运维与脚本场景&lt;/strong&gt;。服务器上没有图形界面，没有 IDE，只有一个 SSH 会话。这时候能用的 AI，就只有命令行形态的。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;代价也很明确：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;它能执行命令，就意味着它能执行错命令&amp;lt;/span&amp;gt;。所以这一篇后半段会专门讲权限与安全——这不是可有可无的附录，而是终端助手能不能放心用的前提。&lt;/p&gt;
&lt;p&gt;主线就一条：&lt;strong&gt;先选对工具形态，再学会把活交出去，最后守住权限的底线。&lt;/strong&gt;&lt;/p&gt;
&lt;h2&gt;工具形态盘点：三类终端助手&lt;/h2&gt;
&lt;p&gt;市面上的命令行 AI 助手，按出身可以分成三类。先看对比表，再逐个说。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;形态&lt;/th&gt;
&lt;th&gt;代表工具&lt;/th&gt;
&lt;th&gt;模型来源&lt;/th&gt;
&lt;th&gt;上手门槛&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;官方 CLI 型&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;https://github.com/anthropics/claude-code&quot;&gt;Claude Code&lt;/a&gt;、&lt;a href=&quot;https://github.com/google-gemini/gemini-cli&quot;&gt;Gemini CLI&lt;/a&gt;、Codex CLI&lt;/td&gt;
&lt;td&gt;厂商自家模型，账号登录即用&lt;/td&gt;
&lt;td&gt;低，装好登录就能用&lt;/td&gt;
&lt;td&gt;日常开发、仓库级改动、长任务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;开源终端助手型&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;https://github.com/Aider-AI/aider&quot;&gt;Aider&lt;/a&gt;、&lt;a href=&quot;https://github.com/sst/opencode&quot;&gt;OpenCode&lt;/a&gt; 等社区工具&lt;/td&gt;
&lt;td&gt;自备 API Key，可换多家模型&lt;/td&gt;
&lt;td&gt;中，要自己配 Key 和模型&lt;/td&gt;
&lt;td&gt;想换模型、想控成本、喜欢折腾配置的人&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本地模型接入型&lt;/td&gt;
&lt;td&gt;上述开源工具接 Ollama 等本地运行时&lt;/td&gt;
&lt;td&gt;自己机器上跑的开源模型&lt;/td&gt;
&lt;td&gt;高，要先把本地模型跑起来&lt;/td&gt;
&lt;td&gt;代码不出内网、离线环境、零边际成本&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;官方 CLI 型：省心，能力上限高&lt;/h3&gt;
&lt;p&gt;Claude Code、Gemini CLI 这类工具是模型厂商亲自下场做的终端助手。共同特点是：安装一条命令，浏览器登录一次账号，立刻开工。它们对自家模型的工具调用、上下文管理做了深度适配，处理&quot;读懂整个仓库再动手改&quot;这类长任务时最稳。&lt;/p&gt;
&lt;p&gt;短板是绑定：模型只能用它家的，订阅或计费方式也由厂商定。对个人开发者来说，这类是默认起点——先用它把工作流跑顺，再考虑要不要换。&lt;/p&gt;
&lt;h3&gt;开源终端助手型：模型随便换&lt;/h3&gt;
&lt;p&gt;Aider 是这一类的老牌代表：在 Git 仓库里工作是它的设计原点，改完自动提交、diff 清晰。OpenCode 等新一代开源工具则更强调多模型与终端界面。这类工具的共同点是&lt;strong&gt;模型与工具解耦&lt;/strong&gt;：今天用这家的 API，明天换另一家，甚至同一个会话里贵活给强模型、杂活给便宜模型。&lt;/p&gt;
&lt;p&gt;代价是配置要自己操心：API Key 哪来、模型名填什么、上下文多长，都得自己查文档填对。新手最常见的翻车不是工具不好用，而是第一步配置就卡住。&lt;/p&gt;
&lt;h3&gt;本地模型接入型：数据不出门&lt;/h3&gt;
&lt;p&gt;第三类不是独立工具，而是接法：把开源终端助手（或支持自定义端点的官方工具）的模型端点，指向本地跑的 Ollama 之类运行时。本地部署的方法在 &lt;a href=&quot;/posts/ai-ollama-local-llm/&quot;&gt;Ollama 部署本地大模型&lt;/a&gt; 里已经完整写过，这里不重复。&lt;/p&gt;
&lt;p&gt;它的价值只有一个词：&lt;strong&gt;可控&lt;/strong&gt;。代码不离开你的机器，没有按量账单，断网也能用。代价是模型能力与云端旗舰有差距，且吃你的显卡。所以现实的组合往往是：敏感仓库、内网服务器走本地；普通项目走云端。&lt;/p&gt;
&lt;p&gt;:::warning
选型时先想清楚一件事：你要的是&quot;最强的大脑&quot;，还是&quot;最可控的管道&quot;。终端助手的本体只是管道，真正干活的是它背后接的模型。工具换来换去都学得会，选错模型来源才是真正的成本。
:::&lt;/p&gt;
&lt;h2&gt;通用上手流程：四步走通任何一款&lt;/h2&gt;
&lt;p&gt;不管选哪一类，上手流程都是四步：安装、认证、进目录、开第一句。下面以最常见的组合为例给命令，其他工具把命令名换掉即可，思路完全一致。&lt;/p&gt;
&lt;h3&gt;第一步：安装&lt;/h3&gt;
&lt;p&gt;官方 CLI 多数通过 npm 或官方脚本安装，开源工具多走 pip 或包管理器：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 官方 CLI 型（以 npm 分发的为例）
npm install -g @anthropic-ai/claude-code

# 开源终端助手型（以 Python 分发的为例）
python3 -m pip install aider-install
aider --version
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;装完先跑一次 &lt;code&gt;--version&lt;/code&gt; 和 &lt;code&gt;--help&lt;/code&gt;，确认命令在 PATH 里、版本对得上。&lt;strong&gt;这一步养成习惯，能省掉后面一半的&quot;为什么跑不起来&quot;。&lt;/strong&gt;&lt;/p&gt;
&lt;h3&gt;第二步：登录或配 API&lt;/h3&gt;
&lt;p&gt;官方 CLI 首次运行会拉起浏览器走 OAuth 登录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;claude
# 首次启动会给出登录链接，浏览器里授权后回到终端即可
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;自备 Key 的工具走环境变量，不要把 Key 写进任何会提交到 Git 的文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;export OPENAI_API_KEY=&quot;sk-...&quot;
export ANTHROPIC_API_KEY=&quot;sk-ant-...&quot;
# 写进 ~/.bashrc 或 ~/.zshrc 可以，但那个文件绝不能进仓库
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第三步：在项目目录里启动&lt;/h3&gt;
&lt;p&gt;终端助手的工作范围默认就是当前目录。&lt;strong&gt;在哪个目录启动，它就把哪个目录当世界&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd ~/projects/my-app
git status        # 先确认仓库干净，出事能回滚
claude            # 或 aider / gemini，在仓库根目录启动
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动后它一般会扫描目录结构、读关键文件建立上下文。仓库越大，首次扫描越久，这是正常现象。&lt;/p&gt;
&lt;h3&gt;第四步：第一句先让它&quot;只说不做&quot;&lt;/h3&gt;
&lt;p&gt;不管多信任，先用一句只读的问话验货：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;gt; 先不要改任何文件。读一下这个项目的结构，告诉我入口文件在哪、
&amp;gt; 用了什么框架、测试怎么跑。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它答得对，说明上下文建起来了；答得驴唇不对马嘴，先解决模型或目录问题，别急着派活。&lt;/p&gt;
&lt;h2&gt;五个实战场景：把活真正交出去&lt;/h2&gt;
&lt;p&gt;下面五个场景，是终端助手在日常开发与运维里出场率最高的用法。每个都给完整的会话示例，注意看&lt;strong&gt;交活的方式&lt;/strong&gt;——怎么描述、怎么限定范围、怎么验收——这比工具本身更决定成败。&lt;/p&gt;
&lt;h3&gt;场景一：解释报错日志&lt;/h3&gt;
&lt;p&gt;日志排障是终端助手最被低估的用法。它能直接读日志文件、定位报错行、再顺藤摸瓜去读相关代码，比你把日志片段粘贴到网页对话框里强得多。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 服务起不来，先把日志攒下来
docker compose logs --tail=500 app &amp;gt; /tmp/app.log
journalctl -u myservice --since &quot;10 min ago&quot; &amp;gt; /tmp/svc.log
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;&amp;gt; 读 /tmp/app.log 最后这段启动失败的日志：
&amp;gt; 1. 先告诉我第一个真正的错误是什么（不要被后面的连锁报错带偏）；
&amp;gt; 2. 再去代码里找对应的位置，解释触发条件；
&amp;gt; 3. 先给结论和证据，不要动文件。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;关键技巧是那句&quot;第一个真正的错误&quot;。日志排障的老手都知道，刷屏的往往是连锁反应，源头只有一处——把这句话写进提问里，答案质量立刻上一个台阶。&lt;/p&gt;
&lt;h3&gt;场景二：批量改文件&lt;/h3&gt;
&lt;p&gt;十几个文件里统一改一个函数签名、换一个配置项、批量补一段注释——这种活手工做枯燥易错，终端助手做又快又整齐，前提是把范围钉死。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;gt; 把 src/ 下所有 .ts 文件里对 oldFetch( 的调用，改成新签名
&amp;gt; newFetch(url, { timeout })，timeout 沿用各文件原来的默认值，
&amp;gt; 没有默认值的填 5000。
&amp;gt; 限制：只改 src/，不要动 tests/ 和 dist/；
&amp;gt; 改完列一个清单：每个文件改了几处。
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;# 它改完之后，你的验收动作永远是这个
git diff --stat
git diff
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;批量修改的验收纪律：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;永远用 git diff 逐行看完再提交，不要只看它给的总结&amp;lt;/span&amp;gt;。总结是它写的，diff 是事实。&lt;/p&gt;
&lt;h3&gt;场景三：写脚本并让它自测&lt;/h3&gt;
&lt;p&gt;写一次性脚本是终端助手的甜点区：需求一句话，产物能立刻跑，跑没跑对当场见分晓。诀窍是把&quot;自测&quot;写进任务本身。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;gt; 写一个 bash 脚本 clean-logs.sh：
&amp;gt; 删除 /var/log/app 下 30 天前的 .log 文件，压缩 7 天前的，
&amp;gt; 支持 --dry-run 只打印不执行。
&amp;gt; 写完自己用 --dry-run 在测试目录 /tmp/logtest 上跑一遍，
&amp;gt; 把输出贴给我看，再解释每个关键命令为什么这么写。
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;# 它交活之后，你的复核命令
bash -n clean-logs.sh          # 语法检查
shellcheck clean-logs.sh       # 静态检查，能抓出一堆坏习惯
./clean-logs.sh --dry-run      # 亲自再跑一遍 dry-run
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;让它先自测再汇报，能过滤掉一大半低级错误；但&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;涉及删除、覆盖的脚本，dry-run 输出必须你亲眼过一遍才许真跑&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h3&gt;场景四：Git 提交信息与代码审查&lt;/h3&gt;
&lt;p&gt;两个高频小活。一是根据 diff 生成像样的提交信息，告别满仓库的 &quot;fix&quot; 和 &quot;update&quot;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git add -A
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;&amp;gt; 看一下已暂存的 diff，写一条提交信息：
&amp;gt; 标题一行说清做了什么，正文列三点为什么。
&amp;gt; 用中文，不要出现&quot;优化代码&quot;这种空话。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;二是提交前让它先审一遍，相当于免费多一双眼睛：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;gt; 审查当前未提交的改动，按严重程度排序输出：
&amp;gt; 先列可能引入 bug 的（逻辑、边界、并发），
&amp;gt; 再列风格与可读性问题。只报告，不要改。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;审完的意见当参考不当圣旨——它指出的问题你要能复述出道理，复述不出来的，先当没看见，别为了改而改。&lt;/p&gt;
&lt;h3&gt;场景五：服务器巡检问答&lt;/h3&gt;
&lt;p&gt;SSH 到一台不熟的服务器上，先让助手陪你把家底摸清，比一条条敲命令猜高效得多：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;gt; 这是一台我刚接手的服务器，不要执行任何修改命令。
&amp;gt; 依次用只读命令帮我确认：系统版本、磁盘和内存余量、
&amp;gt; 在跑的主要服务、监听了哪些端口、最近有没有报错刷屏的日志。
&amp;gt; 最后汇总成一张表，并标出你觉得最该先处理的三件事。
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;# 它常用的只读巡检命令，你也应该眼熟
df -h &amp;amp;&amp;amp; free -h
systemctl --failed
ss -tlnp
journalctl -p err --since today | tail -30
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这类场景里事先声明&quot;不要执行修改命令&quot;至关重要。巡检是侦察，不是手术。&lt;/p&gt;
&lt;h2&gt;权限与安全：能干活的手，必须戴镣铐&lt;/h2&gt;
&lt;p&gt;终端助手与聊天机器人的本质区别，就是它握着一个真实的 Shell。这一节的每条习惯，都是在给这只手上保险。&lt;/p&gt;
&lt;h3&gt;确认习惯：命令先过眼，再落地&lt;/h3&gt;
&lt;p&gt;主流终端助手默认在执行命令、改文件前会请求确认。&lt;strong&gt;这个确认弹窗不是仪式，是你的最后一道闸&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;看清楚命令本体再回车，尤其是带 &lt;code&gt;rm&lt;/code&gt;、&lt;code&gt;mv&lt;/code&gt;、&lt;code&gt;chmod&lt;/code&gt;、&lt;code&gt;systemctl&lt;/code&gt;、&lt;code&gt;docker&lt;/code&gt; 的；&lt;/li&gt;
&lt;li&gt;它给的解释再动听，也以命令文本为准——解释是给人看的，执行的是命令；&lt;/li&gt;
&lt;li&gt;批量操作时逐条确认，不要开&quot;全部自动同意&quot;图省事。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;永远不要在生产服务器上开全自动执行模式。&amp;lt;/span&amp;gt;省下的那点回车时间，抵不上一次误删的恢复成本。真想提速，正确做法是给只读命令设白名单（如 &lt;code&gt;ls&lt;/code&gt;、&lt;code&gt;cat&lt;/code&gt;、&lt;code&gt;git status&lt;/code&gt; 免确认），写操作永远人工过闸。&lt;/p&gt;
&lt;h3&gt;危险命令拦截：三道防线&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;目录防线&lt;/strong&gt;：只在项目目录里启动它，别在 &lt;code&gt;/&lt;/code&gt; 或家目录这种&quot;全世界&quot;范围里开会话；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;版本防线&lt;/strong&gt;：动任何文件之前，工作区必须是干净的 Git 状态，或者至少有一份刚打的备份——出事能一键回到上一秒；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;账号防线&lt;/strong&gt;：日常用普通用户跑助手，需要 root 时它自然会卡在 sudo 密码上，这道卡是好事，别为了顺手给它免密 sudo。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;只读模式：巡检和答疑的默认姿势&lt;/h3&gt;
&lt;p&gt;很多工具提供计划模式、只读模式或&quot;不允许编辑&quot;的开关。凡是&quot;先看看、先问问&quot;的场景——巡检、审查、读陌生仓库——默认就该用只读姿势开局，确认它理解对了，再放开写权限。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;终端助手的正确打开方式是：默认只读，按需放权。&amp;lt;/span&amp;gt;这和运维里最小权限原则是同一条道理，只是对象从人换成了 AI。&lt;/p&gt;
&lt;p&gt;还有一个容易忽略的点：&lt;strong&gt;密钥与隐私&lt;/strong&gt;。助手会把读到的文件内容发给它背后的模型服务，仓库里的 &lt;code&gt;.env&lt;/code&gt;、私钥、客户数据都可能被它顺手读走。敏感项目要么在工具配置里排除这些路径，要么直接走本地模型路线。家里有多个订阅账号、想把额度统一成一个接口来喂给终端助手的，可以看 &lt;a href=&quot;/posts/ai-cliproxyapi/&quot;&gt;CLIProxyAPI：把 CLI 订阅包装成统一 API&lt;/a&gt; 那一篇，它就是干这个的。&lt;/p&gt;
&lt;h2&gt;与 IDE 助手的分工&lt;/h2&gt;
&lt;p&gt;终端助手不是来取代 IDE 助手的，两者的地盘很清楚：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;IDE 助手更合适&lt;/th&gt;
&lt;th&gt;终端助手更合适&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;工作现场&lt;/td&gt;
&lt;td&gt;正在编辑的文件、光标周围&lt;/td&gt;
&lt;td&gt;整个仓库、整个系统&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;典型任务&lt;/td&gt;
&lt;td&gt;补全、重构、边写边问&lt;/td&gt;
&lt;td&gt;批量改动、跑命令、排障、巡检&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;执行能力&lt;/td&gt;
&lt;td&gt;以建议为主&lt;/td&gt;
&lt;td&gt;能直接执行并看结果&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;无图形界面时&lt;/td&gt;
&lt;td&gt;用不了&lt;/td&gt;
&lt;td&gt;唯一选择&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;日常的舒服姿势是混着用：在 IDE 里写新代码，遇到&quot;全仓库统一改一处&quot;&quot;这服务为什么起不来&quot;这类活，切到终端交给 CLI 助手，改完再回 IDE 里看 diff。两者共用同一套 Git 状态，切换零成本。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：启动后它说找不到模型 / 401 认证失败？&lt;/strong&gt;
先分清是哪一类工具在报错。官方 CLI 多半是登录态过期，退出重新登录即可；自备 Key 的工具查三件事：环境变量名拼对没有、Key 有没有余额或额度、终端是新开的还是旧会话（旧会话读不到刚写进 &lt;code&gt;.bashrc&lt;/code&gt; 的变量，重开一个终端最省事）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：它改文件改到一半停住，或者反复试同一个错？&lt;/strong&gt;
通常是上下文太长或任务太糊。处理顺序：让它先总结&quot;已经改了什么、卡在哪&quot;，你看完再决定是缩小任务重来，还是自己接管。不要在同一个长会话里无限重试——错误会越滚越多。必要时用 &lt;code&gt;git checkout -- &amp;lt;文件&amp;gt;&lt;/code&gt; 回到干净状态，换一句更具体的指令重开。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：补全和回答质量突然变差？&lt;/strong&gt;
先确认它背后接的模型有没有被悄悄换掉（工具升级、默认模型变更都发生过）；本地模型路线则检查是不是显存不够导致模型被换成更低量化或回退到 CPU 跑——&lt;code&gt;ollama ps&lt;/code&gt; 一眼就能看出模型在不在 GPU 上。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：它想执行一条我看不懂的命令怎么办？&lt;/strong&gt;
看不懂就不要放行，这是铁律。让它逐段解释这条命令每个参数在干什么，解释完你还拿不准，就复制命令自己去查，或者让它换一条你看得懂的等效写法。助手被拒绝一次不会记仇，服务器删错一次会。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：在服务器上用，网络不通装不上工具？&lt;/strong&gt;
内网或离线环境本来就是本地模型路线的地盘：提前在有网的机器上把工具安装包和模型文件备好拷进去，或者干脆只在本地终端用 SSH 把命令递过去。不要为了装个助手去给生产服务器乱改网络配置，因小失大。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：费用涨得比预期快？&lt;/strong&gt;
长会话是账单刺客：上下文越滚越长，每一轮都要把前文重新算一遍钱。习惯上做到三点：任务完成就开新会话、长日志先截取关键段再喂、贵模型只留给真正难的活。用量统计和多账号调度这类进阶玩法，同样可以参考 CLIProxyAPI 那篇的思路。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;命令行 AI 助手的价值，不在于它会聊天，而在于它&lt;strong&gt;站在离文件和命令最近的地方&lt;/strong&gt;。选型的顺序是：先定模型来源（官方订阅、自备 API、还是本地模型），再挑顺手的工具外壳；用法的关键是把任务说清、把范围钉死、用 &lt;code&gt;git diff&lt;/code&gt; 验收；安全的底线是默认只读、写操作过眼、生产环境不开全自动。&lt;/p&gt;
&lt;p&gt;把这三件事做对，终端里就多了一个不知疲倦的搭档；做反了，它就是一台打字很快的闯祸机器。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;工具没有立场，你的使用习惯决定它是资产还是风险。&amp;lt;/span&amp;gt;&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：CLIProxyAPI 把 CLI 订阅包装成统一 API</title><link>https://www.anexns.cloudns.org/posts/ai-cliproxyapi/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-cliproxyapi/</guid><description>用 CLIProxyAPI 把 Gemini CLI、Codex、Claude Code 等官方订阅账号通过 OAuth 登录后，统一转成 OpenAI/Gemini/Claude 兼容 API：Docker Compose 部署、config.yaml 配置、多账号轮换、客户端接入与管理 API 全流程。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：订阅买了，却只能在官方 CLI 里用&lt;/h2&gt;
&lt;p&gt;现在主流 AI 厂商都在推 CLI 形态的编程工具：Google 的 Gemini CLI、OpenAI 的 ChatGPT Codex、Anthropic 的 Claude Code，还有 Antigravity、Grok Build、Kimi Code 这些。配套的订阅（比如 Google AI Pro、ChatGPT Plus/Pro、Claude 订阅）额度都不低，但有个共同的尴尬：&lt;strong&gt;这些额度被锁死在各自的官方 CLI 里&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;你想在自己顺手的编辑器插件里用，不行；想写个脚本批量跑任务，不行；想在第三方聊天客户端里调用，还是不行——因为厂商根本没给你一个标准 API 入口，订阅和 API 是两套计费体系，API 那套要另外按量付费。&lt;/p&gt;
&lt;p&gt;CLIProxyAPI 解决的就是这层隔阂：它把你已经登录的 CLI 账号接进来，对外统一暴露成 OpenAI / Gemini / Claude / Codex 兼容的标准 API。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;一句话定位：它是一个「订阅账号 → 标准 API」的转换层，让订阅额度第一次能被任何兼容客户端调用。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;讲清它是什么、解决什么问题 → Docker Compose 部署 → config.yaml 关键配置 → OAuth 登录账号与多账号轮换 → 客户端接入实测 → 管理 API 与用量统计 → 和 LiteLLM 的分工 → 风险与合规提醒&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/router-for-me/CLIProxyAPI ，官方文档：https://help.router-for.me/cn/&lt;/p&gt;
&lt;h2&gt;CLIProxyAPI 是什么&lt;/h2&gt;
&lt;p&gt;CLIProxyAPI 是一个开源的代理服务（Go 编写，MIT 协议），工作方式分两步：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;上游侧&lt;/strong&gt;：通过各厂商官方的 OAuth 登录流程，把你的 CLI 账号授权给它，登录凭证以文件形式保存在本地的凭证目录里。支持的账号来源包括 Gemini CLI、Antigravity、ChatGPT Codex、Claude Code、Grok Build、Kimi 等。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;下游侧&lt;/strong&gt;：对外提供 OpenAI（含 Responses）、Gemini、Claude、Codex、Grok 五种兼容格式的 API 端点，支持流式与非流式响应、Function Calling / 工具调用、多模态（文本＋图片）输入。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;也就是说，客户端只管按 OpenAI 格式发请求，CLIProxyAPI 在中间做协议翻译，再拿着你的订阅账号凭证去调上游模型，最后把结果转回客户端要的格式。多个同类账号还可以组队：同一厂商登录多个账号后，请求会在账号之间轮换分发，做负载均衡和额度摊薄。&lt;/p&gt;
&lt;h2&gt;它解决什么问题&lt;/h2&gt;
&lt;p&gt;把场景列一下就清楚了：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;订阅额度用满&lt;/strong&gt;：订阅是包月制，额度不用过期作废；转成 API 后，编辑器插件、脚本、自动化任务都能消耗这些额度，而不是只在官方 CLI 里慢慢敲。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;客户端自由&lt;/strong&gt;：任何支持 OpenAI 兼容接口的工具——编程助手、聊天客户端、翻译工具、工作流平台——填上 CLIProxyAPI 的地址和 Key 就能用上订阅背后的模型。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;多账号聚合&lt;/strong&gt;：手里有多个账号时，一个一个切换登录很痛苦；统一托管后对外只有一个入口，轮换、故障转移都由服务侧处理。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;协议互转&lt;/strong&gt;：客户端只会说 OpenAI 格式、模型只提供 Claude 格式这类错位，也能在这一层抹平。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;反过来，它不适合的场景也要说清：你需要的是厂商官方 API 的 SLA 保障、要开发票对公结算、要给团队几十号人发 Key——那应该走官方 API 或 &lt;a href=&quot;/posts/ai-litellm-gateway/&quot;&gt;LiteLLM 这类 API Key 网关&lt;/a&gt;，而不是个人订阅转换。&lt;/p&gt;
&lt;h2&gt;Docker Compose 部署&lt;/h2&gt;
&lt;p&gt;官方提供 Docker 镜像 &lt;code&gt;eceasy/cli-proxy-api&lt;/code&gt;，一条 Compose 文件就能跑起来。先建目录、准备两个挂载点：配置文件 &lt;code&gt;config.yaml&lt;/code&gt; 和凭证目录 &lt;code&gt;auths/&lt;/code&gt;。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    container_name: cli-proxy-api
    restart: unless-stopped
    ports:
      - &quot;8317:8317&quot;
    volumes:
      - ./config.yaml:/CLIProxyAPI/config.yaml
      - ./auths:/root/.cli-proxy-api
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;目录结构长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cliproxyapi/
├── docker-compose.yml
├── config.yaml        # 主配置文件
└── auths/             # OAuth 登录凭证文件，一账号一份
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动与看日志：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose logs -f cli-proxy-api
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;日志里看到监听 8317 端口、加载了配置文件，就说明服务本身起来了。此时还没有任何上游账号，接口调不通是正常的——先把配置写对，再去登录账号。&lt;/p&gt;
&lt;h2&gt;config.yaml 关键项&lt;/h2&gt;
&lt;p&gt;最小可用配置如下，逐项说明在后面：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 监听地址与端口；host 留空表示监听所有网卡，只在本机用可写 127.0.0.1
host: &quot;&quot;
port: 8317

# OAuth 凭证文件存放目录（容器内路径，与 Compose 的挂载对应）
auth-dir: &quot;/root/.cli-proxy-api&quot;

# 客户端访问这个服务时用的 Key，自己随便设强口令，可配多个分发给不同客户端
# 注意：这是「进门钥匙」，不是任何上游厂商的 API Key
api-keys:
  - &quot;sk-my-client-key-please-change&quot;

# 远程管理开关：默认关闭远程管理，只允许本机访问管理接口
remote-management:
  allow-remote: false
  # 管理密钥，管理 API 和管理面板都要用它鉴权，务必设强口令
  secret-key: &quot;my-management-secret-please-change&quot;

# 多账号调度策略：round-robin 轮询（默认），fill-first 填满一个再用下一个
request-retry: 3
routing:
  strategy: &quot;round-robin&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个容易踩的点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;api-keys&lt;/code&gt; 是给&lt;strong&gt;你的客户端&lt;/strong&gt;用的，和上游账号没有任何关系。客户端请求时把它当成 OpenAI 的 API Key 填进去即可。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;auth-dir&lt;/code&gt; 目录里的文件就是账号本体，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;凭证文件泄露等于账号直接被人拿走用，目录权限和备份都要按密钥级别对待。&amp;lt;/span&amp;gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;remote-management.allow-remote&lt;/code&gt; 默认 &lt;code&gt;false&lt;/code&gt; 时，管理接口只接受本机请求；改成 &lt;code&gt;true&lt;/code&gt; 之前先想清楚暴露面，见文末风险一节。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;账号登录：走一遍 OAuth&lt;/h2&gt;
&lt;p&gt;服务跑起来只是空壳，真正的燃料是账号。登录通过给主程序传 &lt;code&gt;--login&lt;/code&gt; 类参数完成，每种账号一个入口，常用的有：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 在容器里执行登录（以 Gemini 为例，其余同理换参数）
docker compose exec cli-proxy-api ./CLIProxyAPI --login                 # Gemini CLI
docker compose exec cli-proxy-api ./CLIProxyAPI --codex-login           # ChatGPT Codex
docker compose exec cli-proxy-api ./CLIProxyAPI --claude-login          # Claude Code
docker compose exec cli-proxy-api ./CLIProxyAPI --antigravity-login     # Antigravity
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;流程都一样：命令输出一个授权链接 → 在浏览器里打开、用你的订阅账号登录并授权 → 回调完成后，凭证自动写成一个 JSON 文件落进 &lt;code&gt;auths/&lt;/code&gt; 目录。无图形界面的服务器上，就把链接复制到本地浏览器打开，按提示完成回调即可。&lt;/p&gt;
&lt;p&gt;登录成功后可以看一眼目录确认：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ls -l auths/
# 每多登录一个账号，这里就多一份凭证文件
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;多账号轮换&lt;/strong&gt;不需要额外配置：同一厂商多登录几个账号，请求会自动按 &lt;code&gt;routing.strategy&lt;/code&gt; 的策略（默认轮询）在账号间分发。某个账号额度耗尽或报错，服务会重试并切换到其他可用账号——这也是它比手动切号省心的地方。配多个账号时注意，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把来路不明的账号凭证往里塞，来历不明的凭证文件同样可能反过来盗走你的服务。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;客户端接入&lt;/h2&gt;
&lt;p&gt;账号就位后，先用 curl 验证 OpenAI 兼容端点：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 列出当前可用模型
curl http://127.0.0.1:8317/v1/models \
  -H &quot;Authorization: Bearer sk-my-client-key-please-change&quot;

# 发一条对话请求（model 换成上一步列表里实际有的）
curl http://127.0.0.1:8317/v1/chat/completions \
  -H &quot;Content-Type: application/json&quot; \
  -H &quot;Authorization: Bearer sk-my-client-key-please-change&quot; \
  -d &apos;{
    &quot;model&quot;: &quot;gemini-2.5-pro&quot;,
    &quot;messages&quot;: [{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;用一句话解释什么是负载均衡&quot;}],
    &quot;stream&quot;: false
  }&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;能返回正常补全内容，整条链路就通了。之后任何客户端接入都是同一套填法：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Base URL&lt;/strong&gt;：&lt;code&gt;http://你的服务器:8317/v1&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;API Key&lt;/strong&gt;：config.yaml 里 &lt;code&gt;api-keys&lt;/code&gt; 配的任意一个&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;模型名&lt;/strong&gt;：以 &lt;code&gt;/v1/models&lt;/code&gt; 返回的列表为准&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;比如给编程工具当后端——把工具的模型供应商指向这个地址，它就会拿你的订阅额度干活；命令行 AI 助手类工具同理，细节可对照本系列的&lt;a href=&quot;/posts/ai-cli-assistants/&quot;&gt;《命令行里的 AI 助手》&lt;/a&gt;。除了 OpenAI 格式，它还提供 Gemini 格式（&lt;code&gt;/v1beta/...&lt;/code&gt;）与 Claude 格式（&lt;code&gt;/v1/messages&lt;/code&gt;）端点，原生吃这两种协议的客户端不用绕 OpenAI 格式也能直连。&lt;/p&gt;
&lt;h2&gt;管理 API 与用量统计&lt;/h2&gt;
&lt;p&gt;CLIProxyAPI 带一套管理 API（路径前缀 &lt;code&gt;/v0/management/&lt;/code&gt;），用 &lt;code&gt;secret-key&lt;/code&gt; 鉴权，能远程做这些事：查看与增删客户端 API Key、列出已登录的凭证文件、开关远程管理、热更新部分配置，不用每次都去改文件重启。官方还提供配套的 Web 管理面板，部署后按文档启用即可在浏览器里操作。&lt;/p&gt;
&lt;p&gt;两个使用要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;管理请求要带密钥请求头，本机调用也一样，别图省事把 &lt;code&gt;secret-key&lt;/code&gt; 留空——留空等于管理接口裸奔。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;用量统计&lt;/strong&gt;：较新的版本已经不再内置用量统计功能，官方推荐外接独立统计服务（如 CPA Usage Keeper、CPA-Manager-Plus 这类社区项目），它们通过管理 API 拉取数据，落库到 SQLite 再出仪表盘。想看每个账号烧了多少额度、哪个模型调用最多，装其中一个即可，部署细节见官方文档的 Usage Statistics 章节。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;与 LiteLLM 的分工&lt;/h2&gt;
&lt;p&gt;本系列上一篇 &lt;a href=&quot;/posts/ai-litellm-gateway/&quot;&gt;LiteLLM&lt;/a&gt; 和这篇经常被放在一起比较，其实两者聚合的东西根本不同，最好配合而不是二选一：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;CLIProxyAPI&lt;/th&gt;
&lt;th&gt;LiteLLM&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;聚合对象&lt;/td&gt;
&lt;td&gt;AI 产品的&lt;strong&gt;订阅账号&lt;/strong&gt;（OAuth 凭证）&lt;/td&gt;
&lt;td&gt;各厂商的 &lt;strong&gt;API Key&lt;/strong&gt;（官方计费通道）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;上游来源&lt;/td&gt;
&lt;td&gt;Gemini CLI、Codex、Claude Code 等 CLI 账号&lt;/td&gt;
&lt;td&gt;OpenAI、Anthropic、Gemini 等 100+ 厂商 API&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;计费方式&lt;/td&gt;
&lt;td&gt;吃订阅的包月额度，不另计费&lt;/td&gt;
&lt;td&gt;按官方 API 用量计费，网关只做转发&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;多账号/多 Key&lt;/td&gt;
&lt;td&gt;多账号轮询、故障切换&lt;/td&gt;
&lt;td&gt;多 Key 负载均衡、预算与限流&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;典型角色&lt;/td&gt;
&lt;td&gt;把「只能 CLI 里用」的额度解放出来&lt;/td&gt;
&lt;td&gt;团队统一网关、成本管控、协议标准化&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;合规属性&lt;/td&gt;
&lt;td&gt;灰色地带，取决于各厂商订阅条款&lt;/td&gt;
&lt;td&gt;官方通道，正规用法&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;分工结论：个人场景用 CLIProxyAPI 把已有订阅额度榨干，正规 API 需求走 LiteLLM 统一管理；两者甚至可以串联——CLIProxyAPI 作为 LiteLLM 的一个上游渠道接进去。&amp;lt;/span&amp;gt;选型思路的完整版在系列第一篇&lt;a href=&quot;/posts/ai-tools-overview/&quot;&gt;《AI 工具全景图与选型指南》&lt;/a&gt;里。&lt;/p&gt;
&lt;h2&gt;风险与合规提醒&lt;/h2&gt;
&lt;p&gt;这一节不是套话，是用之前必须想清楚的三件事：&lt;/p&gt;
&lt;p&gt;:::warning
&lt;strong&gt;账号条款风险&lt;/strong&gt;：把订阅账号转成 API 调用，并不在多数厂商订阅条款预期的使用方式之内。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;一旦被厂商判定违规，处置是封号而不是提醒，订阅费和账号里的其他权益可能一起没了。&amp;lt;/span&amp;gt;用不用、用哪个账号用，自己权衡，别拿大号主力账号去试水。
:::&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;凭证保管&lt;/strong&gt;：&lt;code&gt;auths/&lt;/code&gt; 里的 JSON 凭证等价于登录态，任何拿到文件的人都能以你的账号调用。不要进 Git 仓库、不要随手发人、备份要加密。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;网络暴露&lt;/strong&gt;：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;8317 端口不要直接暴露在公网。&amp;lt;/span&amp;gt;哪怕设了 &lt;code&gt;api-keys&lt;/code&gt;，暴露面也意味着别人可以持续爆破和白嫖你的订阅额度。远程使用优先走内网穿透到私有网络、或在前面套一层带鉴权的反向代理，只给自己的设备放行。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;管理面隔离&lt;/strong&gt;：&lt;code&gt;remote-management.allow-remote&lt;/code&gt; 能不开就不开；必须开时，&lt;code&gt;secret-key&lt;/code&gt; 用长随机串，并且不要和管理端口一起裸奔公网。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. 容器起来了，但 /v1/models 返回空列表&lt;/strong&gt;
还没登录任何账号，或凭证没被加载。先 &lt;code&gt;ls auths/&lt;/code&gt; 确认凭证文件存在，再看启动日志里有没有加载凭证的记录；文件不在就重新走一遍登录流程。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 客户端调用返回 401&lt;/strong&gt;
两种 401 别混淆：客户端 → CLIProxyAPI 这一段的 401，是 &lt;code&gt;api-keys&lt;/code&gt; 没填对（注意 Bearer 前缀和空格）；CLIProxyAPI → 上游的鉴权失败，是凭证过期或被吊销，回容器重新执行一次对应账号的登录命令刷新凭证。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 登录时浏览器回调失败、流程卡住&lt;/strong&gt;
服务器无图形界面时，授权链接要拿到本地浏览器打开，并保证回调能回到服务所在机器。实在走不通回调，就换一台能直连的机器先登录、把生成的凭证文件拷进服务器的 &lt;code&gt;auths/&lt;/code&gt; 再重启服务，效果一样。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 请求频繁返回 429 或额度错误&lt;/strong&gt;
单个账号的订阅额度到顶了。要么等额度窗口恢复，要么多登录几个账号摊薄——轮询策略下请求会自动分散。注意这解决的是「额度不够」而不是「绕过额度」，总额度还是那些。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. 某个模型调不通，其他模型正常&lt;/strong&gt;
多半是账号来源不对：每个模型只能由对应厂商的账号提供，比如 Claude 系列要 Claude Code 账号、GPT 系列要 Codex 账号。先用 &lt;code&gt;/v1/models&lt;/code&gt; 对照模型与账号的对应关系，再看日志里实际上游报错。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;6. 改了 config.yaml 不生效&lt;/strong&gt;
确认 Compose 挂载的是你改的那份文件（路径写错是最常见原因），然后 &lt;code&gt;docker compose restart&lt;/code&gt; 重启容器；管理类配置有些支持热更新，但端口、监听地址这类必须重启。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;CLIProxyAPI 的本质是&lt;strong&gt;协议与额度的转换层&lt;/strong&gt;：上游接 CLI 订阅账号的 OAuth 凭证，下游吐 OpenAI / Gemini / Claude 兼容 API。&lt;/li&gt;
&lt;li&gt;部署就三步：Compose 起服务 → 写对 config.yaml（端口、auth-dir、api-keys、管理密钥）→ 逐个账号走 OAuth 登录。&lt;/li&gt;
&lt;li&gt;多账号轮询是它的核心红利：订阅额度从「一个 CLI 里慢慢用」变成「一个标准入口随便接客户端用」。&lt;/li&gt;
&lt;li&gt;和 LiteLLM 不冲突：一个聚合订阅账号、一个聚合 API Key，按场景分工，甚至可以串联。&lt;/li&gt;
&lt;li&gt;最后再强调一次：凭证当密钥保管、端口别裸奔公网、账号条款风险自己掂量——工具是好工具，用法决定它是省钱利器还是封号导火索。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>AI 工具应用：AI 编程助手实战</title><link>https://www.anexns.cloudns.org/posts/ai-coding-assistants/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-coding-assistants/</guid><description>把 AI 编程助手用对地方：行内补全、对话改代码、仓库级 Agent 三种用法分层，主流工具形态盘点，以及给上下文、做验收、防幻觉的完整实战方法。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说结论：AI 编程助手是放大器，不是替代品&lt;/h2&gt;
&lt;p&gt;这两年 AI 编程工具进化得非常快，从最初的&quot;代码自动补全&quot;一路走到了能自己翻仓库、改一片文件、跑一遍测试的 Agent 形态。但工具越强，越容易出现两种极端用法：一种是把它当搜索引擎，问一句抄一段，出了问题就怪&quot;AI 不行&quot;；另一种是无条件信任，生成什么合并什么，最后在生产环境里还债。&lt;/p&gt;
&lt;p&gt;真正高效的用法在中间：&lt;strong&gt;你负责定方向、给上下文、做验收，AI 负责干体力活&lt;/strong&gt;。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;AI 编程助手的价值不在于替你写代码，而在于把你从重复劳动里解放出来，去做只有人能做的判断。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;三种用法分层 → 工具形态盘点 → 什么活该交给 AI → 提问实战（上下文四要素＋分步验收）→ 生成代码验收清单 → 团队与隐私注意事项&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;三种用法分层：补全、对话、Agent&lt;/h2&gt;
&lt;p&gt;AI 编程工具按&quot;自主程度&quot;可以分成三层，适合的活完全不同，先把这个框架立住，后面选工具、派任务都按它来。&lt;/p&gt;
&lt;h3&gt;第一层：行内补全&lt;/h3&gt;
&lt;p&gt;你写代码，它实时预测接下来几行，按 Tab 接受。特点是&lt;strong&gt;低打扰、低风险、高频次&lt;/strong&gt;。它不理解你的项目全局，只看得懂当前文件附近的上下文，所以最擅长的是&quot;模式明确&quot;的代码：循环、判空、参数填充、重复结构的第二三份。&lt;/p&gt;
&lt;h3&gt;第二层：对话改代码&lt;/h3&gt;
&lt;p&gt;你选中一段代码或一个文件，用自然语言提要求，它给出修改后的版本，你看 diff 决定接不接受。这一层开始需要你会&quot;提需求&quot;：改什么、不能动什么、改完要满足什么条件。适合中等粒度的任务：重构一个函数、给一段逻辑加错误处理、把回调改成 async/await。&lt;/p&gt;
&lt;h3&gt;第三层：仓库级 Agent&lt;/h3&gt;
&lt;p&gt;你给一个完整任务，它自己搜索代码库、读多个文件、制定修改计划、分步执行、跑测试验证。这一层适合跨文件的活：加一个贯穿前后端的功能、批量迁移 API 用法、全仓替换某个废弃依赖。但自主程度越高，失控的代价越大，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Agent 模式下不设检查点、让它一口气改几十个文件，是翻车概率最高的用法。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;三层对比一表看清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;行内补全&lt;/th&gt;
&lt;th&gt;对话改代码&lt;/th&gt;
&lt;th&gt;仓库级 Agent&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;自主程度&lt;/td&gt;
&lt;td&gt;最低，你写它猜&lt;/td&gt;
&lt;td&gt;中等，你说它改&lt;/td&gt;
&lt;td&gt;最高，你派活它执行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;上下文范围&lt;/td&gt;
&lt;td&gt;当前文件局部&lt;/td&gt;
&lt;td&gt;你选中的文件/代码段&lt;/td&gt;
&lt;td&gt;整个仓库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合任务&lt;/td&gt;
&lt;td&gt;样板代码、重复结构&lt;/td&gt;
&lt;td&gt;函数级重构、局部功能&lt;/td&gt;
&lt;td&gt;跨文件功能、批量迁移&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;出错代价&lt;/td&gt;
&lt;td&gt;低，一眼能看出来&lt;/td&gt;
&lt;td&gt;中，diff 可审查&lt;/td&gt;
&lt;td&gt;高，必须分步验收&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;对使用者的要求&lt;/td&gt;
&lt;td&gt;会写代码即可&lt;/td&gt;
&lt;td&gt;会提清晰需求&lt;/td&gt;
&lt;td&gt;会拆任务、会验收&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;实战建议：日常编码时三层混用。写新文件时靠对话层起骨架，填充细节时靠补全层加速，遇到跨文件改造时才请出 Agent 层，并且永远分步验收。&lt;/p&gt;
&lt;h2&gt;工具形态盘点：四类工具，各取所需&lt;/h2&gt;
&lt;p&gt;市面上的工具名字很多，但按形态分就四类。选型时先对形态，再看具体产品。&lt;/p&gt;
&lt;h3&gt;IDE 插件型&lt;/h3&gt;
&lt;p&gt;装在你现有的编辑器里，代表是 VS Code、JetBrains 全家桶里的各类 AI 插件。优点是不用换工作环境、学习成本低；缺点是受插件机制限制，深度能力（尤其是 Agent 式的多文件操作）通常不如原生设计的产品。这类是大多数人的起点。&lt;/p&gt;
&lt;h3&gt;独立 AI IDE 型&lt;/h3&gt;
&lt;p&gt;整个编辑器就是围绕 AI 设计的，代表如 Cursor、Windsurf 这类基于 VS Code 内核改造的产品。代码索引、上下文召回、多文件编辑都是原生能力，对话层和 Agent 层的体验最完整。代价是你要迁移整个工作环境，团队推广时还要考虑统一配置的问题。&lt;/p&gt;
&lt;h3&gt;终端型&lt;/h3&gt;
&lt;p&gt;直接在命令行里运行，代表如 &lt;a href=&quot;https://github.com/anthropics/claude-code&quot;&gt;Claude Code&lt;/a&gt;、Aider 这类工具。它们不挑编辑器，和 Git、测试命令、构建脚本天然衔接，特别适合&quot;改代码＋跑验证&quot;的闭环，也方便在服务器和远程环境里用。终端型的深入用法本系列有专篇：&lt;a href=&quot;/posts/ai-cli-assistants/&quot;&gt;AI 工具应用：命令行里的 AI 助手&lt;/a&gt;。&lt;/p&gt;
&lt;h3&gt;本地模型型&lt;/h3&gt;
&lt;p&gt;编辑器插件接本地部署的开源模型（如通过 Ollama 跑在自己机器或内网服务器上的模型），代表组合是 &lt;a href=&quot;https://github.com/continuedev/continue&quot;&gt;Continue&lt;/a&gt; 插件＋本地模型。好处是代码不出本机、没有按量费用；代价是模型能力比云端旗舰弱一档，补全和短对话够用，复杂 Agent 任务会吃力。搭建方法见专篇：&lt;a href=&quot;/posts/ai-continue-local-coding/&quot;&gt;AI 工具应用：Continue＋本地模型搭私有编程助手&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;:::warning
选型时最容易踩的坑，是拿补全层的工具去干 Agent 层的活，或者反过来用 Agent 层写样板代码。前者能力不够会反复出错，后者杀鸡用牛刀还引入不必要的失控风险。先想清楚你的主力任务在哪一层，再选工具。
:::&lt;/p&gt;
&lt;p&gt;价格方面各家订阅方案变化很快，本文不列具体数字，选型时以官网当前页面为准即可；形态和能力的判断框架是长期有效的，价格不是。&lt;/p&gt;
&lt;h2&gt;把活交对：适合与不适合的任务清单&lt;/h2&gt;
&lt;p&gt;工具选对了，还得任务派对了。判断标准很简单：&lt;strong&gt;结果容易验证的活，放心交；结果难以验证、错了代价大的活，谨慎交&lt;/strong&gt;。&lt;/p&gt;
&lt;h3&gt;放心交的活&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;样板代码&lt;/strong&gt;：CRUD 接口、数据模型定义、配置文件骨架。这类代码模式固定、写对写错一眼可见，是 AI 的主场。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;单元测试&lt;/strong&gt;：给已有函数补测试用例，尤其是边界值、异常分支。AI 写测试比人勤快得多，而且测试本身就是验证手段，错了跑一遍就知道。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;正则表达式&lt;/strong&gt;：写正则、解释正则、按样例反推正则。人脑维护正则的成本极高，让 AI 写、拿样例验，是性价比最高的用法之一。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;报错定位&lt;/strong&gt;：把报错堆栈和相关代码贴给它，让它列出最可能的三个原因和各自的验证方法。注意是&quot;列出假设&quot;，不是&quot;直接改&quot;，定位环节保持人在回路。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;文档与注释&lt;/strong&gt;：根据代码生成 README、API 文档、变更说明。这类活人懒得写、AI 不怕烦。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;陌生 API 的用法示例&lt;/strong&gt;：查一个不熟的库怎么用，让它给最小可运行示例，比翻文档快。但要警惕幻觉，见后面的验收清单。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;谨慎交的活&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;架构决策&lt;/strong&gt;：模块怎么拆、用什么存储、同步还是异步——这类决策的依据是业务约束和长期演进，AI 不掌握你项目的历史包袱，它给的往往是&quot;教科书最优解&quot;，不是&quot;对你最合适的解&quot;。可以让它列方案对比表，拍板必须是你。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;核心算法与并发逻辑&lt;/strong&gt;：锁、事务、状态机这类代码，错一个边界条件就是线上事故。AI 可以写初稿，但必须逐行审查加完备测试，不能整段信任。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;涉密与合规代码&lt;/strong&gt;：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;公司未公开的源码、密钥、内部接口细节，不要粘贴进云端 AI 工具。&amp;lt;/span&amp;gt;这类场景要么用本地模型方案，要么先脱敏再问，下文隐私部分会展开。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;大段一次性生成&lt;/strong&gt;：让它一口气写五百行新模块，几乎必然埋雷。拆成小步、步步验收，是贯穿全文的原则。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;提问实战：上下文四要素＋先复述再动手&lt;/h2&gt;
&lt;p&gt;对话层和 Agent 层的效果，七成取决于你给的上下文质量。同一个工具，会问的人和不会问的人，产出能差一个档次。&lt;/p&gt;
&lt;h3&gt;上下文四要素&lt;/h3&gt;
&lt;p&gt;每次提需求，尽量凑齐这四样：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;目标&lt;/strong&gt;：要达成什么效果，用一句话说清。比如&quot;给这个导出函数加分页&quot;，而不是&quot;优化一下这个函数&quot;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;现状&lt;/strong&gt;：相关代码贴出来，或者指明文件路径；用了什么框架、什么版本，有特殊约束一并说明。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;边界&lt;/strong&gt;：哪些不能动。比如&quot;不要改函数签名，其他地方还在调用&quot;、&quot;只能用标准库，不许加新依赖&quot;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;验收标准&lt;/strong&gt;：怎么算做完了。比如&quot;现有的三个测试用例必须全过，再补一个空列表的用例&quot;。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;这套要素的展开讲法，见本系列的提示词专篇：&lt;a href=&quot;/posts/ai-prompt-engineering/&quot;&gt;AI 工具应用：提示词工程实战&lt;/a&gt;。编程场景里，把四要素写进提示词，返工率会明显下降。&lt;/p&gt;
&lt;h3&gt;先复述，再动手&lt;/h3&gt;
&lt;p&gt;对稍复杂的任务，先让 AI 复述它的理解和计划，你确认后再执行。这一步能拦住绝大多数&quot;方向错了还跑很远&quot;的情况。复述环节重点看三件事：它理解的目标和你想的是否一致；它打算动哪些文件，范围有没有超界；它列的步骤里有没有明显多余或缺失的环节。&lt;/p&gt;
&lt;h3&gt;分步验收&lt;/h3&gt;
&lt;p&gt;把大任务拆成它每完成一步、你验收一步的节奏。验收点设在&quot;可独立验证&quot;的节点上：一个函数写完先跑它的测试，一个接口改完先手动调一次。步子越小，单步出错的修复成本越低。&lt;/p&gt;
&lt;h3&gt;提示词示例一：给老函数补测试并修边界&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;目标：给 utils/date_range.py 里的 iter_dates(start, end) 函数补单元测试，
并修复发现的边界问题。

现状：函数签名是 iter_dates(start: date, end: date)，生成从 start 到 end
的日期序列，当前实现我贴在下面。项目用 pytest，测试文件放在 tests/ 下，
风格参考 tests/test_smoke.py。

边界：不要改函数名和参数顺序；可以改实现内部逻辑，但要在回复里说明
改了什么、为什么。

验收标准：
1. 测试覆盖：start 等于 end、跨月、跨年、start 晚于 end（应抛 ValueError）
2. 先给出你的测试用例清单让我确认，再写测试代码
3. 写完后运行 pytest 并把结果贴出来

[在此处粘贴函数源码]
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;提示词示例二：让 Agent 做跨文件迁移，先出计划&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;任务：把项目里所有直接调用 requests 库的地方，迁移到项目内部的
http_client 封装（src/common/http_client.py）。

先不要改任何代码。第一步只输出迁移计划，包含：
1. 全仓搜索到的调用点清单（文件＋行号＋调用方式）
2. 哪些调用点可以直接替换、哪些因为用了 requests 特有参数需要特殊处理
3. 你建议的执行顺序

等我确认计划后，再按文件逐个执行：每改完一个文件，运行该文件相关的
测试，把 diff 摘要和测试结果发我确认，然后再继续下一个文件。
中途遇到计划外的问题，先停下来报告，不要自行扩大改动范围。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意第二个示例的结构：&lt;strong&gt;限定动作（先只出计划）＋明确产出格式＋分步确认节奏＋异常处理规则&lt;/strong&gt;。Agent 任务的提示词写到这个密度，基本就稳了。&lt;/p&gt;
&lt;h2&gt;生成代码的验收清单&lt;/h2&gt;
&lt;p&gt;AI 生成的代码进入你的仓库之前，至少过这四关：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;跑起来&lt;/strong&gt;：能编译、能启动、相关测试全过。这是底线，跑不过的生成代码没有任何讨论价值。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;看 diff&lt;/strong&gt;：逐行看改动，重点看三处——有没有顺手改了你没让它改的东西；有没有引入新依赖；错误处理是真处理了还是 &lt;code&gt;catch&lt;/code&gt; 后吞掉假装没事。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;查 API 真实性&lt;/strong&gt;：它调用的库函数、参数名、返回值，都要核对。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;AI 会一本正经地编造不存在的 API 和参数，这是最高频的翻车来源。&amp;lt;/span&amp;gt;核对方法很土但有效：去官方文档或源码里搜这个函数名，搜不到就是编的。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;补验证&lt;/strong&gt;：对它声称&quot;已处理&quot;的边界情况，自己构造一个输入实际跑一遍。口头保证不算数，运行结果算数。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;验收不是对 AI 的不信任，而是这套工作流的固定成本：省掉验收省下的时间，最后都会连本带利还回去。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;:::warning
特别注意测试代码本身也要验收。AI 写的测试有可能为了&quot;通过&quot;而迁就错误实现，比如把断言写成和当前（有 bug 的）输出一致。验收测试时要问一句：这个用例断言的是需求，还是现状？
:::&lt;/p&gt;
&lt;h2&gt;团队与隐私注意事项&lt;/h2&gt;
&lt;p&gt;个人用得顺手，推广到团队还要多考虑三件事。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一，代码外发边界要成文。&lt;/strong&gt; 明确哪些仓库可以用云端工具、哪些只能用本地模型、哪些连本地模型也要审批。尤其是有客户代码、未发布产品代码的团队，这条要在工具引入之前就定好，而不是出了事再补。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二，密钥和配置绝不进提示词。&lt;/strong&gt; 调试时顺手把 &lt;code&gt;.env&lt;/code&gt;、数据库连接串、云厂商密钥贴进对话框，是真实发生过多次的事故源头。贴日志和代码前先扫一眼，敏感值打码再发；终端型工具要留意它自动读取的文件范围，别让它把整个家目录都当上下文。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三，提交规范照常执行。&lt;/strong&gt; AI 生成的代码走和手写代码完全相同的流程：同样的 Code Review、同样的测试门槛、同样的提交信息规范。不要在 commit 里用&quot;AI 写的&quot;当免责声明，也不要因为&quot;是 AI 写的&quot;就放松审查——进了仓库，责任就是提交人的。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;h3&gt;补全质量突然变差，猜的代码驴唇不对马嘴&lt;/h3&gt;
&lt;p&gt;先看上下文来源：补全工具主要参考当前文件和最近打开的文件，如果你在写的代码依赖一个还没打开过的模块定义，它自然猜不准。把相关定义文件打开、或者在当前文件顶部先写好 import 和类型标注，补全质量通常立刻回升。另外检查一下是不是文件太长，超长文件里离光标很远的关键定义可能已经被挤出上下文窗口。&lt;/p&gt;
&lt;h3&gt;对话改代码时，它总是顺手&quot;优化&quot;没让它动的部分&lt;/h3&gt;
&lt;p&gt;这是边界没说清的典型表现。在提示词里显式加一句&quot;只修改 X，其他代码保持原样，不要重构、不要调整格式&quot;，并在验收时对 diff 里计划外的改动直接打回。重复两三次后，把这句固化成你自己的提示词模板。&lt;/p&gt;
&lt;h3&gt;Agent 跑着跑着开始绕圈子，反复改同一个地方&lt;/h3&gt;
&lt;p&gt;通常是验收标准缺失或互相矛盾，它在两个错误方向之间横跳。处理方法：停下来，让它总结&quot;当前状态、已尝试的方法、各自的失败原因&quot;，你看完总结再给新指示。不要在它绕圈子的时候追加更多模糊要求，那只会让它绕得更快。&lt;/p&gt;
&lt;h3&gt;它给的 API 调用本地死活跑不通&lt;/h3&gt;
&lt;p&gt;大概率是幻觉 API 或版本不对。排查顺序：先查官方文档确认函数存在且签名一致；再确认你装的库版本与它假设的版本是否相同（很多&quot;跑不通&quot;是它在按新版本写、你装的是旧版本）；最后才怀疑自己的用法。养成习惯：凡是它给出的不熟悉 API，先搜文档再粘贴运行。&lt;/p&gt;
&lt;h3&gt;同一个问题问两次，答案完全不一样&lt;/h3&gt;
&lt;p&gt;正常现象，不要纠结于&quot;哪个是对的&quot;。把两次答案当作两个方案来评估，或者把矛盾点挑明了追问：&quot;你上次说用 A，这次说用 B，两者的取舍是什么？&quot;让它对比，比让它重复回答有用得多。&lt;/p&gt;
&lt;h3&gt;团队里有人抵触，觉得 AI 生成的代码不靠谱&lt;/h3&gt;
&lt;p&gt;不要争论，直接用数据：在一个低风险模块上试点两周，统计返工率和交付速度。多数抵触来自没用对层级——拿补全层干重构的活，当然不靠谱。按本文的分层把活派对，试点结果通常自己会说话。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;AI 编程分三层：补全管样板、对话管局部、Agent 管跨文件，自主程度越高越要分步验收。&lt;/li&gt;
&lt;li&gt;选工具先对形态：插件型低成本起步，独立 IDE 型体验完整，终端型贴合 Git 工作流，本地模型型守隐私。&lt;/li&gt;
&lt;li&gt;派活看可验证性：样板、测试、正则、定位、文档放心交；架构、涉密、核心并发谨慎交。&lt;/li&gt;
&lt;li&gt;提问凑齐四要素：目标、现状、边界、验收标准；复杂任务先复述计划再动手。&lt;/li&gt;
&lt;li&gt;生成代码必过验收四关：跑起来、看 diff、查 API、防假测试。&lt;/li&gt;
&lt;li&gt;团队推广先定外发边界，密钥永不进提示词，提交规范不打折。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;用对了层级和流程，AI 编程助手就是目前性价比最高的生产力工具；用错了，它就是个生成返工的机器。差别不在工具，在用法。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：ComfyUI 绘图入门与节点工作流</title><link>https://www.anexns.cloudns.org/posts/ai-comfyui-beginner/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-comfyui-beginner/</guid><description>从安装到逐节点拆解默认文生图工作流，讲清 KSampler 每个参数管什么，再概览图生图、高清修复、局部重绘与 ControlNet，带你真正上手 ComfyUI 的节点式绘图。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说结论：为什么认真画图的人最后都去了 ComfyUI&lt;/h2&gt;
&lt;p&gt;AI 绘图工具大致分两类界面：一类是表单式的 WebUI——填提示词、拉几个滑杆、点生成，简单直接；另一类就是 ComfyUI 这种节点式的——整个生成过程摊开成一张流程图，每个环节是一个节点，连线就是数据流。刚打开 ComfyUI 的人通常会被满屏的框和线吓退，但只要你想做的事稍微复杂一点，比如「先生成、再放大、再局部重绘、最后按另一张图的姿势摆好」，表单式界面就会开始不够用，而节点式可以把每一步明明白白串起来、单独调、单独重跑。&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;装好 ComfyUI → 搞懂节点与工作流的概念 → 把默认文生图工作流逐个节点拆开讲透 → 吃透 KSampler 参数表 → 概览图生图、高清修复、局部重绘、ControlNet 四种进阶玩法 → 知道模型和自定义节点去哪找&lt;/strong&gt;。跟着走完，你不光会出图，还能看懂别人分享的工作流并改成自己的。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/comfyanonymous/ComfyUI&lt;/p&gt;
&lt;h2&gt;ComfyUI 是什么：把生成过程摊开给你看&lt;/h2&gt;
&lt;p&gt;ComfyUI 是一个基于节点的 Stable Diffusion 图形界面后端。它的核心思想是：扩散模型的生成过程本来就是一串确定的步骤——加载模型、编码提示词、从噪声开始采样、解码成像素——那就干脆把每一步做成一个节点，让用户自由拼装。&lt;/p&gt;
&lt;p&gt;和表单式 WebUI 的区别，可以这样理解：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;表单式 WebUI&lt;/th&gt;
&lt;th&gt;ComfyUI&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;上手难度&lt;/td&gt;
&lt;td&gt;低，填空点按钮&lt;/td&gt;
&lt;td&gt;高，先要理解节点与连线&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;流程可见性&lt;/td&gt;
&lt;td&gt;黑盒，只能调暴露出来的参数&lt;/td&gt;
&lt;td&gt;全透明，每一步的输入输出都看得见&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;复杂流程&lt;/td&gt;
&lt;td&gt;靠插件堆功能，互相容易冲突&lt;/td&gt;
&lt;td&gt;自己串节点，想怎么组合怎么组合&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;复现与分享&lt;/td&gt;
&lt;td&gt;靠抄参数&lt;/td&gt;
&lt;td&gt;整个工作流就是一个 JSON 文件，拖进去即还原&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;显存占用&lt;/td&gt;
&lt;td&gt;相对较高&lt;/td&gt;
&lt;td&gt;相对较低，模型卸载与调度更积极&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;出图一致性&lt;/td&gt;
&lt;td&gt;同参数可复现&lt;/td&gt;
&lt;td&gt;工作流＋种子固定后可精确复现每一步&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;ComfyUI 的核心价值是：工作流本身就是可保存、可分享、可复现的资产。&amp;lt;/span&amp;gt;别人发你一张用 ComfyUI 生成的图片，图片里往往就内嵌了完整的工作流信息，直接把图片拖进 ComfyUI 界面，整张流程图原样还原——这是它生态繁荣的根基。&lt;/p&gt;
&lt;p&gt;也正因为流程全透明，ComfyUI 成了新模型、新技术落地最快的平台：SDXL、Flux 等新架构出来后，往往先在 ComfyUI 里跑通；视频生成模型的工作流也大多以 ComfyUI 为载体（本系列后面的 &lt;a href=&quot;/posts/ai-muse-video-prompt/&quot;&gt;AI 视频提示词工作流&lt;/a&gt; 里会再提到它）。&lt;/p&gt;
&lt;h2&gt;安装：便携包最省事，手动装最可控&lt;/h2&gt;
&lt;h3&gt;方式一：官方便携包（Windows 推荐）&lt;/h3&gt;
&lt;p&gt;官方为 Windows 提供免安装便携包，解压即用，自带独立的 Python 环境，不污染系统：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;到项目仓库的 Releases 页面下载 &lt;code&gt;ComfyUI_windows_portable&lt;/code&gt; 压缩包（分 NVIDIA 版与 AMD 版，按显卡选）；&lt;/li&gt;
&lt;li&gt;解压到任意目录（路径尽量不要有中文和空格）；&lt;/li&gt;
&lt;li&gt;双击 &lt;code&gt;run_nvidia_gpu.bat&lt;/code&gt; 启动，浏览器打开 &lt;code&gt;http://127.0.0.1:8188&lt;/code&gt; 就是界面。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;便携包的缺点是环境封闭，后续装自定义节点遇到依赖问题时不如手动安装好排查。新手先用便携包跑通第一张图，完全没问题。&lt;/p&gt;
&lt;h3&gt;方式二：手动安装（Linux / macOS / 想长期折腾的 Windows）&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI

# 先按你的显卡装 PyTorch（NVIDIA 示例，版本以 PyTorch 官网为准）
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu124

# 再装 ComfyUI 自身依赖
pip install -r requirements.txt

# 启动
python main.py
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;常用启动参数：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 允许局域网访问（默认只监听本机）
python main.py --listen 0.0.0.0 --port 8188

# 显存紧张时
python main.py --lowvram

# 指定模型目录（和别的绘图工具共用模型时很有用）
python main.py --extra-model-paths-config extra_model_paths.yaml
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;--listen 0.0.0.0&lt;/code&gt; 会把界面暴露到局域网，而 ComfyUI 本身没有任何登录鉴权。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;千万不要把 8188 端口直接映射到公网&amp;lt;/span&amp;gt;，需要远程使用时走内网穿透加鉴权或 SSH 隧道，别裸奔。
:::&lt;/p&gt;
&lt;h3&gt;显存门槛速览&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;模型架构&lt;/th&gt;
&lt;th&gt;最低显存（能跑）&lt;/th&gt;
&lt;th&gt;舒适显存&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;SD 1.5&lt;/td&gt;
&lt;td&gt;4GB&lt;/td&gt;
&lt;td&gt;6GB&lt;/td&gt;
&lt;td&gt;512×512 起家，分辨率低&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SDXL&lt;/td&gt;
&lt;td&gt;6GB&lt;/td&gt;
&lt;td&gt;8–10GB&lt;/td&gt;
&lt;td&gt;1024×1024 原生，生态最庞大&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Flux.1（fp8 量化）&lt;/td&gt;
&lt;td&gt;8GB&lt;/td&gt;
&lt;td&gt;12GB&lt;/td&gt;
&lt;td&gt;画质强，完整版更吃显存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Flux.1（完整精度）&lt;/td&gt;
&lt;td&gt;16GB&lt;/td&gt;
&lt;td&gt;24GB&lt;/td&gt;
&lt;td&gt;也可走量化路线降低门槛&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;显存不够时还有两条路：一是 &lt;code&gt;--lowvram&lt;/code&gt; 参数把部分计算挪到内存里（慢，但能跑）；二是把模型部署在带 GPU 的服务器或云主机上——Docker 里直通 NVIDIA 显卡的完整方法见本系列的 &lt;a href=&quot;/posts/docker-gpu-nvidia/&quot;&gt;Docker GPU 直通篇&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;界面与核心概念：节点、连线、工作流&lt;/h2&gt;
&lt;p&gt;打开界面你会看到默认加载好的一张工作流。先建立三个概念，后面拆解就顺了：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;节点（Node）&lt;/strong&gt;：一个处理步骤。每个节点左侧是输入口、右侧是输出口，口子按数据类型分颜色——模型、条件（提示词编码结果）、潜空间、图像各有专属类型，类型不对连不上，这是 ComfyUI 防呆的第一道关。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;连线（Link）&lt;/strong&gt;：数据流的方向。从输出口拖到输入口即可连接；按住节点标题可整体拖动，滚轮缩放画布，双击空白处可以搜索并添加新节点。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;工作流（Workflow）&lt;/strong&gt;：整张图的存档。点界面上的 Save 可存为 JSON 文件；把 JSON 文件（或内嵌工作流的 PNG 图片）拖进界面即可完整还原。&lt;code&gt;Ctrl+Enter&lt;/code&gt; 是排队生成的快捷键，点 Queue Prompt 也一样。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;还有一个关键认知：ComfyUI 是「改哪跑哪」的增量执行——你只改了提示词，它只会重跑受影响的下游节点，上游没变的节点直接用缓存。所以调参数试错的成本比想象中低，改个种子重跑采样即可，不用从头再来。&lt;/p&gt;
&lt;p&gt;界面右上角的 Queue 队列面板能看到排队与历史记录；生成的图默认保存在安装目录的 &lt;code&gt;output&lt;/code&gt; 文件夹里，按日期和前缀归档。&lt;/p&gt;
&lt;h2&gt;逐节点拆解：默认文生图工作流&lt;/h2&gt;
&lt;p&gt;默认工作流只有 7 个节点，却完整覆盖了扩散生成的全部环节。逐个讲清，你就掌握了 ComfyUI 的「语法」。&lt;/p&gt;
&lt;h3&gt;1. Load Checkpoint（加载检查点）&lt;/h3&gt;
&lt;p&gt;全图的源头。下拉框里选一个大模型文件，它同时吐出三路输出：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;MODEL&lt;/strong&gt;：扩散模型本体（UNet），负责真正的去噪计算；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CLIP&lt;/strong&gt;：文本编码器，负责把提示词翻译成模型能懂的向量；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;VAE&lt;/strong&gt;：变分自编码器，负责在像素空间与潜空间之间转换。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;模型文件放在安装目录的 &lt;code&gt;models/checkpoints&lt;/code&gt; 文件夹里，放好后刷新页面就能在下拉框里看到。选哪个模型决定了画风上限，选型思路见本系列的 &lt;a href=&quot;/posts/ai-open-models-guide/&quot;&gt;开源模型怎么选&lt;/a&gt;。&lt;/p&gt;
&lt;h3&gt;2. CLIP Text Encode ×2（正、负提示词编码）&lt;/h3&gt;
&lt;p&gt;两个一模一样的节点，一个写正面提示词、一个写负面提示词。它们接收 Load Checkpoint 的 CLIP 输出，把文本编码成 &lt;strong&gt;CONDITIONING（条件）&lt;/strong&gt; 送给采样器：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;正面：描述你想要什么——主体、场景、画风、光线，英文逗号分隔的短语为主；&lt;/li&gt;
&lt;li&gt;负面：描述你不要什么——低质量、变形的手、多余的肢体之类常见缺陷词。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;注意：两个节点用的必须是同一个 CLIP（即同一个大模型配套的编码器），串错了模型会出现语义完全对不上的怪图。&lt;/p&gt;
&lt;h3&gt;3. Empty Latent Image（空白潜空间）&lt;/h3&gt;
&lt;p&gt;生成一张「全噪声的底图」，但它不在像素空间，而在压缩后的潜空间里。这里设三个值：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;width / height&lt;/strong&gt;：出图尺寸。SD 1.5 模型用 512×512，SDXL 用 1024×1024，乱设大尺寸容易出重影和拼贴感；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;batch_size&lt;/strong&gt;：一次并行生成几张，显存够的话调 2–4 一次多抽几张挑。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;4. KSampler（采样器）——全图的心脏&lt;/h3&gt;
&lt;p&gt;它接收 MODEL、正负 CONDITIONING 和空白 LATENT，按参数一步步把噪声「雕刻」成有语义的潜图，再输出给解码环节。它是参数最多、也最值得吃透的一个节点，下一节专门列表讲。&lt;/p&gt;
&lt;h3&gt;5. VAE Decode（VAE 解码）&lt;/h3&gt;
&lt;p&gt;把采样完成的潜图翻译回真正的像素图像。输入是 KSampler 的 LATENT 输出和 Load Checkpoint 的 VAE 输出，一根线的事，没什么可调的。&lt;/p&gt;
&lt;h3&gt;6. Save Image（保存图像）&lt;/h3&gt;
&lt;p&gt;接收解码后的 IMAGE，落盘到 &lt;code&gt;output&lt;/code&gt; 目录，&lt;code&gt;filename_prefix&lt;/code&gt; 控制文件名前缀。它的兄弟节点 Preview Image 只预览不存盘，调试工作流时常用。前面提到的「图片内嵌工作流」就是 Save Image 干的——保存时它把整张图的节点信息写进了 PNG 元数据。&lt;/p&gt;
&lt;p&gt;把七个节点连起来看一遍数据流：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Load Checkpoint ──MODEL──► KSampler ──LATENT──► VAE Decode ──IMAGE──► Save Image
       │                     ▲  ▲                    ▲
       ├─CLIP─► 正面编码 ────┘  │                    │
       ├─CLIP─► 负面编码 ───────┘                    │
       └─VAE─────────────────────────────────────────┘
Empty Latent Image ──LATENT──► KSampler
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;KSampler 参数速查：六个参数各管什么&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;管什么&lt;/th&gt;
&lt;th&gt;常用范围&lt;/th&gt;
&lt;th&gt;调错的症状&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;seed（种子）&lt;/td&gt;
&lt;td&gt;噪声的随机起点，固定它就能复现同一张图&lt;/td&gt;
&lt;td&gt;任意整数，-1 为随机&lt;/td&gt;
&lt;td&gt;每次出图都不一样、无法复现，多半是它没固定&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;steps（步数）&lt;/td&gt;
&lt;td&gt;去噪迭代次数，越多细节越收敛&lt;/td&gt;
&lt;td&gt;20–30（常规采样器）&lt;/td&gt;
&lt;td&gt;太少画面糊、结构没长完；太多纯属浪费时间&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;cfg（提示词相关性）&lt;/td&gt;
&lt;td&gt;模型听提示词话的程度&lt;/td&gt;
&lt;td&gt;5–9（SDXL 常用 5–7）&lt;/td&gt;
&lt;td&gt;太低画面散、跑题；太高颜色烧焦、线条过锐出「油腻感」&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;sampler_name（采样器）&lt;/td&gt;
&lt;td&gt;用哪种算法去噪&lt;/td&gt;
&lt;td&gt;euler、dpmpp_2m、euler_ancestral 等&lt;/td&gt;
&lt;td&gt;没有绝对优劣，换采样器等于换笔触，要配合调度器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;scheduler（调度器）&lt;/td&gt;
&lt;td&gt;每一步噪声衰减的节奏曲线&lt;/td&gt;
&lt;td&gt;normal、karras、sgm_uniform 等&lt;/td&gt;
&lt;td&gt;与采样器不搭会出现细节丢失或噪点残留&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;denoise（重绘幅度）&lt;/td&gt;
&lt;td&gt;保留多少输入潜图、重画多少&lt;/td&gt;
&lt;td&gt;文生图固定 1.0；图生图 0.3–0.8&lt;/td&gt;
&lt;td&gt;文生图不是 1.0 会残留初始噪声，出图发灰&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个实战要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;文生图时 denoise 必须是 1.0&lt;/strong&gt;。它表示「把输入噪声完全重画」，低于 1.0 等于让一部分纯噪声直接进解码，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;出图蒙灰、噪点洗不掉，九成是这个值被误改了&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;steps 不是越多越好&lt;/strong&gt;。常规采样器 20–30 步后收益急剧递减，翻倍步数换不来翻倍画质，只换来翻倍等待。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;cfg 和模型强相关&lt;/strong&gt;。SDXL 系大多在 5–7 舒适，Flux 等新模型甚至只需要 1–3.5 或用专用引导节点，抄参数时先确认对方用的什么模型。&lt;/li&gt;
&lt;li&gt;快速采样器（如 LCM、Turbo 类模型）是例外：它们专为 4–8 步设计，steps 按其说明给，别套常规经验。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;调参顺序建议：先固定种子，定住 sampler 与 scheduler，再调 steps 与 cfg——一次只动一个变量，对比才有意义。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;进阶玩法概览：四条支线&lt;/h2&gt;
&lt;p&gt;默认工作流跑顺之后，常见需求基本落在这四条支线上。它们都不用换软件，只是往图里加节点。&lt;/p&gt;
&lt;h3&gt;图生图（Img2Img）&lt;/h3&gt;
&lt;p&gt;拿一张现成的图当起点重绘。做法：用 Load Image 节点读入图片，经 VAE Encode 转成潜图，替换掉 Empty Latent Image 喂给 KSampler，并把 &lt;strong&gt;denoise 调到 0.3–0.8&lt;/strong&gt;——值越小越像原图，越大改动越狠。风格迁移、草图上色、照片转绘都走这条线。&lt;/p&gt;
&lt;h3&gt;高清修复（Hires Fix）&lt;/h3&gt;
&lt;p&gt;先在低分辨率出图、再放大重绘补细节，避免直接大尺寸出图的重影问题。ComfyUI 里的典型串法是：第一遍 KSampler 出图 → 解码 → 用 Upscale Image（或加载放大模型的 Image Upscale With Model）放大 → 再 VAE Encode 回潜图 → 第二个 KSampler 以 &lt;strong&gt;0.3–0.5 的低 denoise&lt;/strong&gt; 补细节 → 解码保存。也有 Latent Upscale 节点直接在潜空间放大，速度快但细节补充不如像素放大扎实。&lt;/p&gt;
&lt;h3&gt;局部重绘（Inpainting）&lt;/h3&gt;
&lt;p&gt;只改图中的一小块：右键 Load Image 节点选「在遮罩编辑器中打开」，涂出要重绘的区域；把图片经 VAE Encode (for Inpainting) 节点（它多一个 mask 输入和 grow_mask_by 参数）转成带遮罩的潜图，再接 KSampler 并把 denoise 拉到 0.85 以上，提示词只写涂抹区域里想要的内容。换衣服、改表情、去掉路人，都靠它。&lt;/p&gt;
&lt;h3&gt;ControlNet：给构图上缰绳&lt;/h3&gt;
&lt;p&gt;提示词管「画什么」，ControlNet 管「怎么摆」。它通过一张控制图约束生成结果的结构，常见预处理类型：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Canny / Lineart&lt;/strong&gt;：按边缘线稿控制构图；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Depth&lt;/strong&gt;：按深度图控制前后层次；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;OpenPose&lt;/strong&gt;：按骨骼关节点控制人物姿势；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Tile&lt;/strong&gt;：分块放大补细节。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;用法是插入 Load ControlNet Model 与 Apply ControlNet 两个节点，把控制图和正负条件接进去再送入 KSampler。控制图可以手画，也可以用预处理节点从照片自动提取。&lt;/p&gt;
&lt;p&gt;:::warning
这四条支线都会显著增加显存与耗时，尤其是高清修复的第二遍采样和 ControlNet 叠加时。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;显存爆掉（CUDA out of memory）时先降分辨率或关掉 batch，而不是反复重启碰运气。&amp;lt;/span&amp;gt;
:::&lt;/p&gt;
&lt;h2&gt;模型与自定义节点生态：东西去哪下、放哪&lt;/h2&gt;
&lt;h3&gt;模型放对目录，界面才认&lt;/h3&gt;
&lt;p&gt;ComfyUI 按类型分目录管理模型，放错位置等于没装：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;models/
├── checkpoints/    # 大模型（主模型文件）
├── loras/          # LoRA 微调小模型
├── vae/            # 独立 VAE
├── controlnet/     # ControlNet 模型
├── upscale_models/ # 放大模型
├── clip/           # 独立文本编码器
└── unet/           # 独立扩散模型（部分新架构用）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;下载渠道以两个为主：&lt;strong&gt;Hugging Face&lt;/strong&gt;（官方与开源模型的大本营，新模型首发地）和 &lt;strong&gt;Civitai&lt;/strong&gt;（社区微调模型、LoRA 与工作流分享最集中的地方，附带大量示例图和参数）。下载时注意两点：一是看清文件对应架构——SD 1.5 的 LoRA 用不到 SDXL 模型上；二是认准 &lt;code&gt;.safetensors&lt;/code&gt; 格式，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;来路不明的 .ckpt / .pt 文件可能内嵌恶意代码，能选 safetensors 就别用老格式。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;如果和别的绘图工具共用一套模型，不必复制两份：在安装目录建 &lt;code&gt;extra_model_paths.yaml&lt;/code&gt;，把对方的模型根目录登记进去即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;other_ui:
    base_path: D:/stable-diffusion-webui/models/Stable-diffusion
    checkpoints: Stable-diffusion
    loras: Lora
    vae: VAE
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;自定义节点与 ComfyUI-Manager&lt;/h3&gt;
&lt;p&gt;官方节点只覆盖核心流程，大量进阶能力来自社区的&lt;strong&gt;自定义节点&lt;/strong&gt;（Custom Nodes）：放大套件、面部修复、视频生成支持、批量处理工具等等。手动装法是把节点仓库 clone 进 &lt;code&gt;custom_nodes&lt;/code&gt; 目录再装它的依赖，但更推荐先装一个管理器：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd ComfyUI/custom_nodes
git clone https://github.com/ltdrdata/ComfyUI-Manager.git
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重启后界面上会多出 Manager 按钮，点开就能搜索、安装、更新自定义节点，还能一键补装某个工作流缺失的节点——打开别人的工作流时如果一片红色报错节点，先去 Manager 里点「Install Missing Custom Nodes」，八成能自动补齐。&lt;/p&gt;
&lt;p&gt;:::warning
自定义节点本质是在你的机器上运行第三方 Python 代码，装之前先看仓库活跃度与口碑；来路不明的节点包不要装。另外节点更新偶尔会改接口，工作流正用在正事上时，务必先导出 JSON 备份再升级节点和本体。
:::&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：启动时报 &lt;code&gt;CUDA out of memory&lt;/code&gt; 或生成到一半显存爆掉？&lt;/strong&gt;
先降尺寸与 batch_size，再考虑加 &lt;code&gt;--lowvram&lt;/code&gt; 启动参数；同时开着其他占显存的程序（游戏、其他推理服务）也会抢占，先关掉再试。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：下拉框里找不到刚下载的模型？&lt;/strong&gt;
先确认文件放进了正确的子目录（大模型进 &lt;code&gt;checkpoints&lt;/code&gt;，LoRA 进 &lt;code&gt;loras&lt;/code&gt;），再刷新页面；还不行就重启服务。目录对了仍不显示，多半是文件没下完整，对比一下文件大小与发布页标注。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：出图全黑或全紫、糊成一团？&lt;/strong&gt;
按顺序查：模型与 LoRA 架构是否匹配（SD1.5 与 SDXL 混用必翻车）→ VAE 是否串错（某些模型需要配套 VAE，用错会偏色）→ cfg 是否被拉得过高 → denoise 在文生图时是否为 1.0。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：打开别人的工作流，一堆节点标红？&lt;/strong&gt;
是缺自定义节点。用 Manager 的 Install Missing Custom Nodes 补装；补完还红的，可能是节点改名或版本对不上，看工作流来源页的说明确认版本。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：换了提示词，图却没变化？&lt;/strong&gt;
大概率是改错了节点——默认工作流里有两个长得一样的 CLIP Text Encode，一个正一个负；另外注意改完要重新点 Queue Prompt，界面不会自动重跑。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：生成速度突然变慢？&lt;/strong&gt;
查三件事：是否被切到了 CPU 模式（启动日志里会写设备）→ 显存爆了在反复换页（降分辨率验证）→ 尺寸或步数被改大。还有一种是笔记本独显没被调用，确认 PyTorch 装的是 CUDA 版且驱动正常。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：想让别人也能用我的工作流？&lt;/strong&gt;
直接发 Save Image 保存的 PNG 或导出的 JSON 即可，对方拖进界面就还原；记得一并说明用到的模型与自定义节点名称，不然对方打开全是缺模型提示。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;ComfyUI 的门槛只在最初的理解成本：一旦你看懂「加载模型 → 编码提示词 → 采样 → 解码」这条主线，以及 KSampler 那六个参数各自的职责，剩下的图生图、高清修复、局部重绘、ControlNet 都只是在这张图上添节点。建议的练习顺序是：先把默认工作流的种子固定住，逐个参数单变量试一遍效果；再照着本篇把图生图和高清修复各串一遍；最后去下载一个别人分享的工作流，对照着拆——这是进步最快的路子。工作流文件记得随手备份，它就是你的配方本。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：Continue ＋ 本地模型搭私有编程助手</title><link>https://www.anexns.cloudns.org/posts/ai-continue-local-coding/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-continue-local-coding/</guid><description>用 VS Code ＋ Continue 插件 ＋ Ollama 本地模型搭一套完全私有的编程助手：代码不出内网、零订阅费，讲清三类模型的角色分工、config.yaml 逐段配置、四个实测场景与补全调优。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：编程助手好用，但代码发给谁了&lt;/h2&gt;
&lt;p&gt;AI 编程助手已经是日常写代码的标配：行内补全、选中代码问答、让模型直接改文件，效率提升是实打实的。但主流方案有个绕不开的前提——&lt;strong&gt;你的代码要发到别人的服务器上&lt;/strong&gt;。补全时，当前文件和周边上下文会被打包上传；用 @Codebase 问问题时，整个仓库的索引也要过一遍云端。&lt;/p&gt;
&lt;p&gt;对个人开源项目这可能无所谓，但下面几种情况就得掂量了：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;公司内部代码、未发布的产品代码，合规上根本不允许出内网。&lt;/li&gt;
&lt;li&gt;仓库里混着配置文件、脚本、内部接口文档，上传等于把家底摊开。&lt;/li&gt;
&lt;li&gt;订阅按月付费，团队人一多就是一笔长期支出，还随时可能涨价或调整额度。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;好在现在开源模型和本地推理工具都成熟了：&lt;strong&gt;用 Ollama 在自己机器（或内网一台带显卡的机器）上跑模型，再用 Continue 这个开源插件接进 VS Code，就能得到一套代码不出内网、零订阅费的私有编程助手&lt;/strong&gt;。模型选型和 Ollama 部署的通用部分，本系列的 &lt;a href=&quot;/posts/ai-ollama-local-llm/&quot;&gt;Ollama 本地大模型部署&lt;/a&gt; 和 &lt;a href=&quot;/posts/ai-open-models-guide/&quot;&gt;开源模型怎么选&lt;/a&gt; 已经讲过；和云端助手的整体对比，可以先看 &lt;a href=&quot;/posts/ai-coding-assistants/&quot;&gt;AI 编程助手实战&lt;/a&gt;。本篇专注一件事：把 Continue ＋ Ollama 这套组合从零配到能干活，并且把每个配置项讲清楚。&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;架构与角色分工 → Ollama 侧准备三类模型 → Continue 安装 → config.yaml 逐段详解 → 四个场景实测 → 补全与上下文调优 → 局限与取舍&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/continuedev/continue&lt;/p&gt;
&lt;h2&gt;架构：三件套各自干什么&lt;/h2&gt;
&lt;p&gt;这套方案由三个部件组成，先把角色对齐，后面配置才不会乱：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;部件&lt;/th&gt;
&lt;th&gt;角色&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;VS Code&lt;/td&gt;
&lt;td&gt;工作台&lt;/td&gt;
&lt;td&gt;写代码的地方，本身不做推理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Continue 插件&lt;/td&gt;
&lt;td&gt;调度员&lt;/td&gt;
&lt;td&gt;决定每个动作（补全、对话、编辑、索引）调用哪个模型，管理上下文&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Ollama&lt;/td&gt;
&lt;td&gt;推理引擎&lt;/td&gt;
&lt;td&gt;在本机或内网服务器上真正运行模型，对外提供 API&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;关键认知在 Continue 这一层：&lt;strong&gt;它不是「接一个模型」，而是「给每种活分配一个模型」&lt;/strong&gt;。补全要的是快，对话要的是聪明，代码库索引要的是嵌入模型——这三类活对模型的要求完全不同，硬用一个模型全包，结果就是补全慢、索引还建不起来。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Continue 的核心设计就是模型角色分工：chat、autocomplete、embed 各司其职，私有编程助手能不能用，七成取决于这三个角色配得对不对。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;前置：Ollama 侧准备三类模型&lt;/h2&gt;
&lt;p&gt;Ollama 的安装和基础用法见 &lt;a href=&quot;/posts/ai-ollama-local-llm/&quot;&gt;Ollama 本地大模型部署&lt;/a&gt;，这里只讲为编程助手做的针对性准备。&lt;/p&gt;
&lt;h3&gt;三类模型分工&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;角色&lt;/th&gt;
&lt;th&gt;干什么活&lt;/th&gt;
&lt;th&gt;模型要求&lt;/th&gt;
&lt;th&gt;推荐模型&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;chat / edit / apply&lt;/td&gt;
&lt;td&gt;对话问答、按指令改代码、应用编辑结果&lt;/td&gt;
&lt;td&gt;指令跟随好、代码能力强，可以慢&lt;/td&gt;
&lt;td&gt;Qwen2.5-Coder 14B / 32B&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;autocomplete&lt;/td&gt;
&lt;td&gt;行内补全，你打字它接话&lt;/td&gt;
&lt;td&gt;必须快（几百毫秒级）、支持 FIM&lt;/td&gt;
&lt;td&gt;Qwen2.5-Coder 7B、StarCoder2 7B&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;embed&lt;/td&gt;
&lt;td&gt;把代码切块算向量，建代码库索引&lt;/td&gt;
&lt;td&gt;嵌入模型，和聊天模型完全两回事&lt;/td&gt;
&lt;td&gt;nomic-embed-text&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;rerank（可选）&lt;/td&gt;
&lt;td&gt;对检索回来的代码片段重排序&lt;/td&gt;
&lt;td&gt;小个通用模型即可&lt;/td&gt;
&lt;td&gt;Llama 3.1 8B&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一条命令全部拉下来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ollama pull qwen2.5-coder:14b
ollama pull qwen2.5-coder:7b
ollama pull nomic-embed-text
ollama pull llama3.1:8b
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;显存怎么分：14B 对话模型量化后约占 9 GB，7B 补全模型约 5 GB，嵌入和重排模型各 1 GB 上下。一张 24 GB 的卡可以全常驻；16 GB 的卡建议把对话模型降到 14B 以下或者让补全和对话共用调度（用时加载、闲时卸载，代价是首次响应慢几秒）。纯 CPU 也能跑，但补全延迟会到秒级，体验基本不可用——&lt;strong&gt;这套方案的下限是一张 12 GB 以上显存的显卡，或者 Apple Silicon 统一内存 32 GB 起步&lt;/strong&gt;。&lt;/p&gt;
&lt;h3&gt;Ollama 服务端设置&lt;/h3&gt;
&lt;p&gt;如果 Ollama 和 VS Code 在同一台机器上，默认配置就能用（监听 &lt;code&gt;127.0.0.1:11434&lt;/code&gt;）。常见的是把 Ollama 放在内网一台带显卡的机器上，笔记本只装 VS Code，这时要改两个地方。&lt;/p&gt;
&lt;p&gt;Linux 上用 systemd 环境变量覆盖：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl edit ollama
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;填入：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Service]
Environment=&quot;OLLAMA_HOST=0.0.0.0:11434&quot;
Environment=&quot;OLLAMA_KEEP_ALIVE=30m&quot;
Environment=&quot;OLLAMA_NUM_PARALLEL=2&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl restart ollama
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;OLLAMA_HOST&lt;/code&gt;：改成 &lt;code&gt;0.0.0.0&lt;/code&gt; 才允许别的机器连。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;OLLAMA_KEEP_ALIVE&lt;/code&gt;：模型闲置多久后从显存卸载。默认 5 分钟太短，写代码时频繁冷启动很烦，设 30 分钟。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;OLLAMA_NUM_PARALLEL&lt;/code&gt;：允许的并发请求数。Continue 会同时发补全和对话请求，设 2 更顺。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
把 OLLAMA_HOST 开到 0.0.0.0 等于把推理接口暴露在局域网里，Ollama 本身没有鉴权。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把 11434 端口映射到公网&amp;lt;/span&amp;gt;，只在可信内网使用；跨网络访问请走内网穿透或 VPN，不要裸奔端口转发。
:::&lt;/p&gt;
&lt;h2&gt;Continue 安装&lt;/h2&gt;
&lt;p&gt;在 VS Code 扩展市场搜 Continue 安装即可（JetBrains 全家桶也有对应插件，配置完全共用）。装好后左侧栏会出现 Continue 图标。点开面板，点右上角的齿轮（或配置选择器里的「Add Config」/ 打开配置），会定位到配置文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;~/.continue/config.yaml
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Continue 现在的主力配置格式就是这个 YAML 文件（老版本的 config.json 已淘汰）。整个助手的全部行为都由它决定，下面逐段拆。&lt;/p&gt;
&lt;h2&gt;config.yaml 逐段详解&lt;/h2&gt;
&lt;p&gt;先给一份可以直接抄的完整配置，再逐段解释：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;name: Private Coding Assistant
version: 1.0.0
schema: v1

models:
  # —— 对话 / 编辑主力 ——
  - name: Qwen2.5-Coder 14B
    provider: ollama
    model: qwen2.5-coder:14b
    apiBase: http://127.0.0.1:11434
    roles:
      - chat
      - edit
      - apply
    requestOptions:
      timeout: 60000

  # —— 行内补全：小、快、支持 FIM ——
  - name: Qwen2.5-Coder 7B Autocomplete
    provider: ollama
    model: qwen2.5-coder:7b
    apiBase: http://127.0.0.1:11434
    roles:
      - autocomplete
    autocompleteOptions:
      debounceDelay: 500
      maxPromptTokens: 1024

  # —— 代码库索引嵌入 ——
  - name: Nomic Embed Text
    provider: ollama
    model: nomic-embed-text:latest
    apiBase: http://127.0.0.1:11434
    roles:
      - embed
    embedOptions:
      maxChunkSize: 512
      maxBatchSize: 32

  # —— 检索结果重排（可选） ——
  - name: Llama 3.1 8B Rerank
    provider: ollama
    model: llama3.1:8b
    apiBase: http://127.0.0.1:11434
    roles:
      - rerank

context:
  - provider: code
  - provider: codebase
  - provider: docs
  - provider: diff
  - provider: file
  - provider: folder
  - provider: terminal
  - provider: problems
  - provider: search
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;顶层三件套：name / version / schema&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;name&lt;/code&gt; 是这份配置在 Continue 界面里的显示名，随便起。&lt;code&gt;schema: v1&lt;/code&gt; 声明配置格式版本，照抄即可。&lt;code&gt;version&lt;/code&gt; 是你自己给配置编的版本号，方便将来回滚，无实际约束。&lt;/p&gt;
&lt;h3&gt;models：角色分配是核心&lt;/h3&gt;
&lt;p&gt;每个模型条目四要素：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;name&lt;/code&gt;：显示名，界面里切换模型时看到的就是它。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;provider: ollama&lt;/code&gt;：走 Ollama 通道。换成本地其他推理服务（如 LM Studio）时才改这里。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;model&lt;/code&gt;：Ollama 里的模型标签，必须和 &lt;code&gt;ollama list&lt;/code&gt; 里看到的一字不差。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;apiBase&lt;/code&gt;：Ollama 地址。本机跑就写 &lt;code&gt;http://127.0.0.1:11434&lt;/code&gt;；放在内网服务器上就改成那台机器的 IP。&lt;strong&gt;这是唯一需要按你的网络环境改的字段。&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code&gt;roles&lt;/code&gt; 是整份配置的灵魂，六个角色分工如下：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;角色&lt;/th&gt;
&lt;th&gt;触发时机&lt;/th&gt;
&lt;th&gt;配错的后果&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;chat&lt;/td&gt;
&lt;td&gt;侧边栏对话、问答&lt;/td&gt;
&lt;td&gt;用小模型答，质量明显不行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;edit&lt;/td&gt;
&lt;td&gt;选中代码按 Ctrl+I 给指令改写&lt;/td&gt;
&lt;td&gt;同上&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;apply&lt;/td&gt;
&lt;td&gt;把模型给出的代码块真正写进文件&lt;/td&gt;
&lt;td&gt;用慢模型点一次等半天；一般和 chat 用同一个&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;autocomplete&lt;/td&gt;
&lt;td&gt;打字时的灰色行内补全&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;误配成大模型是最常见的翻车点&amp;lt;/span&amp;gt;，延迟直接爆炸&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;embed&lt;/td&gt;
&lt;td&gt;给代码库建向量索引&lt;/td&gt;
&lt;td&gt;不配则 @Codebase 完全不可用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;rerank&lt;/td&gt;
&lt;td&gt;对索引检索结果重排序&lt;/td&gt;
&lt;td&gt;不配也能用，只是 @Codebase 答得糙一点&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;注意 apply 角色：Continue 在对话里生成代码后，点「Apply」把改动落到文件这一步是单独走一个模型的，因为它要做的是把完整文件内容和代码块做合并，要求快且稳，通常直接和 chat 共用同一个模型即可，不必单列。&lt;/p&gt;
&lt;p&gt;两个可选参数值得单独说：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;requestOptions.timeout&lt;/code&gt;：毫秒。对话用大模型生成长回答时，默认超时容易误杀，14B 级别设 60000 比较稳。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;autocompleteOptions&lt;/code&gt;：补全专属。&lt;code&gt;debounceDelay&lt;/code&gt; 是你停手多少毫秒后才发请求，太小会狂发请求、太大跟不上手速，400–600 是甜点区。&lt;code&gt;maxPromptTokens&lt;/code&gt; 限制补全时带多少上下文，1024 兼顾速度和相关性。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;embedOptions.maxChunkSize&lt;/code&gt;：索引切块大小。代码文件按 512 切比较均衡；文档型仓库可以放大到 1024。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;context：上下文提供者&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;context&lt;/code&gt; 段决定你在对话里打 &lt;code&gt;@&lt;/code&gt; 时能引用哪些东西：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;code&lt;/code&gt;：引用当前文件里某个函数/类（按符号选）。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;codebase&lt;/code&gt;：全仓库语义检索，就是靠 embed 模型建的索引在干活。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;docs&lt;/code&gt;：引用官方文档站（Continue 内置了一批常用文档源）。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;diff&lt;/code&gt;：把当前 Git 改动喂给模型，写提交说明、做自查 review 都靠它。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;file&lt;/code&gt; / &lt;code&gt;folder&lt;/code&gt;：指定文件或整个文件夹作为上下文。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;terminal&lt;/code&gt;：把终端最近输出带进来，报错排查时极其好用。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;problems&lt;/code&gt;：编辑器里标红的报错列表。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;search&lt;/code&gt;：在代码库里做文本搜索。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这段不用背，用到哪个 @ 不出来，再回来查这张单子往里加即可。&lt;/p&gt;
&lt;h2&gt;实测四场景&lt;/h2&gt;
&lt;p&gt;配置写好后，在 Continue 面板顶部的配置选择器里切到这份「Private Coding Assistant」，逐个场景验收。&lt;/p&gt;
&lt;h3&gt;场景一：行内补全&lt;/h3&gt;
&lt;p&gt;新建一个 Python 文件，写下函数签名和注释：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;def retry(func, times=3, delay=1.0):
    &quot;&quot;&quot;调用 func，失败后重试，间隔逐次翻倍&quot;&quot;&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;回车后稍等，应该能看到灰色的补全建议（循环、异常捕获、sleep 翻倍那一整段），按 Tab 接受。验收标准：&lt;strong&gt;从停手到出现建议应在 1 秒上下&lt;/strong&gt;。明显更慢，先去排障小节看补全延迟部分。&lt;/p&gt;
&lt;h3&gt;场景二：选中代码问答&lt;/h3&gt;
&lt;p&gt;选中一段自己看不太懂的正则或算法，按 Ctrl+L 把它送进对话，问「这段在干什么，边界情况有哪些」。模型应该结合这段代码本身回答，而不是泛泛而谈。这验证的是 chat 角色和上下文传递都通了。&lt;/p&gt;
&lt;h3&gt;场景三：整文件编辑&lt;/h3&gt;
&lt;p&gt;打开一个函数，Ctrl+I 输入「给这个函数加上参数校验，非法参数抛 ValueError」。Continue 会以 diff 形式给出改动，逐块接受或拒绝。这一步同时验证 edit 和 apply 两个角色——能生成 diff 说明 edit 通了，能干净地落进文件说明 apply 通了。&lt;/p&gt;
&lt;h3&gt;场景四：代码库问答 @Codebase&lt;/h3&gt;
&lt;p&gt;第一次使用先让它建索引：打开 Continue 设置里的索引状态，确认进度走完（大仓库要几分钟）。然后在对话里输入：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;@Codebase 这个项目的配置是从哪里加载的？给出文件路径
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;回答里应该引用到具体文件和代码片段，而不是编造。答得离谱，先查 embed 模型有没有配对、索引有没有建完，再考虑 rerank。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;四个场景全过，这套私有助手就算搭成了：补全管手速、对话管理解、编辑管落地、Codebase 管全局。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;调优：补全延迟与上下文长度&lt;/h2&gt;
&lt;h3&gt;补全为什么必须用 FIM 模型&lt;/h3&gt;
&lt;p&gt;行内补全的本质是「已知光标前后的代码，填中间的空」。支持 FIM（Fill-in-the-Middle）的模型在训练时专门学过这种「给前缀＋后缀、补中间」的格式，补出来的代码能和后文严丝合缝；普通对话模型只能顺着前缀往下编，经常把后面已有的代码再重复一遍。&lt;/p&gt;
&lt;p&gt;选补全模型时认准这一点：Qwen2.5-Coder、StarCoder2、DeepSeek-Coder 这几个系列都支持 FIM。&lt;strong&gt;不要拿通用对话模型（比如纯 Llama 聊天版）顶补全的班&lt;/strong&gt;，那是补全质量差的头号原因，排障时先查这里。&lt;/p&gt;
&lt;h3&gt;延迟从哪来，怎么压&lt;/h3&gt;
&lt;p&gt;补全的体感延迟由三段组成：防抖等待（debounceDelay，你设的）、网络往返（内网可忽略）、模型生成（大头）。压延迟的顺序：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;补全模型换小：7B 是甜点，显存富裕也别超过 14B，补全要的是 token 吐得快。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;maxPromptTokens&lt;/code&gt; 别贪大：从 2048 降到 1024，相关性损失很小，速度提升明显。&lt;/li&gt;
&lt;li&gt;让补全模型常驻显存：&lt;code&gt;OLLAMA_KEEP_ALIVE&lt;/code&gt; 设长一点，避免每次补全先花几秒加载模型。&lt;/li&gt;
&lt;li&gt;对话和补全抢显存时，优先保补全：把对话模型降一档（32B → 14B）比让补全排队划算得多。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;上下文长度：别被默认值坑了&lt;/h3&gt;
&lt;p&gt;Ollama 默认给模型的上下文窗口只有 2048 token，对聊天勉强够，对编程场景远远不够：一个中等长度的文件就爆了，模型会「忘掉」文件开头，@Codebase 的回答也跟着残缺。两个办法：&lt;/p&gt;
&lt;p&gt;办法一，给 Ollama 设全局上下文长度（较新版本的 Ollama 支持）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Environment=&quot;OLLAMA_CONTEXT_LENGTH=16384&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;办法二，用 Modelfile 派生一个大上下文版本，适合只想给对话模型扩窗的场景：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;FROM qwen2.5-coder:14b
PARAMETER num_ctx 32768
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;ollama create qwen-coder-32k -f Modelfile
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后把 config.yaml 里对话模型的 &lt;code&gt;model&lt;/code&gt; 改成 &lt;code&gt;qwen-coder-32k&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;:::warning
上下文不是越大越好：窗口翻倍，显存里的 KV 缓存也跟着涨，生成速度还会变慢。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;无脑拉满到 128K 是最常见的过度调优&amp;lt;/span&amp;gt;，对话模型 16K–32K、补全 4K–8K 对绝大多数仓库已经够用。
:::&lt;/p&gt;
&lt;h2&gt;局限与取舍：什么活别交给它&lt;/h2&gt;
&lt;p&gt;把预期摆正，这套方案才用得久。和云端旗舰编程助手比，本地小模型的差距主要在三处：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;复杂重构&lt;/strong&gt;：跨多文件的大改、需要长链推理的架构调整，14B 级别模型容易改着改着丢约束，产出需要逐行审。云端旗舰在这类活上确实更强。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;冷门技术栈&lt;/strong&gt;：训练语料少的框架、公司内部自研库，本地模型基本靠猜；@Codebase 能补一部分上下文，但补不了它没见过的 API。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;长上下文项目理解&lt;/strong&gt;：几十万行的大仓，索引检索只能捞回片段，拼不出全局图景，别指望它做架构级问答。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;适合放心交给它的活：样板代码、单测生成、正则与脚本、代码解释、报错定位、格式转换、补类型标注、写注释和文档字符串——也就是日常写代码里最耗时但最不需要「聪明」的那 70%。&lt;/p&gt;
&lt;p&gt;取舍原则一句话：&lt;strong&gt;隐私敏感、重复枯燥的活留在本地；真正烧脑、且代码允许外发的活，临时切回云端模型&lt;/strong&gt;。Continue 支持在同一份配置里混排本地和云端模型，按场景手动切换，这正是它的好处——不用二选一站队。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;h3&gt;补全迟迟不出现，或慢到 3 秒以上&lt;/h3&gt;
&lt;p&gt;按这个顺序查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;补全角色是不是误配了大模型或对话模型（roles 里 autocomplete 挂的必须是小个 FIM 模型）。&lt;/li&gt;
&lt;li&gt;在跑 Ollama 的机器上执行 &lt;code&gt;ollama ps&lt;/code&gt;，确认补全模型在显存里常驻，而不是每次请求现加载。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;nvidia-smi&lt;/code&gt; 看显存：如果对话模型把显存占满，补全模型被挤到内存里跑，延迟直接翻十倍。降对话模型一档，或给 Ollama 限制对话模型的常驻。&lt;/li&gt;
&lt;li&gt;跨机器部署时测一下内网延迟，Wi-Fi 抖动也会让补全忽快忽慢，有条件走有线。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;Continue 面板报错，连不上 Ollama&lt;/h3&gt;
&lt;p&gt;先在 VS Code 所在机器上自测接口：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl http://127.0.0.1:11434/api/tags
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;本机都通不了：Ollama 没在跑，或端口不对，先修服务端。&lt;/li&gt;
&lt;li&gt;本机通、Continue 里不通：多半是 &lt;code&gt;apiBase&lt;/code&gt; 写错（IP、端口、漏了 &lt;code&gt;http://&lt;/code&gt;）。&lt;/li&gt;
&lt;li&gt;Ollama 在另一台机器上：确认服务端设了 &lt;code&gt;OLLAMA_HOST=0.0.0.0:11434&lt;/code&gt; 并重启过服务，且防火墙放行了 11434。注意 &amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;apiBase 还写着 127.0.0.1 是跨机器部署时最常见的低级错误&amp;lt;/span&amp;gt;——127.0.0.1 永远指你自己这台机器。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;@Codebase 回答不引用任何文件，像在编&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;查索引状态：Continue 里看代码库索引是否建完，中途失败会静默降级成「无索引问答」。&lt;/li&gt;
&lt;li&gt;查 embed 角色：config.yaml 里有没有模型挂了 embed 角色，模型名和 &lt;code&gt;ollama list&lt;/code&gt; 对不对得上。嵌入模型没配对时不报错、只是不用，这是最阴的一种故障。&lt;/li&gt;
&lt;li&gt;仓库刚大改过结构：手动触发一次重新索引，旧索引里的路径全是过期的。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;补全建议驴唇不对马嘴，重复已有代码&lt;/h3&gt;
&lt;p&gt;典型的「补全模型不支持 FIM」症状：它在顺着前缀续写，而不是填空。把 autocomplete 换成 Qwen2.5-Coder、StarCoder2 这类明确支持 FIM 的模型；同时检查 &lt;code&gt;maxPromptTokens&lt;/code&gt; 是否被设得过小（比如 256），上下文喂太少，模型只能瞎猜。&lt;/p&gt;
&lt;h3&gt;改完 config.yaml 不生效&lt;/h3&gt;
&lt;p&gt;config.yaml 是热加载的，保存后一般几秒内生效。如果改了没反应：确认改的是当前选中的那份配置（Continue 支持多份配置并存，界面顶部能切换）；再确认 YAML 缩进没错位——&lt;strong&gt;YAML 对缩进极其敏感，一个空格错位就会整段失效且不报错&lt;/strong&gt;，拿不准时把文件贴进任意 YAML 校验工具先验一遍。&lt;/p&gt;
&lt;h3&gt;中文注释和中文提问回答质量差&lt;/h3&gt;
&lt;p&gt;对话模型换中文友好的系列：Qwen 系列对中文的理解明显好于同尺寸的 Llama 系。如果主力是英文代码＋中文交流，Qwen2.5-Coder 兼顾得最好，这也是上面配置拿它当主力的原因。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;私有编程助手的价值就两条：&lt;strong&gt;代码不出内网，订阅费归零&lt;/strong&gt;，代价是复杂任务上和云端旗舰有真实差距，心里要有数。&lt;/li&gt;
&lt;li&gt;搭这套东西的关键不在装，而在 Continue 的角色分工：对话用大模型、补全用小的 FIM 模型、索引用嵌入模型，三者别串位。&lt;/li&gt;
&lt;li&gt;config.yaml 里真正要按自己环境改的只有 &lt;code&gt;apiBase&lt;/code&gt; 和模型尺寸，其余照抄就能跑通四个基本场景。&lt;/li&gt;
&lt;li&gt;调优先压补全延迟，再扩对话上下文；窗口别贪大，够用即止。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;跑通之后，如果想把本地模型再往前推一步——比如给整个团队共用一台推理服务器、或者把模型接到更多工具里——可以接着看本系列的进阶篇。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：creator-generalist 让 AI 助手变身 2D/3D 创作通才</title><link>https://www.anexns.cloudns.org/posts/ai-creator-generalist/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-creator-generalist/</guid><description>creator-generalist 是给 AI 编程助手安装的 2D/3D/游戏创作技能包：三大主技能加一整套工艺与工具技能，沿八步生产主线把一句话需求做成带 QA 的短片、讲解图和小游戏原型。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：AI 助手会写代码，却不会「做片子」&lt;/h2&gt;
&lt;p&gt;让 AI 编程助手写个脚本、改个 Bug，它很在行；可你要是说「给我做一条 60 秒的 3D 剖面动画短片」，它多半只会泛泛而谈。缺的不是智商，是&lt;strong&gt;手艺和流程&lt;/strong&gt;：建模用什么工具、动画按什么原则、资产从哪找、做完怎么检查质量——这些行当里的 know-how，它没装进脑子里。&lt;/p&gt;
&lt;p&gt;creator-generalist 干的就是这件事：它是一套给 AI 助手安装的创作技能包，装一次，助手就像多了一个小型创作工作室——能建模、能绑定、能做动画、能剪讲解图、能拼游戏原型，而且每一步都有现成的工艺规范和质检关口兜底。本篇把它的三大主技能、配套工艺技能、共同的八步生产主线和三种安装方式一次讲透。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/codepawl/creator-generalist&lt;/p&gt;
&lt;h2&gt;它是什么：一套技能包，五个插件&lt;/h2&gt;
&lt;p&gt;先说清定位：creator-generalist 不是一个独立软件，而是一组 &lt;strong&gt;Agent Skills（智能体技能）&lt;/strong&gt;，以插件形式分发。它兼容主流的 AI 编程助手：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Claude Code&lt;/li&gt;
&lt;li&gt;Codex&lt;/li&gt;
&lt;li&gt;Cursor&lt;/li&gt;
&lt;li&gt;Gemini CLI&lt;/li&gt;
&lt;li&gt;OpenCode&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;装好之后，你不需要记技能名字再去点名调用——直接说要做的活，匹配的技能会自动加载；也可以用快捷口令 &lt;code&gt;/3dg&lt;/code&gt;、&lt;code&gt;/2dg&lt;/code&gt;、&lt;code&gt;/gameg&lt;/code&gt; 分别唤起 3D、2D 和游戏三条线。它主打的产出场景，是给 YouTube、TikTok、Facebook、Instagram、X 做内容、视频和 Shorts。&lt;/p&gt;
&lt;p&gt;还有一个很实用的交互设计：&lt;strong&gt;动手之前，助手会先问几个简短的问题&lt;/strong&gt;，把你需求里没说清的地方（用途、平台、格式、风格）逐个确认，而且每个问题都附一个建议答案，你点头就行；然后它会先给一个低成本预览，确认方向对了才往下做。这套「先对齐、再生产」的节奏，是它和「一句话直接开渲」最大的区别。&lt;/p&gt;
&lt;h2&gt;三大主技能：一个助手，三间工作室&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;主技能&lt;/th&gt;
&lt;th&gt;口令&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;th&gt;主要工具与产出&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;3d-generalist&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/3dg&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;3D 短片、剖面演示、故事场景、世界搭建、绑定角色、主视觉资产&lt;/td&gt;
&lt;td&gt;在 Blender、Three.js 里脚本化建模与动画，素材优先用 CC0 / CC BY 真实扫描资源，过 QA 关口才给预览&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2d-generalist&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/2dg&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Vox 风讲解图：扁平纸卡、印刷边框的真实照片、荧光笔标注、地图、图表、真比例时间线&lt;/td&gt;
&lt;td&gt;全部用免费工具制作，撕纸、网点、颗粒这类风格化效果只作可选&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;game-generalist&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/gameg&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;可玩的游戏原型、小型原创游戏、Game Jam 参赛作品、给现成可玩版本做手感与 QA&lt;/td&gt;
&lt;td&gt;先交可试玩的灰盒，再锁定美术风格；支持 Web（Three.js、Phaser、Canvas）、Godot、Unity、Unreal&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;3d-generalist：五种模式&lt;/h3&gt;
&lt;p&gt;3D 这条线内置五种模式，覆盖了短视频里最常见的 3D 需求：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;cutaway&lt;/code&gt;（剖面）：约 60 秒的透视剖面 Short，一个简单物件经过 5 到 7 轮「出问题 → 修好」的推进，最后翻转加压力测试收尾。示例口令：&lt;code&gt;/3dg cutaway how a hole in the ground becomes a flushing toilet&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;story&lt;/code&gt;（故事）：角色驱动的短片，拼搭场景、透视墙、面部表情、错落的肢体时序和滑稽节拍。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;world&lt;/code&gt;（世界）：某个地点与时代的环境或微缩景观，带扫描的 PBR 地面、草、水、火和活动的小生命。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;character&lt;/code&gt;（角色）：带绑定的角色，动画片段可重定向，脚能踩实台阶和斜坡，手臂用双骨 IK。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;asset&lt;/code&gt;（资产）：主视觉模型、拼搭道具或按照片对齐的 PBR 材质，导出 GLB 并附一份 &lt;code&gt;CREDITS.md&lt;/code&gt; 记录素材出处。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;game-generalist：先玩起来，再谈好看&lt;/h3&gt;
&lt;p&gt;游戏这条线的顺序很清醒：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;先交付一个能玩的灰盒让你上手试，美术风格在那之后才锁定&amp;lt;/span&amp;gt;。更特别的是它的试玩 QA：由脚本机器人自动跑一遍，产出试玩报告——报错、胜利与失败路径、重开、确定性、帧耗时、软锁（卡死）全都查，最后附一个可玩链接和一段 30 到 60 秒的录屏。对独立做小游戏的人来说，这一关省掉的是大量枯燥的人肉回归测试。&lt;/p&gt;
&lt;h2&gt;工艺与工具技能：主技能背后的手艺库&lt;/h2&gt;
&lt;p&gt;三大主技能负责统筹，每个制作环节则由专门的工艺技能和工具技能执行，也可以单独点名使用：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;技能&lt;/th&gt;
&lt;th&gt;负责环节&lt;/th&gt;
&lt;th&gt;内容要点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;model-characters&lt;/td&gt;
&lt;td&gt;3D 角色建模&lt;/td&gt;
&lt;td&gt;低多边形（PS1、N64、Q 版、动漫、吉祥物）、风格化雕刻、干净基础网格、写实人类四条路线，带参考测量与网格检查&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;sculpt-models&lt;/td&gt;
&lt;td&gt;雕刻&lt;/td&gt;
&lt;td&gt;形体层级与解剖、按尺度分层的表面处理、岩石与地形断裂逻辑、Blender 雕刻工具、重拓扑与烘焙&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;animate-characters&lt;/td&gt;
&lt;td&gt;2D/3D 动画&lt;/td&gt;
&lt;td&gt;动画十二原则在两种媒介的落地、时序与间距、曲线编辑、行走与待机循环、表演节拍、逐帧（Krita、Grease Pencil）与剪纸动画&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;rig-characters&lt;/td&gt;
&lt;td&gt;绑定&lt;/td&gt;
&lt;td&gt;骨骼命名、Rigify、权重、带极向的 IK、IK/FK 吸附切换、面部与机械绑定、2D 剪纸绑定，导出 Unity、Godot、glTF&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;draw-and-paint-art&lt;/td&gt;
&lt;td&gt;绘画&lt;/td&gt;
&lt;td&gt;动态与结构、解剖与透视缩短、光影与形体、灰度上色，兼作 3D 的三视图设定图&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;paint-stylized-backgrounds&lt;/td&gt;
&lt;td&gt;背景&lt;/td&gt;
&lt;td&gt;Blender 渲染设置、3D 搭景加绘景、笔刷、时段变体、视差、风、水与粒子&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;use-3d-software&lt;/td&gt;
&lt;td&gt;3D 工具操作&lt;/td&gt;
&lt;td&gt;约 250 条 Blender 配方（按新版命名）、Three.js 加载与色彩流程、Godot / Unity / Unreal 指南、GLB 与 FBX 导出规则&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;edit-video&lt;/td&gt;
&lt;td&gt;剪辑&lt;/td&gt;
&lt;td&gt;Shorts 与 YouTube 的剪辑手艺（钩子、节奏、卡点、字幕、安全区、响度、平台导出）、DaVinci Resolve 特效与调色、FFmpeg 配方&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;watch-video&lt;/td&gt;
&lt;td&gt;看片学样&lt;/td&gt;
&lt;td&gt;抽帧表、剪辑点、频谱与声音时间线、多语种转写、复刻配方；还能把教程频道沉淀成技能&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;design-sound&lt;/td&gt;
&lt;td&gt;声音设计&lt;/td&gt;
&lt;td&gt;按语义检索的音效库（CLAP）、拟音生成、按事件表摆放音效音轨、配乐贴合剪辑、混音到平台响度并查同步与手机可听度&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这套分工的意义在于：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;主技能管流程，工艺技能管手艺，工具技能管软件操作&amp;lt;/span&amp;gt;——助手在每一步调用的都是对应环节的专门知识，而不是靠通用常识硬凑。&lt;/p&gt;
&lt;h2&gt;共同的八步生产主线&lt;/h2&gt;
&lt;p&gt;2D 和 3D 两位「通才」共用同一条八步生产主线，游戏线也遵循同样的先对齐后生产逻辑：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;简报&lt;/strong&gt;：确认时长、平台、比例、语言等基本盘。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;参考&lt;/strong&gt;：找参考图与参考片，定方向。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;脚本与节拍&lt;/strong&gt;：把内容拆成镜头和节拍。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;备料与风格定样门&lt;/strong&gt;：先做风格样张，A/B/C 几版让你挑，挑定才继续——这是整条线的关键关口。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;资产&lt;/strong&gt;：准备模型、贴图、照片等全部素材。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;构建与动画&lt;/strong&gt;：正式制作，期间先交第一个完成镜头的半成品演示给你看。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;声音&lt;/strong&gt;：配乐、音效、混音。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;QA 与交付&lt;/strong&gt;：先给 540p 预览，你选下一步（按意见改、按你指的方向继续、或者放手让助手自己创作），&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;全质量渲染只在你批准之后才开始&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::warning
这条主线意味着它不是「一句话等成品」的玩具：中途有提问、有风格定样、有预览确认。赶时间想要一次到位的人要有心理准备——但换来的好处是成品方向可控，不容易整条片子做完才发现风格不对。
:::&lt;/p&gt;
&lt;h2&gt;防「一眼 AI 味」的三套机制&lt;/h2&gt;
&lt;p&gt;AI 生成内容最容易露馅的地方，是塑料感的模型、滑动的脚步和所有关节同一帧停住的僵硬感。这个技能包专门针对性地做了三件事：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;真实资产优先&lt;/strong&gt;：动手拼基本几何体之前，先去 Poly Haven、ambientCG、Sketchfab、BlenderKit、Quaternius 等来源找 CC0 和 CC BY 的真实扫描模型与贴图，每个物件按真实顶点边界贴合。质感的地基是真实数据，不是凭空捏。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;表演时序错开&lt;/strong&gt;：转头时头部领先躯干 4 到 6 帧，各个关节错开 3 到 6 帧停住，身体永远不在同一帧冻住；每个失败动作都有预备和反应节拍。再加上跟随角色的柔和补光、主体景深和 180 度快门运动模糊，画面就有了「拍出来」的感觉。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;机器 QA 兜底&lt;/strong&gt;：交付预览前有自动检查——接触与滑动检查脚本逐帧测 30fps 下的瞬移、速度、腾空、脚步打滑和接触间隙；外观对比脚本把渲染结果和已批准的风格样张逐项比对。检查不过，先修再给你看。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;同系列里，&lt;a href=&quot;/posts/ai-muse-animated-film/&quot;&gt;AI 动画短片全流程技能&lt;/a&gt;走的是关键帧加生成式视频的路线，&lt;a href=&quot;/posts/ai-muse-video-skill/&quot;&gt;虚拟剧组前期策划引擎&lt;/a&gt;专注剧本分镜等前期策划；而 creator-generalist 的路线是&lt;strong&gt;用 Blender、Three.js 这类传统工具脚本化生产&lt;/strong&gt;，三者正好互补：策划、生成、传统制作各管一段。&lt;/p&gt;
&lt;h2&gt;安装：三条路线&lt;/h2&gt;
&lt;h3&gt;路线一：让 Agent 自己装（最省事）&lt;/h3&gt;
&lt;p&gt;把下面这段话粘贴进 Claude Code、Codex、Cursor、Gemini CLI 或 OpenCode，助手会自己装好技能、检查 Blender、FFmpeg、Node.js、Python 是否就位，缺软件时会先问过你再装：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Install the creator-generalist skill pack and set up its tools. Read
https://raw.githubusercontent.com/codepawl/creator-generalist/main/INSTALL.md and follow every step.
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;路线二：Claude Code 插件市场&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;/plugin marketplace add codepawl/creator-generalist
/plugin install 3d-generalist@creator-generalist
/plugin install 2d-generalist@creator-generalist
/plugin install game-generalist@creator-generalist
/plugin install watch-video@creator-generalist
/plugin install design-sound@creator-generalist
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;五个插件全装才是完整技能集；其中 2d-generalist 自带一份生产主线，所以 2D、3D 两个插件单独装也能各自独立工作。&lt;/p&gt;
&lt;h3&gt;路线三：skills 命令行（任意 Agent）&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;npx skills add codepawl/creator-generalist
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;也可以纯手动安装：把仓库 &lt;code&gt;plugins/&lt;/code&gt; 下各技能文件夹复制进你所用 Agent 的 skills 目录（如 &lt;code&gt;~/.claude/skills/&lt;/code&gt;、&lt;code&gt;~/.cursor/skills/&lt;/code&gt;、&lt;code&gt;~/.gemini/skills/&lt;/code&gt; 等），Gemini CLI 和 OpenCode 还需按仓库说明补一份口令命令文件。&lt;/p&gt;
&lt;p&gt;:::warning
安装时注意两点：一是让 Agent 代装时，它会检查并可能提议安装 Blender、FFmpeg 等本地软件，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;装任何软件前都应由你确认，不要无脑放行&amp;lt;/span&amp;gt;；二是技能里引用的第三方素材遵循 CC0 / CC BY 许可，商用发布时记得按 &lt;code&gt;CREDITS.md&lt;/code&gt; 的记录保留署名。
:::&lt;/p&gt;
&lt;h2&gt;适合谁&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;短视频创作者&lt;/strong&gt;：想给 YouTube、TikTok 做剖面动画、故事短片、讲解图，又请不起专业团队的人。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;讲解类内容作者&lt;/strong&gt;：Vox 风的地图、时间线、数据图，靠 2d-generalist 一条线就能成系列产出。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;独立游戏爱好者&lt;/strong&gt;：想快速验证玩法点子，game-generalist 的灰盒加自动试玩 QA 能把「想法到能玩」压缩到一轮对话。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;已经在用 AI 编程助手的人&lt;/strong&gt;：无论你手头是 Claude Code 还是 Gemini CLI，装上就是增量，不用换工具链。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;如果你的需求是照片级写实渲染或长片电影级制作，这套以短片和 Shorts 为目标的技能包不是对的工具；绘图方向的节点式工作流可以看同系列的 &lt;a href=&quot;/posts/ai-comfyui-beginner/&quot;&gt;ComfyUI 入门&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：装完之后，助手没有自动用上这些技能？&lt;/strong&gt;
先确认技能文件夹放进了正确的目录，且五个插件都已安装。用口令强制唤起验证：输入 &lt;code&gt;/3dg&lt;/code&gt; 应能列出五种模式；若口令无反应，多半是插件没启用或目录放错，回到路线二逐个重装。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：Gemini CLI / OpenCode 里 &lt;code&gt;/3dg&lt;/code&gt; 口令不生效？&lt;/strong&gt;
这两个平台需要额外一步：按仓库说明把 &lt;code&gt;harness/&lt;/code&gt; 里对应的命令文件复制到命令目录（Gemini CLI 是 &lt;code&gt;~/.gemini/commands/&lt;/code&gt;，OpenCode 是 &lt;code&gt;~/.config/opencode/commands/&lt;/code&gt;）。漏了这一步时技能本身在，直接描述需求也能触发，只是没有快捷口令。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：生成到一半报缺工具或渲染失败？&lt;/strong&gt;
这套技能依赖本地的 Blender、FFmpeg、Node.js、Python。让助手重新走一遍环境检查（路线一的安装提示词会做这件事），缺哪个补哪个；&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要跳过 QA 直接要终稿&amp;lt;/span&amp;gt;，很多渲染异常正是接触检查和外观对比这两关要拦的。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：产出看着还是有 AI 味怎么办？&lt;/strong&gt;
先回到流程找原因：是不是跳过了风格定样门、参考阶段没给足参考、或者资产阶段没用上真实扫描素材。用预览环节的「按意见改」给出具体修改点（如「脚步打滑」「转头太僵」），助手会针对性调整时序与资产，而不是整片重做。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：能不能只装其中一个插件？&lt;/strong&gt;
可以。3D 和 2D 两个插件都能独立工作，watch-video 和 design-sound 本身就是独立插件。只做讲解图的人完全可以只装 2d-generalist，先跑通一条线再扩。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：做出来的东西能商用吗？&lt;/strong&gt;
技能包本身是 MIT 许可；但产出里用到的第三方素材是 CC0 / CC BY，CC BY 部分需要署名。发布前检查每个项目自带的 &lt;code&gt;CREDITS.md&lt;/code&gt;，按记录保留出处即可。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;creator-generalist 的思路，是把「创作工作室的组织方式」打包成技能装给 AI 助手：三大主技能分管 3D、2D 和游戏，十来个工艺与工具技能提供每个环节的手艺，两条通才线共用八步生产主线，靠风格定样门、540p 预览和机器 QA 把质量关口前置。它不承诺一句话出大片，但能把一个会写代码的助手，变成一个能按流程交活的创作通才。对于想用 AI 做短视频、讲解内容和小游戏原型的人，这是目前完成度很高的一套现成方案。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：Dify 工作流应用搭建</title><link>https://www.anexns.cloudns.org/posts/ai-dify-workflow/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-dify-workflow/</guid><description>用 Docker Compose 自托管 Dify：部署与初始化、接入云端与本地 Ollama 模型、四种应用形态对比，再手把手搭一个「长文章转摘要＋要点＋标题」的工作流并发布成 API。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：会聊天，不等于能干活&lt;/h2&gt;
&lt;p&gt;聊天框式的 AI 用法有个天花板：每次都要手动粘贴内容、重复交代要求、再把结果复制出来。真正能省时间的用法，是把「输入 → 处理步骤 → 输出格式」固定下来，做成一个可以反复调用的小应用：文章丢进去，摘要出来；工单丢进去，分类和回复草稿出来。这类「把提示词变成流水线」的活，正是 Dify 的主场。&lt;/p&gt;
&lt;p&gt;Dify 是一个开源的 LLM 应用开发平台，可以自托管。它把几件通常要分别搭的东西打包在了一起：&lt;strong&gt;可视化工作流编排、知识库（RAG）、Agent、模型供应商管理、应用发布（网页端＋API）&lt;/strong&gt;。你在画布上拖节点连线，背后就是一次真实的程序执行；搭好的应用既能生成一个可分享的网页，也能拿到 API Key 被自己的脚本和系统调用。&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;Docker Compose 自托管部署 Dify → 初始化管理员 → 接入云端 API 与本地 Ollama 两种模型 → 搞清四种应用形态 → 完整搭一个「长文章 → 摘要＋要点＋标题」工作流 → 发布成网页和 API → 资源占用与备份要点&lt;/strong&gt;。本地模型与知识库的原理细节，本系列另有 &lt;a href=&quot;/posts/ai-ollama-local-llm/&quot;&gt;Ollama 部署本地大模型&lt;/a&gt; 与 &lt;a href=&quot;/posts/ai-rag-knowledge-base/&quot;&gt;RAG 个人知识库&lt;/a&gt; 两篇，本篇只讲在 Dify 里怎么用，不重复展开。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/langgenius/dify&lt;/p&gt;
&lt;h2&gt;部署：Docker Compose 一把梭&lt;/h2&gt;
&lt;p&gt;Dify 官方只推荐 Docker Compose 部署。先看一眼它到底会拉起多少东西，心里有数再动手：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;组件&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;api&lt;/td&gt;
&lt;td&gt;后端 API 服务&lt;/td&gt;
&lt;td&gt;业务逻辑核心&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;worker / worker_beat&lt;/td&gt;
&lt;td&gt;异步任务与定时任务&lt;/td&gt;
&lt;td&gt;文档解析、索引构建都在这里跑&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;web&lt;/td&gt;
&lt;td&gt;前端控制台&lt;/td&gt;
&lt;td&gt;浏览器里操作的那个界面&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;db&lt;/td&gt;
&lt;td&gt;PostgreSQL&lt;/td&gt;
&lt;td&gt;存应用、对话、配置&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;redis&lt;/td&gt;
&lt;td&gt;缓存与队列&lt;/td&gt;
&lt;td&gt;任务队列依赖&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;weaviate&lt;/td&gt;
&lt;td&gt;默认向量数据库&lt;/td&gt;
&lt;td&gt;知识库索引，可换 Qdrant、Milvus 等&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;sandbox&lt;/td&gt;
&lt;td&gt;代码节点沙箱&lt;/td&gt;
&lt;td&gt;跑工作流里的代码节点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;plugin_daemon&lt;/td&gt;
&lt;td&gt;插件守护进程&lt;/td&gt;
&lt;td&gt;模型与工具以插件形式接入&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ssrf_proxy&lt;/td&gt;
&lt;td&gt;出站请求防护&lt;/td&gt;
&lt;td&gt;HTTP 请求节点经它出网&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;nginx&lt;/td&gt;
&lt;td&gt;统一入口反代&lt;/td&gt;
&lt;td&gt;对外只暴露它&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;部署命令（服务器上执行，目录位置按自己习惯）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git clone https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;.env&lt;/code&gt; 里第一次部署真正需要留意的就几项，其余保持默认：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 对外端口（被占用就改这两个）
EXPOSE_NGINX_PORT=80
EXPOSE_NGINX_SSL_PORT=443

# 数据库密码，默认是弱口令，务必改掉
DB_PASSWORD=换成你自己的强密码

# 向量库类型，默认 weaviate，想换在这里改
VECTOR_STORE=weaviate

# 文件存储，默认本地磁盘
STORAGE_TYPE=opendal
OPENDAL_SCHEME=fs
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动后等一两分钟，容器陆续 healthy，再访问 &lt;code&gt;http://你的服务器地址/install&lt;/code&gt; 进入初始化页面，设置管理员邮箱和密码。登录后看到的控制台首页，就是后面所有工作的起点。&lt;/p&gt;
&lt;p&gt;:::warning
初始化页面在建好管理员之前是无鉴权的，谁先打开谁就是管理员。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;部署完成后第一件事就是立刻完成初始化，不要把 /install 页面在公网上晾着。&amp;lt;/span&amp;gt;另外 Dify 这一套容器不少，官方口径的最低配置是 2 核 4GB 内存，小于这个规格跑文档解析时很容易被 OOM 打断。
:::&lt;/p&gt;
&lt;h2&gt;接入模型：云端与本地两条线&lt;/h2&gt;
&lt;p&gt;Dify 本身不带模型智能，所有生成能力都来自你接入的模型供应商。在右上角头像菜单进入「设置 → 模型供应商」，按插件方式安装并配置。两条路线：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;云端 API&lt;/strong&gt;：装 OpenAI、Anthropic、DeepSeek、通义千问等对应插件，填 API Key 即可。适合效果优先、按量付费的场景。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;本地 Ollama&lt;/strong&gt;：装 Ollama 插件，添加模型时把 API 基础地址指向你的 Ollama 服务。这里有个经典坑：Dify 在容器里，Ollama 在宿主机上时，地址不能写 &lt;code&gt;localhost&lt;/code&gt;，要写宿主机在 Docker 网络里的地址：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;模型类型：LLM
模型名称：qwen3:8b            ← 与 ollama list 里显示的名字一字不差
API 基础地址：http://host.docker.internal:11434
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果 Ollama 是另一台机器，就填那台机器的内网地址和端口。填完在供应商页面能看到模型状态变绿，再去「系统模型设置」里把默认推理模型、嵌入模型各指定一个，后面建应用时就不用每次重选。嵌入模型如果要做知识库，必须配一个（如 &lt;code&gt;bge-m3&lt;/code&gt; 或云端 embedding 接口），只配聊天模型是不够的。&lt;/p&gt;
&lt;p&gt;两种供应商可以同时存在、按应用切换：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;工作流里每个 LLM 节点都能独立选模型，完全可以让摘要节点用云端大模型、分类节点用本地小模型，把钱花在刀刃上。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;建应用之前：四种形态先选对&lt;/h2&gt;
&lt;p&gt;Dify 创建应用时要先选形态，选错了后面全是别扭。四种主要形态对比：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;形态&lt;/th&gt;
&lt;th&gt;交互方式&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;聊天助手&lt;/td&gt;
&lt;td&gt;多轮对话&lt;/td&gt;
&lt;td&gt;客服问答、带知识库的问答机器人&lt;/td&gt;
&lt;td&gt;内置对话记忆，可挂知识库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文本生成&lt;/td&gt;
&lt;td&gt;一次输入一次输出&lt;/td&gt;
&lt;td&gt;摘要、改写、批量文案&lt;/td&gt;
&lt;td&gt;表单式输入，跑完出结果&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;工作流&lt;/td&gt;
&lt;td&gt;一次运行、节点流水线&lt;/td&gt;
&lt;td&gt;结构化处理、多步骤加工、对外供 API&lt;/td&gt;
&lt;td&gt;无对话，输入变量 → 输出变量，最适合自动化&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Agent&lt;/td&gt;
&lt;td&gt;自主调用工具的多轮对话&lt;/td&gt;
&lt;td&gt;需要查资料、调接口的复杂问答&lt;/td&gt;
&lt;td&gt;模型自己决定调用哪些工具&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;还有一种「对话流（Chatflow）」是工作流的对话版，每轮对话触发一次流程编排，属于进阶玩法，先知道有它即可。本篇实战选&lt;strong&gt;工作流&lt;/strong&gt;：输入输出都结构化，跑完还能直接当 API 用，是四种里最「程序员友好」的形态。&lt;/p&gt;
&lt;h2&gt;实战：长文章 → 摘要＋要点＋标题&lt;/h2&gt;
&lt;p&gt;需求很具体：给一段长文章（比如一篇博客草稿或一篇新闻稿），自动产出三样东西——&lt;strong&gt;一句话摘要、3–5 条要点、一个标题&lt;/strong&gt;，并拼成固定格式输出。下面逐节点搭。&lt;/p&gt;
&lt;p&gt;在工作室点「创建应用 → 工作流」，命名为「文章摘要助手」。画布上默认已有一个开始节点。&lt;/p&gt;
&lt;h3&gt;节点 1：开始——定义输入&lt;/h3&gt;
&lt;p&gt;点开开始节点，添加一个输入字段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;变量名：article
类型：段落（长文本）
标签：文章正文
必填：是
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再加一个可选字段 &lt;code&gt;style&lt;/code&gt;（短文本，选填），用来控制标题风格，比如填「严肃」或「活泼」，不填就走默认。开始节点的作用就是声明这条流水线的入参，后面所有节点都只能引用这里定义过的变量——这也是工作流比聊天框可靠的原因：输入契约是写死的。&lt;/p&gt;
&lt;h3&gt;节点 2：LLM——干活的核心&lt;/h3&gt;
&lt;p&gt;从节点面板拖一个 LLM 节点连到开始节点后面，配置三处：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;模型&lt;/strong&gt;：选一个中文能力好的模型。摘要这类任务对推理要求不高，云端的中杯模型或本地 8B 级别模型都够用。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;系统提示词&lt;/strong&gt;：把输出结构钉死，这是全篇最重要的一段文字：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;你是一个中文编辑助手。阅读用户给出的文章，严格按以下结构输出，不要输出任何多余的解释：


用一句话概括全文，不超过 60 字。


提炼 3 到 5 条核心要点，每条一行，以「- 」开头。


给出一个标题，不超过 24 字。标题风格：{{#开始节点.style#}}
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;用户提示词&lt;/strong&gt;：只放文章变量本身，形如 &lt;code&gt;{{#开始节点.article#}}&lt;/code&gt;（在编辑器里通过变量选择器插入，不要手打，节点 ID 对不上会直接报错）。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
结构化输出最容易翻车的地方，是模型在正文前后加「好的，以下是摘要：」这类客套话。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;提示词里必须明确写「不要输出任何多余的解释」，并且先在调试里跑两三篇不同长度的文章验证格式稳定性，再往下接节点。&amp;lt;/span&amp;gt;格式不稳，后面的模板拼装全会跟着乱。
:::&lt;/p&gt;
&lt;h3&gt;节点 3：模板转换——拼装成品&lt;/h3&gt;
&lt;p&gt;LLM 的输出是一整段带标记的文本，很多时候直接用就够了。但如果要给下游系统消费，或者想换个排版，就加一个「模板转换」节点，用 Jinja2 模板把上游变量拼成最终成品：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 文章速览

{{ arg1}}

---
由文章摘要助手自动生成
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;模板节点里把 &lt;code&gt;arg1&lt;/code&gt; 绑定为 LLM 节点的输出文本即可。模板转换不消耗任何模型调用，纯字符串处理，适合做加页眉页脚、拼 Markdown、组装 JSON 前的文本整形这类活。&lt;/p&gt;
&lt;h3&gt;节点 4：直接回复——交付结果&lt;/h3&gt;
&lt;p&gt;最后拖一个「直接回复」节点（部分版本里叫「结束/Answer」），内容引用模板转换节点的输出变量。工作流跑到这里，就把这段文本作为最终结果返回。&lt;/p&gt;
&lt;h3&gt;跑通与调试&lt;/h3&gt;
&lt;p&gt;点右上角「运行」，在测试面板粘贴一篇文章全文，点执行。画布上每个节点会依次亮起，点任意节点能看到它的实际输入与输出——这是 Dify 调试体验最好的地方：哪一步格式跑偏，一眼定位。常见调整就两类：摘要太长，回 LLM 节点把字数上限写得更硬；要点数量不稳，在提示词里把「3 到 5 条」改成固定「4 条」。&lt;/p&gt;
&lt;p&gt;如果这个摘要结果还要喂给别的系统（比如自动发到笔记软件），把「直接回复」换成或追加一个「HTTP 请求」节点即可：方法选 POST，URL 填目标接口，Body 选 JSON 并引用上游输出变量。工作流的终点是回复还是请求，取决于结果给谁看。&lt;/p&gt;
&lt;h2&gt;知识库：点到为止&lt;/h2&gt;
&lt;p&gt;如果你的应用需要「照着我的文档回答」，就用知识库：控制台「知识库 → 创建」，上传文档后 Dify 会自动完成分段、向量化、建索引，应用里加一个「知识检索」节点（或在聊天助手里直接挂载知识库）就能引用。&lt;/p&gt;
&lt;p&gt;本篇只提醒两个关键点：第一，索引质量取决于分段，文档先清洗再上传，扫描版 PDF 先转成文本，别指望它替你 OCR 出奇迹；第二，嵌入模型一旦选定，中途换模型等于全量重建索引，动手前想清楚。原理、切分策略与召回调参，本系列的 &lt;a href=&quot;/posts/ai-rag-knowledge-base/&quot;&gt;RAG 个人知识库&lt;/a&gt; 一篇专门讲透，这里不展开。&lt;/p&gt;
&lt;p&gt;另外提一句定位问题：如果只是想要一个带知识库的聊天网页，不需要工作流编排，&lt;a href=&quot;/posts/selfhost-open-webui/&quot;&gt;Open WebUI&lt;/a&gt; 那类工具更轻；Dify 的价值在于「流程＋发布」，别为喝牛奶养一头牛。&lt;/p&gt;
&lt;h2&gt;发布：网页与 API 两种入口&lt;/h2&gt;
&lt;p&gt;调试通过后点「发布」，应用立刻有两个入口：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;WebApp&lt;/strong&gt;：发布页给出一个独立网址，任何人打开就能用（可设置访问密码或仅限成员）。适合把摘要助手这类小工具直接分享给同事。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;API&lt;/strong&gt;：在应用的「访问 API」页生成 API Key，用标准 HTTP 调用工作流：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -X POST &apos;http://你的服务器地址/v1/workflows/run&apos; \
  -H &apos;Authorization: Bearer app-替换成你的APIKey&apos; \
  -H &apos;Content-Type: application/json&apos; \
  -d &apos;{
    &quot;inputs&quot;: {
      &quot;article&quot;: &quot;把文章全文放在这里……&quot;,
      &quot;style&quot;: &quot;严肃&quot;
    },
    &quot;response_mode&quot;: &quot;blocking&quot;,
    &quot;user&quot;: &quot;my-script&quot;
  }&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;response_mode&lt;/code&gt; 用 &lt;code&gt;blocking&lt;/code&gt; 是等跑完一次性返回结果，脚本里最好处理；&lt;code&gt;streaming&lt;/code&gt; 则是流式返回中间事件。返回 JSON 里 &lt;code&gt;data.outputs&lt;/code&gt; 就是直接回复节点的内容。至此，这个摘要流水线就从「网页上的小玩具」变成了任何脚本、定时任务、其他服务都能调用的能力。&lt;/p&gt;
&lt;p&gt;:::warning
API Key 等同于这个应用的调用凭证，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把带 Key 的调用代码提交到公开仓库，也不要给公网应用关闭访问控制裸奔。&amp;lt;/span&amp;gt;自托管实例如果只在内网用，建议连同控制台一起放在反向代理加认证之后，或干脆不映射公网端口。
:::&lt;/p&gt;
&lt;h2&gt;资源占用与备份&lt;/h2&gt;
&lt;p&gt;资源方面有个心理预期：全套容器空载时内存占用大约 2–3GB，其中 PostgreSQL、向量库和 api/worker 是大头；跑文档解析和批量索引时 CPU 会阶段性拉满。2 核 4GB 是能跑的下限，长期用建议 4 核 8GB 起步。磁盘增长主要来自三处：上传的知识库文件、向量索引、对话日志，定期看一眼 &lt;code&gt;docker system df&lt;/code&gt; 和数据卷大小。&lt;/p&gt;
&lt;p&gt;备份要抓三样，缺一不可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 数据库（应用、提示词、对话全在这里）
docker compose exec db pg_dump -U postgres dify &amp;gt; dify-db-$(date +%F).sql

# 2. 文件存储卷（上传文件、知识库源文件、生成结果）
docker compose stop api worker
tar -czf dify-storage-$(date +%F).tar.gz -C /var/lib/docker/volumes/docker_app-storage/_data . 
docker compose start api worker

# 3. 配置本身
cp .env docker-compose.yaml ~/dify-config-backup/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;记住一句话：Dify 里最值钱的不是容器，而是数据库加存储卷这两份数据，备份策略围着它们转就对了。&amp;lt;/span&amp;gt;升级 Dify 时先备份再 &lt;code&gt;git pull&lt;/code&gt; 拉新镜像重建，官方升级路径一直是这个套路；跨大版本升级前先看一眼 release notes 里的迁移说明。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;容器都起来了，但打开页面白屏或 502。&lt;/strong&gt; 先看 nginx 和 api 的日志：&lt;code&gt;docker compose logs -f nginx api&lt;/code&gt;。多半是 api 还没完成数据库迁移就对外服务，等一两分钟再刷新；若 api 日志里报数据库连接失败，回头检查 &lt;code&gt;.env&lt;/code&gt; 里 &lt;code&gt;DB_PASSWORD&lt;/code&gt; 是否与 db 容器初始化时用的密码一致——改密码要在首次启动前改，库已经初始化后再改 &lt;code&gt;.env&lt;/code&gt; 是对不上的。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;模型供应商里加 Ollama 一直报连接失败。&lt;/strong&gt; 按顺序查：Ollama 那边是否监听在 &lt;code&gt;0.0.0.0:11434&lt;/code&gt;（默认只听本机回环，服务化部署要设 &lt;code&gt;OLLAMA_HOST&lt;/code&gt;）；Dify 容器里能否解析并连通你填的地址，本机部署优先用 &lt;code&gt;host.docker.internal&lt;/code&gt;（Linux 上需在 compose 里给 api/worker 补 &lt;code&gt;extra_hosts: [&quot;host.docker.internal:host-gateway&quot;]&lt;/code&gt;，官方 compose 已内置，改过网络配置的要自查）；最后才是模型名拼写，名字必须与 &lt;code&gt;ollama list&lt;/code&gt; 输出一字不差。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;工作流运行时在 LLM 节点报错或超时。&lt;/strong&gt; 先单独在供应商页面测试这个模型通不通，再看输入长度：长文章很容易顶爆模型的上下文窗口，表现就是报错或输出截断。解法是换长上下文模型、或在 LLM 节点前加一个代码/模板节点先做截断。另外云端 API 的速率限制也会以超时形式出现，批量跑时把并发降下来。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;模板转换节点输出为空或变量没替换。&lt;/strong&gt; 九成是变量绑定问题：模板里的 &lt;code&gt;arg1&lt;/code&gt;、&lt;code&gt;arg2&lt;/code&gt; 必须在节点配置区逐个绑定到上游节点的输出，绑定后模板里用 &lt;code&gt;{{ arg1 }}&lt;/code&gt; 引用；如果直接在模板里写工作流变量语法，版本不同语法不同，容易 silently 输出空字符串。改完先用「运行」里的单步调试确认本节点输出，再往下查。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;知识库上传文档一直卡在索引中。&lt;/strong&gt; 索引任务由 worker 执行，先看 &lt;code&gt;docker compose logs -f worker&lt;/code&gt; 有没有报错：嵌入模型没配或连不上是最常见原因；大文件解析吃内存被 OOM kill 也常见，加内存或拆小文件。向量库容器异常时整个索引链会一起卡住，&lt;code&gt;docker compose ps&lt;/code&gt; 先把不健康的容器找出来。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;发布成 WebApp 后别人打不开。&lt;/strong&gt; 检查 &lt;code&gt;.env&lt;/code&gt; 里的几个 URL 配置（&lt;code&gt;CONSOLE_API_URL&lt;/code&gt;、&lt;code&gt;SERVICE_API_URL&lt;/code&gt;、&lt;code&gt;APP_WEB_URL&lt;/code&gt;）：同机部署通常留空走相对路径没问题，但一旦你改过域名或加了 HTTPS 反代，这几处不改对，页面能开、接口全挂。改完 &lt;code&gt;.env&lt;/code&gt; 要 &lt;code&gt;docker compose up -d&lt;/code&gt; 重建容器才生效，只 restart 不读新环境变量。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Dify 的定位是「把提示词变成可交付的应用」：工作流负责把处理步骤钉死，知识库负责给模型喂私有资料，发布环节负责把能力交出去。本篇走完了一条完整链路——自托管部署、云端与本地双模型接入、四种形态的取舍、一个能真跑起来的摘要工作流、API 发布与备份。照着这个骨架，把 LLM 节点换成翻译、分类、信息抽取，开始节点换成你的业务输入，就是一个个新应用。这也是本系列后面几篇会反复用到的基本功：先把流程拆对，模型只是其中一个节点。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：LiteLLM 把模型包装成统一 API</title><link>https://www.anexns.cloudns.org/posts/ai-litellm-gateway/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-litellm-gateway/</guid><description>用 LiteLLM Proxy 把云端 API 与本地 Ollama 模型统一成一个 OpenAI 兼容接口：Docker 部署、config.yaml 别名映射、虚拟密钥与预算限额、负载均衡与成本统计的完整实战。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：模型一多，接口先乱&lt;/h2&gt;
&lt;p&gt;刚开始用 AI 接口时，事情很简单：一个供应商、一个 API Key、一段代码。乱象是从第二个模型开始的。OpenAI 一套请求格式，Anthropic 一套，本地 Ollama 又一套；每接一家，代码里就多一个分支、多一处密钥、多一种报错格式。等到想统计「这个月到底在模型上花了多少钱」、想给某个脚本单独限额、想在主供应商挂掉时自动切备用时，直连模式就彻底管不住了——这些能力散落在每个客户端里，谁也拼不出一张全图。&lt;/p&gt;
&lt;p&gt;这一篇的主线，就是在所有客户端和所有模型之间加一层网关：&lt;strong&gt;LiteLLM Proxy&lt;/strong&gt;。它把云端各家的 API 和本地 Ollama 模型全部包装成同一个 OpenAI 兼容接口，对外只暴露一个地址、一套密钥体系、一份日志。客户端从此只认网关，换供应商、加模型、调限额都变成改网关配置，而不是改一圈代码。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/BerriAI/litellm&lt;/p&gt;
&lt;h2&gt;LiteLLM 的两种形态：SDK 与 Proxy&lt;/h2&gt;
&lt;p&gt;LiteLLM 有两种用法，先分清再选：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;形态&lt;/th&gt;
&lt;th&gt;是什么&lt;/th&gt;
&lt;th&gt;适合谁&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Python SDK&lt;/td&gt;
&lt;td&gt;一个 Python 库，在代码里 &lt;code&gt;from litellm import completion&lt;/code&gt;，用统一参数调用各家模型&lt;/td&gt;
&lt;td&gt;单个 Python 项目内部想抹平供应商差异，不需要独立服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Proxy Server&lt;/td&gt;
&lt;td&gt;独立运行的网关服务，对外提供 OpenAI 兼容的 HTTP 接口，自带密钥、限额、日志&lt;/td&gt;
&lt;td&gt;多个工具、多个设备、多个人共用一套模型资源，本篇主讲这种&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;两者的关系是：Proxy 内部用的就是 SDK 的转换能力，只是外面多套了一层服务化的壳——鉴权、虚拟密钥、消费统计、Admin 管理界面都在这一层。本篇默认你已经有至少两个模型来源（比如一家云端 API 加一个本地 Ollama，Ollama 的部署见 &lt;a href=&quot;/posts/ai-ollama-local-llm/&quot;&gt;Ollama 部署本地大模型&lt;/a&gt;），目标是把它们收成一个入口。&lt;/p&gt;
&lt;h2&gt;Docker 部署 Proxy&lt;/h2&gt;
&lt;p&gt;官方提供现成镜像，一条命令就能起。先准备一个目录放配置和环境变量：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/litellm &amp;amp;&amp;amp; cd ~/litellm
cat &amp;gt; .env &amp;lt;&amp;lt; &apos;EOF&apos;
LITELLM_MASTER_KEY=sk-master-换成你自己的随机长串
OPENAI_API_KEY=sk-你的OpenAI密钥
ANTHROPIC_API_KEY=sk-ant-你的Anthropic密钥
EOF
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;用 Docker Compose 把它固化下来，后面改配置、看日志都方便：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    container_name: litellm
    restart: unless-stopped
    ports:
      - &quot;4000:4000&quot;
    env_file:
      - .env
    volumes:
      - ./config.yaml:/app/config.yaml
    command:
      - &quot;--config&quot;
      - &quot;/app/config.yaml&quot;
      - &quot;--port&quot;
      - &quot;4000&quot;
    extra_hosts:
      - &quot;host.docker.internal:host-gateway&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里有三个细节值得注意：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;LITELLM_MASTER_KEY&lt;/code&gt; 是网关的主密钥，相当于管理员密码，后面生成虚拟密钥、调管理接口都靠它，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;它一旦泄露，等于所有上游供应商的密钥一起泄露&amp;lt;/span&amp;gt;，务必用随机长串并保管好。&lt;/li&gt;
&lt;li&gt;上游各家的真实密钥只写在 &lt;code&gt;.env&lt;/code&gt; 里，配置文件通过环境变量引用（下一节会看到），这样 &lt;code&gt;config.yaml&lt;/code&gt; 可以放心进 Git 仓库、发给别人看，密钥不跟着走。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;extra_hosts&lt;/code&gt; 那行是给容器访问宿主机上的 Ollama 用的，本地模型走 &lt;code&gt;host.docker.internal&lt;/code&gt; 这个地址，Linux 上没有这行会连不上。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code&gt;config.yaml&lt;/code&gt; 先写个最小版（下一节逐段拆），然后启动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose logs -f litellm   # 看到 Uvicorn running on http://0.0.0.0:4000 即起来了
curl http://localhost:4000/health/liveliness
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回 &lt;code&gt;I&apos;m alive!&lt;/code&gt; 说明服务活着。浏览器打开 &lt;code&gt;http://localhost:4000/ui&lt;/code&gt;，用主密钥登录，就是 Admin 管理界面，模型列表、密钥、消费记录都能在这里看。&lt;/p&gt;
&lt;p&gt;:::warning
4000 端口只建议监听在本机或内网。LiteLLM 的接口虽然有密钥鉴权，但 &amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不要把没套 HTTPS、没加访问控制的网关端口直接暴露到公网&amp;lt;/span&amp;gt;——它背后连着的全是你付费的密钥，被人扫到就是替别人买单。
:::&lt;/p&gt;
&lt;h2&gt;config.yaml 逐段详解：统一命名与别名映射&lt;/h2&gt;
&lt;p&gt;这是整篇的核心。LiteLLM 的配置哲学只有一句话：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;客户端看到的模型名，和上游真实的模型名，彻底解耦。&amp;lt;/span&amp;gt;客户端只认你在 &lt;code&gt;model_name&lt;/code&gt; 里起的别名，至于这个别名背后是 OpenAI 还是本地 Ollama、以后要换成谁，都在网关这一层悄悄改。&lt;/p&gt;
&lt;p&gt;一份把云端与本地模型统一收编的完整配置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;model_list:
  # —— 云端 API ——
  - model_name: fast-chat
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

  - model_name: strong-chat
    litellm_params:
      model: anthropic/claude-sonnet-4-5
      api_key: os.environ/ANTHROPIC_API_KEY

  # —— 本地 Ollama（选模型的思路见系列前篇）——
  - model_name: local-chat
    litellm_params:
      model: ollama_chat/qwen2.5:14b
      api_base: http://host.docker.internal:11434

  # —— 同名多后端：两个条目共用一个别名，组成负载均衡池 ——
  - model_name: smart
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
  - model_name: smart
    litellm_params:
      model: anthropic/claude-sonnet-4-5
      api_key: os.environ/ANTHROPIC_API_KEY

router_settings:
  routing_strategy: simple-shuffle   # 池内随机分发；也可 least-busy、latency-based
  num_retries: 2                     # 单个后端失败时自动重试
  timeout: 120                       # 单次请求超时（秒）

litellm_settings:
  drop_params: true                  # 自动丢弃目标模型不支持的参数，减少 400 报错
  fallbacks:
    - smart: [&quot;local-chat&quot;]          # smart 池整体不可用时，自动落到本地模型

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐段看关键点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;model_name&lt;/code&gt;&lt;/strong&gt;：对外别名，客户端请求里填的就是它。起名建议按用途而不是按供应商，比如 &lt;code&gt;fast-chat&lt;/code&gt;、&lt;code&gt;strong-chat&lt;/code&gt;、&lt;code&gt;local-chat&lt;/code&gt;——哪天把 &lt;code&gt;strong-chat&lt;/code&gt; 背后的供应商换掉，客户端一行都不用动。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;litellm_params.model&lt;/code&gt;&lt;/strong&gt;：上游真实模型，格式是 &lt;code&gt;供应商/模型名&lt;/code&gt;。云端写 &lt;code&gt;openai/...&lt;/code&gt;、&lt;code&gt;anthropic/...&lt;/code&gt;；本地 Ollama 写 &lt;code&gt;ollama_chat/模型名&lt;/code&gt; 并配 &lt;code&gt;api_base&lt;/code&gt; 指向 Ollama 地址（用 &lt;code&gt;ollama_chat&lt;/code&gt; 而不是 &lt;code&gt;ollama&lt;/code&gt;，是因为前者走 Ollama 的对话接口、工具调用等行为更贴近 OpenAI 格式）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;api_key: os.environ/XXX&lt;/code&gt;&lt;/strong&gt;：这个前缀是固定写法，表示从环境变量读，避免把密钥明文写进配置文件。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;同名条目&lt;/strong&gt;：&lt;code&gt;model_name&lt;/code&gt; 相同的多个条目自动组成一个池，请求按 &lt;code&gt;routing_strategy&lt;/code&gt; 分发，某个后端报错还会按 &lt;code&gt;num_retries&lt;/code&gt; 换一个重试——这是下一节负载均衡与故障转移的基础，这里先把池建好。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;fallbacks&lt;/code&gt;&lt;/strong&gt;：池级别的兜底。上面这条的意思是：&lt;code&gt;smart&lt;/code&gt; 池里的后端全军覆没时，请求自动改走 &lt;code&gt;local-chat&lt;/code&gt;。本地模型能力弱一截，但胜在不会欠费、不会被限流，做降级兜底正合适。本地模型怎么选才够用，见 &lt;a href=&quot;/posts/ai-open-models-guide/&quot;&gt;开源模型怎么选&lt;/a&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;改完配置执行 &lt;code&gt;docker compose restart litellm&lt;/code&gt; 生效，再调一下模型列表接口确认别名都注册上了：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl http://localhost:4000/v1/models \
  -H &quot;Authorization: Bearer sk-master-换成你自己的随机长串&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回里能看到 &lt;code&gt;fast-chat&lt;/code&gt;、&lt;code&gt;strong-chat&lt;/code&gt;、&lt;code&gt;local-chat&lt;/code&gt;、&lt;code&gt;smart&lt;/code&gt; 四个别名，就可以进入下一步了。&lt;/p&gt;
&lt;h2&gt;客户端接入：只改两个地方&lt;/h2&gt;
&lt;p&gt;网关建好之后，任何支持 OpenAI 格式的客户端都只需要改两个参数：&lt;code&gt;base_url&lt;/code&gt; 指向网关，&lt;code&gt;api_key&lt;/code&gt; 换成网关的密钥。先用 curl 验一发：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl http://localhost:4000/v1/chat/completions \
  -H &quot;Authorization: Bearer sk-master-换成你自己的随机长串&quot; \
  -H &quot;Content-Type: application/json&quot; \
  -d &apos;{
    &quot;model&quot;: &quot;local-chat&quot;,
    &quot;messages&quot;: [{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;用一句话介绍你自己&quot;}]
  }&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意这里请求的是本地模型，但走的是标准 OpenAI 格式——把 &lt;code&gt;model&lt;/code&gt; 换成 &lt;code&gt;strong-chat&lt;/code&gt; 再发一次，同一段请求代码就调到了 Anthropic 的模型，这就是统一接口的实际体感。Python 里用官方 SDK 也一样，只是把客户端初始化改两行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;from openai import OpenAI

client = OpenAI(
    base_url=&quot;http://localhost:4000/v1&quot;,   # 原来是各家供应商的地址
    api_key=&quot;sk-给这个项目单独生成的虚拟密钥&quot;,  # 原来是供应商的真实密钥
)

resp = client.chat.completions.create(
    model=&quot;smart&quot;,                          # 填网关别名，不填供应商模型名
    messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;写一个快速排序&quot;}],
)
print(resp.choices[0].message.content)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;其余代码——消息结构、流式处理、错误处理——全部不用动。这意味着存量项目迁移到网关的成本约等于改一次配置；也意味着&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;以后再换供应商、加模型，改的都是网关配置，而不是散落在各个项目里的代码。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;进阶能力：密钥、限额、均衡、日志、缓存&lt;/h2&gt;
&lt;h3&gt;虚拟密钥与预算限额&lt;/h3&gt;
&lt;p&gt;主密钥只该握在自己手里。给每个项目、每个人发的应该是虚拟密钥（Virtual Key）：能限定可用模型、能设预算上限、能单独吊销。用主密钥调管理接口生成：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -X POST http://localhost:4000/key/generate \
  -H &quot;Authorization: Bearer sk-master-换成你自己的随机长串&quot; \
  -H &quot;Content-Type: application/json&quot; \
  -d &apos;{
    &quot;key_alias&quot;: &quot;my-script&quot;,
    &quot;models&quot;: [&quot;fast-chat&quot;, &quot;local-chat&quot;],
    &quot;max_budget&quot;: 5,
    &quot;duration&quot;: &quot;30d&quot;
  }&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回的 &lt;code&gt;key&lt;/code&gt; 就是给那个脚本用的密钥：它只能调 &lt;code&gt;fast-chat&lt;/code&gt; 和 &lt;code&gt;local-chat&lt;/code&gt;，30 天内最多花 5 美元，超了自动拒绝，想停用随时在 Admin 界面或用 &lt;code&gt;/key/delete&lt;/code&gt; 吊销，而上游的真实密钥它从头到尾没见过。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把主密钥直接写进脚本或客户端分发出去，是使用网关最常见的翻车姿势&amp;lt;/span&amp;gt;——主密钥能生成任意新密钥、能看全部消费记录，只能留在网关管理员手里。&lt;/p&gt;
&lt;h3&gt;负载均衡与故障转移&lt;/h3&gt;
&lt;p&gt;上一节配置里已经埋了两层：同名别名组成池做负载均衡，&lt;code&gt;fallbacks&lt;/code&gt; 做跨池故障转移。实际效果是：同一家供应商有多个账号 Key 时，写成多个同名条目即可把请求摊开，撞限流的概率大幅下降；某个后端连续失败，路由会自动避开并重试其他后端，客户端只会感觉「偶尔慢一点」，不会直接吃报错。再进一步，还可以给池内条目加 &lt;code&gt;weight&lt;/code&gt; 按比例分发，或把 &lt;code&gt;routing_strategy&lt;/code&gt; 换成 &lt;code&gt;latency-based-routing&lt;/code&gt; 让请求优先走响应最快的后端。&lt;/p&gt;
&lt;h3&gt;请求日志与成本统计&lt;/h3&gt;
&lt;p&gt;网关的另一大价值是账算得清。每次请求经过网关，都会记录调用方密钥、模型、Token 数和折算成本。想让这些记录在重启后不丢失，需要给网关接一个 PostgreSQL 存消费数据，在 Compose 里加两行环境变量即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    environment:
      - DATABASE_URL=postgresql://user:password@db:5432/litellm
      - STORE_MODEL_IN_DB=True
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;（数据库服务本身的部署不是本篇重点，任意一个现成的 PostgreSQL 实例都可以。）接好之后，Admin 界面的 Usage 页能按密钥、按模型看消费曲线，也可以用接口直接查某个虚拟密钥的花费：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl &quot;http://localhost:4000/key/info?key=sk-某个虚拟密钥&quot; \
  -H &quot;Authorization: Bearer sk-master-换成你自己的随机长串&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回里的 &lt;code&gt;spend&lt;/code&gt; 就是这个密钥累计花掉的钱。对个人玩家来说，这解决了一个很实际的问题：脚本在后台默默跑偏时，不用等供应商账单出来才发现。&lt;/p&gt;
&lt;h3&gt;缓存&lt;/h3&gt;
&lt;p&gt;对重复提问较多的场景（比如同一批文档反复问答），可以开启响应缓存，命中时直接返回旧结果，不再向上游付费：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;litellm_settings:
  cache: true
  cache_params:
    type: local        # 个人使用够了；多实例部署可换成 redis
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;缓存适合问答结果稳定的场景；需要每次答案都有随机性的创作类调用，记得在请求里带上参数单独关掉，别让缓存把多样性吃掉。&lt;/p&gt;
&lt;h3&gt;顺带一提：和 CLIProxyAPI 分工不同&lt;/h3&gt;
&lt;p&gt;本系列另一篇讲的 &lt;a href=&quot;/posts/ai-cliproxyapi/&quot;&gt;CLIProxyAPI&lt;/a&gt; 解决的是另一头的问题：它把命令行订阅账号包装成 API。两者不冲突，反而能串联——CLIProxyAPI 对外同样是 OpenAI 兼容接口，把它作为一个上游条目写进 LiteLLM 的 &lt;code&gt;model_list&lt;/code&gt;（&lt;code&gt;api_base&lt;/code&gt; 指向它的地址），就能让订阅账号来的模型也进入统一的密钥、限额和日志体系。&lt;/p&gt;
&lt;h2&gt;与直连的取舍：什么时候值得多这一层&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;直连供应商&lt;/th&gt;
&lt;th&gt;经过 LiteLLM 网关&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;接入成本&lt;/td&gt;
&lt;td&gt;每家一套 SDK 参数与密钥管理&lt;/td&gt;
&lt;td&gt;客户端只认一个地址、一套格式&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;换供应商&lt;/td&gt;
&lt;td&gt;改代码、改配置、重新发版&lt;/td&gt;
&lt;td&gt;改 &lt;code&gt;config.yaml&lt;/code&gt; 里一行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;密钥安全&lt;/td&gt;
&lt;td&gt;真实密钥散落在每个客户端&lt;/td&gt;
&lt;td&gt;真实密钥只存网关，客户端用虚拟密钥&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;限额与账单&lt;/td&gt;
&lt;td&gt;各家后台分别看，口径不一&lt;/td&gt;
&lt;td&gt;一处设预算、一处看总账&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;故障转移&lt;/td&gt;
&lt;td&gt;自己写重试与切换逻辑&lt;/td&gt;
&lt;td&gt;配置即得&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;代价&lt;/td&gt;
&lt;td&gt;——&lt;/td&gt;
&lt;td&gt;多一跳网络延迟（通常毫秒级）、网关本身成为单点&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;判断标准很朴素：只有一个项目、一家供应商，网关纯属多余，直连最省事；一旦出现「两家以上供应商」「本地模型加云端混用」「多个工具共用密钥」「想给某个脚本封顶预算」中的任何一条，网关省下的管理成本就远超它多出的那一跳。单点问题对个人部署不算大事——网关挂了客户端会立刻报错，重启容器即可恢复；真到了在意可用性的规模，再考虑多实例加负载均衡，那已经是另一个话题了。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;请求返回 401 Authentication Error。&lt;/strong&gt; 先分清用的是哪把钥匙：调业务接口可以用虚拟密钥，调 &lt;code&gt;/key/generate&lt;/code&gt; 这类管理接口必须用主密钥。还要检查主密钥的配置方式——用 &lt;code&gt;general_settings.master_key&lt;/code&gt; 引用环境变量时，写法必须是 &lt;code&gt;os.environ/LITELLM_MASTER_KEY&lt;/code&gt;，漏了前缀会被当成字面字符串。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;返回 400，提示模型不存在或 model not found。&lt;/strong&gt; 客户端请求里的 &lt;code&gt;model&lt;/code&gt; 必须填 &lt;code&gt;config.yaml&lt;/code&gt; 里的别名（&lt;code&gt;model_name&lt;/code&gt;），不是上游的真实模型名。先调 &lt;code&gt;/v1/models&lt;/code&gt; 对一眼网关实际注册了哪些别名；如果列表里根本没有，多半是配置文件没挂载对或改完没重启，&lt;code&gt;docker compose logs&lt;/code&gt; 里会有 YAML 解析报错。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;本地模型条目连不上 Ollama。&lt;/strong&gt; 容器里访问宿主机不能用 &lt;code&gt;localhost&lt;/code&gt;——那指的是容器自己。确认 Compose 里有 &lt;code&gt;extra_hosts: [&quot;host.docker.internal:host-gateway&quot;]&lt;/code&gt;，且 &lt;code&gt;api_base&lt;/code&gt; 写的是 &lt;code&gt;http://host.docker.internal:11434&lt;/code&gt;；再在宿主机上 &lt;code&gt;curl http://localhost:11434/api/tags&lt;/code&gt; 确认 Ollama 本身在跑。如果 Ollama 是装在另一台机器上，直接把 &lt;code&gt;api_base&lt;/code&gt; 换成那台机器的内网地址即可。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;某些参数被上游拒绝，报 400 Unsupported parameter。&lt;/strong&gt; 不同供应商支持的参数不一样，比如把 OpenAI 的参数原样发给别的模型就会中招。在 &lt;code&gt;litellm_settings&lt;/code&gt; 里打开 &lt;code&gt;drop_params: true&lt;/code&gt;，网关会自动丢弃目标模型不支持的参数，绝大多数这类报错会消失。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;重启容器后，虚拟密钥和消费记录全没了。&lt;/strong&gt; 这是没接数据库的必然结果：默认状态只存内存。按上一节给网关配上 &lt;code&gt;DATABASE_URL&lt;/code&gt; 指向 PostgreSQL，密钥与消费记录才会持久化；已经在裸跑的，先把现有虚拟密钥清单导出备份再迁移。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;流式输出中途断开。&lt;/strong&gt; 多半是超时：本地大模型首字慢、云端长回答久，都会撞上默认超时。把 &lt;code&gt;router_settings.timeout&lt;/code&gt; 调大（比如 300），同时检查客户端自己的读取超时设置，两边都要放宽，只改一边没用。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Admin 界面打不开或登录失败。&lt;/strong&gt; &lt;code&gt;/ui&lt;/code&gt; 登录用的就是主密钥本身（用户名任意或留空视版本而定）。如果改过主密钥但没重启容器，界面仍认旧值；另外注意别把 &lt;code&gt;LITELLM_MASTER_KEY&lt;/code&gt; 和给数据库用的其他密码搞混，它们互不相干。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;LiteLLM Proxy 的定位，是给所有模型调用立一个总闸口：上游无论是云端 API 还是本地 Ollama，在 &lt;code&gt;config.yaml&lt;/code&gt; 里统一命名、统一收编；下游无论是什么工具，只认一个地址、一把虚拟密钥。密钥不再散落、预算有了封顶、账单有了一处总账、供应商故障有了自动转移——这些都不是某一家供应商接口能给你的。&lt;/p&gt;
&lt;p&gt;落地顺序建议照着本篇走：先 Docker 起网关、把在用的两三个模型写进 &lt;code&gt;model_list&lt;/code&gt; 跑通，再给每个项目换发虚拟密钥，最后按需要打开日志持久化和缓存。跑顺之后你会发现，之后每次想试新模型，动作都只剩下「在配置里加四行」。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：MatrixMedia 矩媒视频矩阵发布</title><link>https://www.anexns.cloudns.org/posts/ai-matrixmedia/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-matrixmedia/</guid><description>用开源工具矩媒 MatrixMedia 把一条视频批量分发到抖音、快手、视频号、小红书、B 站等 8 个平台：图形界面、CLI、HTTP 接口与 MCP 四种操控方式、多账号矩阵管理、评论 dry-run 回复，以及交给 AI 智能体编排发布的完整工作流与风控边界。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：一条视频发一圈平台，要重复劳动多少次&lt;/h2&gt;
&lt;p&gt;做短视频的人都熟这个流程：片子剪好了，打开抖音创作者后台，上传、等转码、填标题、填简介、选标签、挂话题；再打开快手，重复一遍；再打开视频号，重复一遍，而且它还要多填一个短标题；然后是小红书、B 站、百家号、头条号……平台之间字段还各不一样，有的把简介和标签拼进正文，有的标签走单独的话题控件，有的干脆只认标题。&lt;/p&gt;
&lt;p&gt;一条视频发一圈，熟练了也要小半个小时，全是无脑重复劳动。要是手里不止一个账号——主号、垂类号、地区号组成的账号矩阵——这个数字还要再乘以账号数。更麻烦的是发完之后：每个平台的数据（粉丝、播放、点赞）要逐个后台去看，评论要逐个后台去回。一天下来，真正花在创作上的时间没多少，全耗在「搬运」上了。&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;认识矩媒的四种操控方式 → 把账号矩阵登录好 → 图形界面手动发一条 → 用 CLI 把发布变成可脚本化的命令 → 用 HTTP 接口和 MCP 把发布交给其它程序和 AI 助手 → 最后把风控边界说清楚&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/hanliang97/MatrixMedia&lt;/p&gt;
&lt;h2&gt;它是什么：一个 Electron 应用，四种操控方式&lt;/h2&gt;
&lt;p&gt;矩媒（MatrixMedia）是一个开源的视频矩阵发布工具，GPL-2.0 许可，基于 Electron + Vue 构建，支持 Windows 与 macOS。它和常见的「一键分发」工具最大的区别不在界面，而在于它从设计上就准备了四种操控方式：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;操控方式&lt;/th&gt;
&lt;th&gt;适合谁&lt;/th&gt;
&lt;th&gt;上手门槛&lt;/th&gt;
&lt;th&gt;能否被智能体调用&lt;/th&gt;
&lt;th&gt;典型场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;图形界面（GUI）&lt;/td&gt;
&lt;td&gt;手动运营者&lt;/td&gt;
&lt;td&gt;低，装好、登录就能用&lt;/td&gt;
&lt;td&gt;不能直接调用，但它是全部登录态的来源&lt;/td&gt;
&lt;td&gt;日常手动发布、各平台首次登录、改发布设置&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;命令行（CLI）&lt;/td&gt;
&lt;td&gt;会写脚本的人、自动化流程&lt;/td&gt;
&lt;td&gt;中，要熟悉终端&lt;/td&gt;
&lt;td&gt;能，靠退出码与 JSON 输出对接&lt;/td&gt;
&lt;td&gt;定时批量发布、流水线里的发布环节、上线前检查&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HTTP 接口&lt;/td&gt;
&lt;td&gt;本机上其它程序&lt;/td&gt;
&lt;td&gt;中，要会发 HTTP 请求&lt;/td&gt;
&lt;td&gt;能，前提是 GUI 保持运行&lt;/td&gt;
&lt;td&gt;自己的小工具、本地服务触发发布&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MCP 服务&lt;/td&gt;
&lt;td&gt;AI 助手用户&lt;/td&gt;
&lt;td&gt;中，要先构建一次并写配置&lt;/td&gt;
&lt;td&gt;能，原生工具调用&lt;/td&gt;
&lt;td&gt;在对话里让助手查账号、发视频、回评论&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;四种方式共用同一份账号登录态和同一套发布记录。也就是说：&lt;strong&gt;先在图形界面里把账号登录好，剩下的事就可以逐步从手动过渡到脚本，再过渡到智能体&lt;/strong&gt;，不用为每种方式各登一遍号。&lt;/p&gt;
&lt;p&gt;从仓库的 Releases 页下载安装包即可。Windows 的 NSIS 安装包（0.4.5 起）会自动把安装目录加入当前用户的 PATH，装完重开终端就能直接用 &lt;code&gt;matrixmedia&lt;/code&gt; 命令；macOS 把 App 拖进「应用程序」后，需要手动建一个符号链接：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo ln -sf /Applications/matrixmedia.app/Contents/MacOS/matrixmedia /usr/local/bin/matrixmedia
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;之后在任意终端都能直接敲 &lt;code&gt;matrixmedia cli ...&lt;/code&gt;。覆盖升级时 App 路径不变，链接继续有效，不用重做。&lt;/p&gt;
&lt;h2&gt;能发哪些平台：8 个视频平台，外加掘金文章&lt;/h2&gt;
&lt;p&gt;矩媒目前完整自动化的发布平台共 8 个，命令行里用短码指代：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;平台&lt;/th&gt;
&lt;th&gt;CLI 短码&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;抖音&lt;/td&gt;
&lt;td&gt;&lt;code&gt;dy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;CLI 可扫码登录；支持商品挂载配置&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;快手&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ks&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;评论拉取与回复已支持&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;百家号&lt;/td&gt;
&lt;td&gt;&lt;code&gt;bjh&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;发布只写标题，正文规则随平台&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;哔哩哔哩&lt;/td&gt;
&lt;td&gt;&lt;code&gt;blbl&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;简介与标签各自独立填写&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;头条号&lt;/td&gt;
&lt;td&gt;&lt;code&gt;tt&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;发布只写标题&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;视频号&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sph&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;CLI 可扫码登录；有独立的短标题字段&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;小红书&lt;/td&gt;
&lt;td&gt;&lt;code&gt;xhs&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;有真实浏览器发布模式，见下文&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;番茄视频&lt;/td&gt;
&lt;td&gt;&lt;code&gt;fqsp&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;别名 &lt;code&gt;fanqie&lt;/code&gt;、&lt;code&gt;fq&lt;/code&gt;、番茄视频&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;除视频外，它还能往&lt;strong&gt;掘金&lt;/strong&gt;发文章（短码 &lt;code&gt;juejin&lt;/code&gt;），走的是单独的 &lt;code&gt;publish-article&lt;/code&gt; 子命令。发布时 &lt;code&gt;file&lt;/code&gt; 参数除了本地路径，也支持 &lt;code&gt;http(s)&lt;/code&gt; 远程 URL：工具会先把视频下载到临时目录，全部平台发布结束后自动清理。&lt;/p&gt;
&lt;h2&gt;账号与登录：矩阵的根基在登录态共享&lt;/h2&gt;
&lt;p&gt;矩阵运营的前提是多账号管理。矩媒里账号以手机号分组，每个账号在每个平台各有一份登录态，CLI 与图形界面共用同一个 session 分区（&lt;code&gt;persist:&amp;lt;手机号&amp;gt;&amp;lt;平台&amp;gt;&lt;/code&gt;），互不侵扰。登录方式有讲究：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;抖音与视频号&lt;/strong&gt;：CLI 直接支持扫码登录，终端里会打印二维码（抖音另支持 puppeteer 无头方式）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;其它平台&lt;/strong&gt;：先在图形界面里登录一次，之后 CLI、HTTP、MCP 全部复用这份登录态。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;登录态过期&lt;/strong&gt;：&lt;code&gt;cli accounts&lt;/code&gt; 会报 &lt;code&gt;cookie 已过期&lt;/code&gt;，回图形界面重新登录一次即可，不用逐个工具处理。&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;# 抖音扫码登录（终端出二维码）
matrixmedia cli login -p dy --phone 13800138000

# 随时检查全部账号的登录态，适合放在自动化流程开头做 preflight
matrixmedia cli accounts --json
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;accounts&lt;/code&gt; 和 &lt;code&gt;history&lt;/code&gt; 这两个查询命令只读本机数据，不会触发任何登录或发布动作，所以特别适合在流水线里做发布前检查：先确认目标账号在线，再决定要不要往下走。&lt;/p&gt;
&lt;h2&gt;图形界面：本地视频发布&lt;/h2&gt;
&lt;p&gt;图形界面的核心页是「本地视频发布」：选好视频文件，逐个平台填标题、简介、标签，再勾选要发的账号，一次提交。字段会按平台规则各自落地——抖音、快手、视频号把简介与标签拼进正文；小红书正文写简介、标签走话题控件；B 站简介和标签分开填；头条、百家号只写标题。视频号还有一个&lt;strong&gt;短标题&lt;/strong&gt;字段（建议 6～16 字），和标题是两回事，别漏填。定时发布、创作声明这类选项在批量设置里统一配。&lt;/p&gt;
&lt;p&gt;几个平台特有项值得单独说：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;抖音商品挂载&lt;/strong&gt;：在「本地视频发布 → 第三方属性」里可为每个账号配置一种商品，填完整商品链接和 1～10 字的商品短标题（注意这与视频号的短标题是两个独立字段）。官方说明该功能尚待有带货权限的真实账号验收，开启后任务只尝试一次，失败先人工核对再重试；目录批量发布配了抖音商品会被明确阻断，要改走单视频发布。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;小红书真实浏览器发布模式&lt;/strong&gt;：小红书对 Electron 内置窗口的自动化检测日趋严格，可能弹出「AI 托管」类警告。矩媒的对策是改用本机已安装的 Google Chrome 发布：在「账号管理 → 小红书账号 → 发布设置」里打开「使用真实浏览器」开关，首次开启会自动检测 Chrome 路径（也可以手动选 &lt;code&gt;.app&lt;/code&gt; 或 &lt;code&gt;.exe&lt;/code&gt;），点「测试连接」确认可用后保存。发布时它用 puppeteer-core 驱动本机 Chrome，并自动把内置窗口的登录态同步过去；若 Chrome 检测不到或启动失败，会自动回退到内置窗口模式。Chrome 路径是全局配置，所有小红书账号共用。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;命令行：子命令、退出码与 JSON&lt;/h2&gt;
&lt;p&gt;在启动参数里带上 &lt;code&gt;cli&lt;/code&gt; 子串即进入命令行模式，不打开主窗口。子命令一览：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;子命令&lt;/th&gt;
&lt;th&gt;支持平台&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cli login&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;抖音、视频号&lt;/td&gt;
&lt;td&gt;终端二维码扫码登录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cli publish&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;8 个视频平台&lt;/td&gt;
&lt;td&gt;发布视频，本地路径或远程 URL&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cli publish-article&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;掘金&lt;/td&gt;
&lt;td&gt;发布文章，&lt;code&gt;--content&lt;/code&gt; 或 &lt;code&gt;--file&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cli accounts&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;全平台&lt;/td&gt;
&lt;td&gt;列出账号并实时检测登录态&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cli history&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;全平台&lt;/td&gt;
&lt;td&gt;查本机发布记录，可按平台、状态、天数过滤&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cli stats&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;7 个平台&lt;/td&gt;
&lt;td&gt;读账号粉丝数据快照（粉丝、播放、点赞、评论、收藏）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cli stats-sync&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;7 个平台&lt;/td&gt;
&lt;td&gt;主动采集最新数据并写入快照&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cli stats-work&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;7 个平台&lt;/td&gt;
&lt;td&gt;按完整标题查某个视频的发布数据&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cli comments&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;抖音、快手、视频号&lt;/td&gt;
&lt;td&gt;拉取已发布作品的评论列表（只读）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cli comments-reply&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;抖音、快手、视频号&lt;/td&gt;
&lt;td&gt;回复评论，默认 dry-run&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;每个子命令都支持 &lt;code&gt;--help&lt;/code&gt;。真正让它能被程序消费的是这套&lt;strong&gt;统一约定&lt;/strong&gt;：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;约定项&lt;/th&gt;
&lt;th&gt;内容&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;进入 CLI 模式&lt;/td&gt;
&lt;td&gt;启动参数含 &lt;code&gt;cli&lt;/code&gt; 即进入无 GUI 流程&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;退出码&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0&lt;/code&gt; 成功 / &lt;code&gt;1&lt;/code&gt; 异常 / &lt;code&gt;2&lt;/code&gt; 参数错误 / &lt;code&gt;3&lt;/code&gt; 业务失败（登录、上传等）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;机器可读输出&lt;/td&gt;
&lt;td&gt;&lt;code&gt;accounts --json&lt;/code&gt;、&lt;code&gt;history --json&lt;/code&gt; 产出稳定 JSON&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;登录态共享&lt;/td&gt;
&lt;td&gt;CLI 与 GUI 共用同一 session 分区&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;可直接抄的发布示例：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 发抖音：标题、简介、标签一次给全
matrixmedia cli publish -p dy --phone 13800138000 -f /path/to/video.mp4 \
  -t &quot;标题&quot; --description &quot;视频简介&quot; --tags &quot;#跑步 #新手&quot;

# 发视频号：多一个短标题
matrixmedia cli publish -p sph --phone 13800138000 -f /path/to/video.mp4 \
  -t &quot;标题&quot; --description &quot;视频简介&quot; --short-title &quot;5公里新手挑战&quot; --tags &quot;#跑步 #新手&quot;

# 发掘金文章
matrixmedia cli publish-article -p juejin --phone 13800138000 -t &quot;文章标题&quot; --file ./post.md

# 查最近 7 天发布记录（JSON 输出，给上游程序消费）
matrixmedia cli history --json --days 7
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;数据统计是「先采集、再读快照」的两步：&lt;code&gt;stats-sync&lt;/code&gt; 主动去平台抓最新数据写进本地快照，&lt;code&gt;stats&lt;/code&gt; 和 &lt;code&gt;stats-work&lt;/code&gt; 只读快照，所以查询瞬间返回、不必每次都惊动平台。&lt;/p&gt;
&lt;h2&gt;评论互动：默认 dry-run，真发要显式确认&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;cli comments&lt;/code&gt; 把抖音、快手、视频号已发布作品的评论拉回本地，归一化成统一 JSON。回复走 &lt;code&gt;cli comments-reply&lt;/code&gt;，工作方式是先把回复内容写进一个 JSON 文件，再交给命令校验：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 拉评论
matrixmedia cli comments -p ks --phone 123

# 只校验、不真发（默认 dry-run）
matrixmedia cli comments-reply -p ks --phone 123 --file replies.json

# 人工核准后，加 --execute 才真正发出
matrixmedia cli comments-reply -p ks --phone 123 --file replies.json --execute
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不加 &lt;code&gt;--execute&lt;/code&gt; 就永远只是校验，加了才会真发&amp;lt;/span&amp;gt;，整个过程全程留台账，事后能查每条回复的去向。这个「默认不动手」的设计对自动化场景很重要：脚本和智能体可以先把回复草稿批量生成好，人过目确认后统一放行。&lt;/p&gt;
&lt;h2&gt;HTTP 接口：GUI 开着，本机程序就能触发发布&lt;/h2&gt;
&lt;p&gt;图形界面启动后，应用会在本机 30088 端口监听一个内置服务，其它程序 POST 一个 JSON 就能触发发布：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -X POST http://127.0.0.1:30088/publish \
  -H &quot;Content-Type: application/json&quot; \
  -d &apos;{
    &quot;phone&quot;: &quot;13800138000&quot;,
    &quot;file&quot;: &quot;https://example.com/video.mp4&quot;,
    &quot;title&quot;: &quot;我的视频标题&quot;,
    &quot;description&quot;: &quot;视频简介&quot;,
    &quot;shortTitle&quot;: &quot;5公里新手挑战&quot;,
    &quot;tags&quot;: &quot;跑步 新手&quot;,
    &quot;platforms&quot;: [&quot;dy&quot;, &quot;sph&quot;, &quot;ks&quot;]
  }&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;行为细节：单平台请求会等待上传完成再返回最终状态；多平台请求与图形界面的批量发布一致，提交到发布队列后立即返回，响应里 &lt;code&gt;status&lt;/code&gt; 为 &lt;code&gt;submitted&lt;/code&gt;，最终成败以发布记录为准。请求体里 &lt;code&gt;file&lt;/code&gt; 必填（本地绝对路径或远程 URL，远程文件只下载一次供多平台共用），&lt;code&gt;publishAt&lt;/code&gt; 可指定一次性定时发布（格式 &lt;code&gt;YYYY-MM-DD HH:mm:ss&lt;/code&gt;，多平台时需全部一致）。错误语义也和 CLI 对齐：参数错误返回 HTTP 400；发布失败（如未登录）仍返回 HTTP 200，但 &lt;code&gt;success: false&lt;/code&gt;、&lt;code&gt;exitCode: 3&lt;/code&gt;，调用方按退出码判断即可，不用去猜 HTTP 状态。&lt;/p&gt;
&lt;p&gt;与 CLI 的分工很清楚：HTTP 接口依赖 GUI 主进程已运行（窗口或托盘在就行），胜在接入简单；CLI 可以独立冷启动，胜在适合定时任务和流水线。&lt;/p&gt;
&lt;h2&gt;MCP 接入：让 AI 助手在对话里直接发布&lt;/h2&gt;
&lt;p&gt;仓库内置了 &lt;code&gt;mcp/&lt;/code&gt; 子包，实现了一个标准的 MCP Server，让支持 MCP 的 AI 工具不用绕 shell 就能直接操作矩媒。先构建一次：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd mcp &amp;amp;&amp;amp; npm install &amp;amp;&amp;amp; npm run build
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后在 Claude Desktop、Cursor、Cline 的 MCP 配置里加上（把路径换成本机仓库的绝对路径）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;mcpServers&quot;: {
    &quot;matrixmedia&quot;: {
      &quot;command&quot;: &quot;node&quot;,
      &quot;args&quot;: [&quot;&amp;lt;MATRIXMEDIA_DIR&amp;gt;/mcp/dist/index.js&quot;],
      &quot;env&quot;: {
        &quot;MATRIXMEDIA_DIR&quot;: &quot;&amp;lt;MATRIXMEDIA_DIR&amp;gt;&quot;
      }
    }
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重启 AI 工具后，以下 9 个工具即可在对话中直接调用：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;工具&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;list_accounts&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列出本机已登录账号，支持按平台过滤&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;list_history&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;查询本机发布记录，支持按平台、状态、天数过滤&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;publish_video&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;发布视频到指定平台（最长 35 分钟，支持定时发布）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;publish_article&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;发布掘金文章（需已登录掘金账号）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;get_account_stats&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;读取账号粉丝数据快照&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;sync_account_stats&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;主动采集最新数据并写入快照&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;get_work_stats&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;按完整标题查某个视频的发布数据&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;list_comments&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;拉取已发布作品的评论列表（抖音、快手、视频号，只读）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;reply_comment&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;回复评论，默认 dry-run，&lt;code&gt;confirm=true&lt;/code&gt; 才真发&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;有一个前提必须记牢：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;所有平台都要先在图形界面里登录，MCP 运行在无头环境，弹不出扫码窗口&amp;lt;/span&amp;gt;。所以正确顺序永远是：装好应用 → 界面里把号登全 → 再接 MCP。&lt;code&gt;reply_comment&lt;/code&gt; 的 dry-run 默认值也延续了 CLI 的克制：助手可以起草，真发必须显式确认。&lt;/p&gt;
&lt;h2&gt;为什么它适合交给智能体&lt;/h2&gt;
&lt;p&gt;把上面几节串起来看，矩媒为自动化准备的其实是一整套契约：参数里带 &lt;code&gt;cli&lt;/code&gt; 就进无头模式；退出码四档语义稳定；查询类命令输出稳定 JSON；登录态在 GUI、CLI、HTTP、MCP 之间共享一份；危险动作（回评论）默认 dry-run、全程台账。这意味着它&lt;strong&gt;与具体框架无关&lt;/strong&gt;——Claude Code、Codex 这类编程智能体，Cursor、Cline 这类 IDE 助手，以及 Dify、n8n 这类工作流编排平台（参见 &lt;a href=&quot;/posts/ai-dify-workflow/&quot;&gt;Dify 工作流篇&lt;/a&gt;），只要能调用外部命令、读退出码或接 MCP，就能把矩媒当成发布环节接进去。仓库甚至在顶部留了给智能体生态的可发现注释标记，声明自己的 CLI 入口与约定。&lt;/p&gt;
&lt;p&gt;放到整条创作流水线里看分工更清楚：上一篇介绍的 &lt;a href=&quot;/posts/ai-toonflow/&quot;&gt;Toonflow&lt;/a&gt; 负责生产端——剧本、分镜、角色资产到视频片段都在一张画布里完成；矩媒负责分发端——成片出来后，一条命令或一次 MCP 调用就铺到 8 个平台。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;生产与分发各交给一个开源工具，中间用 CLI 与 MCP 串起来，就是一条能跑通的短视频流水线。&amp;lt;/span&amp;gt;而 &lt;a href=&quot;/posts/ai-cli-assistants/&quot;&gt;CLI 助手篇&lt;/a&gt; 里讲的那些命令行智能体，正好是最适合站在中间发号施令的角色。&lt;/p&gt;
&lt;h2&gt;风险与边界：自动化发布不是没有代价&lt;/h2&gt;
&lt;p&gt;:::warning
矩阵批量发布本质上是自动化操作各平台的创作者后台，而每个平台对自动化行为的规则与风控尺度各不相同。同一条视频短时间内铺满全平台、多账号发高度重复的内容、发布频率明显超出真人节奏，都可能触发平台的限流、审核拦截，严重的直接封号。这类风险与工具无关，是这类玩法自带的。
:::&lt;/p&gt;
&lt;p&gt;实操上克制一点：发布频率贴近真人节奏，各平台的标题、简介、标签做差异化而不是一字不差地复制；新号、刚养的号先小批量试水，确认账号状态正常再放大；重要账号不要和测试账号混在同一批任务里。账号 Cookie、本地素材都属于敏感数据，只存在本机、妥善保管。工具自带的使用声明也写明了：仅用于合法合规的学习与效率提升场景，不要用于批量作弊、恶意营销、侵权搬运与刷量。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;终端里提示找不到 &lt;code&gt;matrixmedia&lt;/code&gt; 命令？&lt;/strong&gt;
Windows 先确认装的是 0.4.5 之后的安装包（会自动写 PATH），并重开终端；macOS 按上文建好符号链接，或临时用 &lt;code&gt;alias&lt;/code&gt; 指向 App 内的可执行文件。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;macOS 提示「已损坏，无法打开」？&lt;/strong&gt;
多半是 Gatekeeper 拦截未签名应用，并非安装包真损坏。先确认下的是与芯片匹配的包（Apple Silicon 用 arm64 版），把 App 拖进「应用程序」后执行一次：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;xattr -dr com.apple.quarantine /Applications/matrixmedia.app
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;cli accounts&lt;/code&gt; 报 &lt;code&gt;cookie 已过期&lt;/code&gt;？&lt;/strong&gt;
回图形界面把该平台重新登录一次即可，CLI、HTTP、MCP 共用同一份登录态，不用逐处处理。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;在 MCP 里发布失败，或提示未登录？&lt;/strong&gt;
MCP 无头环境无法扫码。先打开图形界面确认对应平台账号在线，再回助手里重试；也可以先用 &lt;code&gt;list_accounts&lt;/code&gt; 让助手自查一遍登录态。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;HTTP 接口连不上（30088 端口无响应）？&lt;/strong&gt;
这个接口依赖 GUI 主进程运行，先把应用打开（窗口或托盘在即可）。参数错误会返回 HTTP 400，先对照字段表检查请求体；发布类失败返回的是 HTTP 200 加 &lt;code&gt;exitCode: 3&lt;/code&gt;，别只看状态码。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;comments-reply&lt;/code&gt; 执行了却没发出回复？&lt;/strong&gt;
默认就是 dry-run，只做校验并写台账。确认内容无误后，加 &lt;code&gt;--execute&lt;/code&gt; 重新执行才是真发。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;小红书发布时弹出自动化/托管类警告？&lt;/strong&gt;
去「账号管理 → 小红书账号 → 发布设置」开启「使用真实浏览器」，用本机 Chrome 发布；开启后点一次「测试连接」，若检测不到 Chrome 会自动回退内置窗口，那就先把 Chrome 装好或手动指定路径。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;启动时提示 &lt;code&gt;ELECTRON_RUN_AS_NODE&lt;/code&gt; 相关错误？&lt;/strong&gt;
该环境变量被误开启会导致启动异常，按提示先关闭它再启动应用。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;矩媒解决的是短视频流水线的最后一公里：一条视频从成片到铺满 8 个平台，从半小时的重复劳动变成一次提交。它真正的分量不在图形界面，而在界面之下那套为自动化准备的契约——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;退出码、JSON 输出、登录态共享、危险动作默认 dry-run，这四样齐了，一个发布工具才算得上能交给智能体的基础设施。&amp;lt;/span&amp;gt;手动发用 GUI，定时批量用 CLI，本机程序联动用 HTTP，想让 AI 助手直接上手就接 MCP；再往前接上 Toonflow 这类生产工具，一条从创作到分发的完整链路就成型了。只记住一条底线：能力越自动，节奏越要克制，账号安全永远排在效率前面。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：ComfyUI-MiniMaxDirector 给 MiniMax H3 当导演</title><link>https://www.anexns.cloudns.org/posts/ai-minimax-director/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-minimax-director/</guid><description>ComfyUI-MiniMaxDirector 把 MiniMax H3 的生成方式从「一段提示词碰运气」变成「时间线排镜头」：分镜块、运镜词汇、主体卡片与帧格规则全部结构化编译，本篇讲清它的编译器原理、三个节点、权重安装与时间线实操。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：一个提示词框，装不下一整片&lt;/h2&gt;
&lt;p&gt;用视频模型做短片，最常见的姿势是把整片的想法——谁出场、镜头怎么走、哪句台词在什么时候说、画面里要出现什么字——一股脑塞进一个提示词框，然后点生成，剩下的交给运气。短片一长，这种做法立刻崩盘：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;镜头顺序对不上。想要「先推近再拉远」，模型可能反过来，或者干脆全程一个景别到底。&lt;/li&gt;
&lt;li&gt;台词和画面脱节。旁白说到第二句，画面还停在第一个场景，声画各走各的。&lt;/li&gt;
&lt;li&gt;人物前后不一致。上一镜穿红外套，下一镜变蓝了，因为提示词里的人物描述被淹没在长文中间，模型没抓住。&lt;/li&gt;
&lt;li&gt;改一处崩全片。想微调第二个镜头的运镜，只能改整段提示词重抽，前面已经对了的部分跟着一起变。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;问题的根子不在模型不够聪明，而在&lt;strong&gt;输入方式不对&lt;/strong&gt;：一整片本来就是有时间轴、有分工的结构化信息，硬压成一段散文，等于把分镜表揉成一团再扔给模型。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;ComfyUI-MiniMaxDirector 的思路是反过来：你在时间线上像导演一样排镜头，它负责把排好的结构编译成 H3 能精确执行的提示词。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/imbutus/ComfyUI-MiniMaxDirector&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;先讲清它为什么是「编译器」而不是关键帧工具 → 速查三个节点 → 装好节点与四个权重文件 → 在时间线上排一支短片 → 用主体卡片锁住一致性 → 避开帧格规则的坑 → 两个进阶开关与适用人群&lt;/strong&gt;。ComfyUI 本身的安装与节点基础不在本篇展开，没接触过的先看 &lt;a href=&quot;/posts/ai-comfyui-beginner/&quot;&gt;ComfyUI 绘图入门与节点工作流&lt;/a&gt; 补齐前置。&lt;/p&gt;
&lt;h2&gt;原理：为什么是「编译器」，不是关键帧注入&lt;/h2&gt;
&lt;p&gt;很多视频工作流的做法是「关键帧注入」：先生成几张关键帧图片，再让模型在帧与帧之间补运动。这条路对 H3 来说是绕远路，原因在它的文本编码器。&lt;/p&gt;
&lt;p&gt;MiniMax H3 的文本编码器是一个 &lt;strong&gt;32B 参数的视觉语言模型&lt;/strong&gt;。这个量级意味着它不是在「匹配关键词」，而是真的能读懂一份结构化的分镜表：哪个时间段发生什么、镜头怎么动、谁在说话、画面里有什么字，它都能逐项解析执行。所以面对 H3，真正要花功夫的不是造关键帧，而是&lt;strong&gt;把结构化提示词写对&lt;/strong&gt;——格式对、顺序对、引用对，模型自己会把分镜表「演」出来。&lt;/p&gt;
&lt;p&gt;ComfyUI-MiniMaxDirector 干的就是这件事，本质上是一个&lt;strong&gt;提示词编译器&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;你在图形界面里拖分镜块、选运镜、挂主体卡片，这些是「源代码」；&lt;/li&gt;
&lt;li&gt;它按 H3 能读懂的规范，把这些结构编译成最终提示词文本，这是「目标代码」；&lt;/li&gt;
&lt;li&gt;编译规则写错的地方，它还有一道检查（下面的 Report 节点）提前拦下来。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;它的灵感来源是 LTXDirector，两者形似而神不同：一句带过——LTXDirector 服务的是另一套模型与注入方式，这个插件则是完全围绕 H3「能读分镜表」这个特性重写的编译逻辑，不要把那边的经验原样搬过来。&lt;/p&gt;
&lt;p&gt;理解了这一层，后面所有设计都有了解释：为什么要分镜块、为什么运镜要拆成三个维度选、为什么台词有固定写法——全都是在帮你把「源代码」写规范，让编译结果不跑偏。提示词为什么值得当代码来写，本系列在 &lt;a href=&quot;/posts/ai-prompt-engineering/&quot;&gt;提示词工程实战&lt;/a&gt; 里有完整的展开，两篇可以对照着看。&lt;/p&gt;
&lt;h2&gt;三个节点速查&lt;/h2&gt;
&lt;p&gt;插件一共提供三个节点，分工正好对应「写、看、查」三个动作：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;节点&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;th&gt;什么时候用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Director&lt;/td&gt;
&lt;td&gt;时间线编辑器：排分镜块、设运镜、写台词、挂主体卡片，是全片的「源代码」入口&lt;/td&gt;
&lt;td&gt;从头到尾都在用它编排&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Prompt&lt;/td&gt;
&lt;td&gt;实时预览编译出的最终提示词文本，所见即所得地检查编译结果&lt;/td&gt;
&lt;td&gt;每次改完时间线扫一眼，确认文本没跑偏&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Report&lt;/td&gt;
&lt;td&gt;规则检查：按 H3 的规范校验当前编排，列出不合规项&lt;/td&gt;
&lt;td&gt;生成前必跑，相当于编译前的 lint&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;典型接法是 Director 的输出喂给 Prompt 预览、同时过一遍 Report 检查，两边都干净了再把提示词送进 H3 的生成链路。三个节点里 Director 是主战场，后面几节讲的全是它。&lt;/p&gt;
&lt;h2&gt;安装：节点 + 四个权重，缺一不可&lt;/h2&gt;
&lt;p&gt;安装分三步，要求 &lt;strong&gt;ComfyUI 0.31.0 以上&lt;/strong&gt;，低于这个版本先升级本体，老版本加载这个插件会直接报错或行为异常。&lt;/p&gt;
&lt;h3&gt;第一步：把插件克隆进 custom_nodes&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;cd ComfyUI/custom_nodes
git clone https://github.com/imbutus/ComfyUI-MiniMaxDirector.git
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;克隆完重启 ComfyUI，节点列表里能搜到 Director、Prompt、Report 三个节点，说明插件加载成功。&lt;/p&gt;
&lt;h3&gt;第二步：从 Comfy-Org/MiniMax-H3 下载四个权重文件&lt;/h3&gt;
&lt;p&gt;H3 的权重托管在 Comfy-Org 的 MiniMax-H3 仓库，一共要下&lt;strong&gt;四个&lt;/strong&gt;文件，各回各的目录：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;权重文件&lt;/th&gt;
&lt;th&gt;放进的目录&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;扩散模型（主模型）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;models/diffusion_models/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;生成的主体，体积最大&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文本编码器&lt;/td&gt;
&lt;td&gt;&lt;code&gt;models/text_encoders/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;就是那个 32B 视觉语言模型，负责读分镜表&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;视频 VAE&lt;/td&gt;
&lt;td&gt;&lt;code&gt;models/vae/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;管画面帧的编解码&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;音频 VAE&lt;/td&gt;
&lt;td&gt;&lt;code&gt;models/vae/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;管声音的编解码&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
注意：&lt;strong&gt;视频 VAE 和音频 VAE 是两个不同的文件，这不是笔误&lt;/strong&gt;。H3 是带声音的视频模型，画面和音频走两套独立的编解码，所以 VAE 要下两个、缺一不可。只下视频 VAE 的话，要么工作流直接报缺文件，要么生成出来没声音——这是新手最容易踩的坑，下完务必数一遍：四个文件，一个不能少。
:::&lt;/p&gt;
&lt;h3&gt;第三步：打开自带示例工作流&lt;/h3&gt;
&lt;p&gt;插件仓库里自带示例工作流，第一次上手不要从空白画布搭，直接打开示例：它把 Director、Prompt、Report 与 H3 的加载、采样、解码节点都接好了，你只需要确认四个权重在各自的加载节点里被正确选中，能跑通一次生成，再开始改成自己的片子。示例跑不通就先别往下走，回到排障小节逐项对。&lt;/p&gt;
&lt;h2&gt;时间线实操：在块上排镜头&lt;/h2&gt;
&lt;p&gt;Director 的编辑器是一条时间线，你的片子被切成一个个&lt;strong&gt;分镜块&lt;/strong&gt;，每块占一段时间、承载一个镜头。排片的基本动作就是：加块、拉长度、逐块填内容。每块要填的核心是三件事：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;画面内容&lt;/strong&gt;：这一镜里有什么、在发生什么，正常描述即可；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;运镜&lt;/strong&gt;：不要自己写散文式的运镜描述，用它给的&lt;strong&gt;运镜词汇&lt;/strong&gt;选，见下；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;声音&lt;/strong&gt;：台词或画外音，按规范写法填，见下。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;运镜词汇：运动类型 × 幅度 × 速度&lt;/h3&gt;
&lt;p&gt;运镜在编辑器里是三个维度的组合选择，而不是一个自由文本框：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;典型选项的含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;运动类型&lt;/td&gt;
&lt;td&gt;镜头怎么动&lt;/td&gt;
&lt;td&gt;推、拉、摇、移、跟、固定等基本运动&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;幅度&lt;/td&gt;
&lt;td&gt;动多少&lt;/td&gt;
&lt;td&gt;小幅、中幅、大幅，决定画面变化的程度&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;速度&lt;/td&gt;
&lt;td&gt;动多快&lt;/td&gt;
&lt;td&gt;慢速、匀速、快速，决定节奏感&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;三段一组合，「慢速小幅推近」和「快速大幅拉远」就是两个完全不同的镜头，编译出的提示词也会把这三个维度写明确。比起在散文里写一句「镜头缓缓地推近一点」，这种选法的好处是&lt;strong&gt;可复现&lt;/strong&gt;：同样的组合永远是同样的镜头语言，调参时也知道自己在改哪个维度。&lt;/p&gt;
&lt;h3&gt;台词与画外音：按规范写，别自由发挥&lt;/h3&gt;
&lt;p&gt;声音部分有固定写法，核心原则是&lt;strong&gt;把「谁在说」和「说什么」分开标清&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;角色台词：标明说话人，再写台词内容，让模型知道这句话是画面里的人开口说的，口型和表演都会对着这个人走；&lt;/li&gt;
&lt;li&gt;画外音/旁白：明确标注为画外音，与台词区分开，模型就不会给画面里的人物乱配口型；&lt;/li&gt;
&lt;li&gt;一块里多人说话时逐句标清说话人，不要写成一段对话流让模型自己猜。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;写法的细节以编辑器给出的格式为准，Report 节点也会检查这一块：说话人没标、台词和画外音混写，都会被它挑出来。&lt;/p&gt;
&lt;h3&gt;画内文字：逐字引用，一个字都别改&lt;/h3&gt;
&lt;p&gt;片子里如果有招牌、字幕牌、屏幕文字这类&lt;strong&gt;画内文字&lt;/strong&gt;，在分镜块里要用引用方式把要出现的文字&lt;strong&gt;逐字写明&lt;/strong&gt;。模型对画内文字是「照抄」逻辑：你引用什么，它渲染什么；你只写「一块写着店名的招牌」，它就自由发挥，出来的字大概率是错的或糊的。要上画的文字，逐字引用，这是唯一的可靠写法。&lt;/p&gt;
&lt;h2&gt;WHO &amp;amp; WHAT 主体卡片：一致性靠引用，不靠复述&lt;/h2&gt;
&lt;p&gt;长片最怕人物和物件前后变样。散文提示词的解法是每个镜头都把人物描述复述一遍，写得累，还总有几处写漏写岔。Director 的解法是 &lt;strong&gt;WHO &amp;amp; WHAT 主体卡片&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;把每个反复出现的主体建一张卡：&lt;strong&gt;人物、服装、道具、场景都可以建卡&lt;/strong&gt;，WHO 管「谁」，WHAT 管「什么东西」；&lt;/li&gt;
&lt;li&gt;卡片建好后会有一个&lt;strong&gt;引用编号&lt;/strong&gt;，在分镜块里&lt;strong&gt;点选插入&lt;/strong&gt;引用，这个镜头里出现谁、穿什么、拿什么道具，点几下就挂好了；&lt;/li&gt;
&lt;li&gt;不只是静态主体——&lt;strong&gt;动作和音色也能挂卡&lt;/strong&gt;：某个角色的标志性动作、某个说话人的固定音色，同样建卡引用，保证多镜头之间动作习惯和声音人设不漂移。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这样每个镜头对主体的描述都来自同一张卡的同一次定义，编译时展开成完全一致的文本，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;一致性不再靠你复述得勤快，而是靠引用机制在结构上锁死。&amp;lt;/span&amp;gt;这套思路和 AI 视频创作里「先定角色卡再逐镜引用」的做法一脉相承，&lt;a href=&quot;/posts/ai-muse-video-skill/&quot;&gt;Muse Video 虚拟剧组&lt;/a&gt; 里对角色资产化的处理可以对照看。&lt;/p&gt;
&lt;p&gt;代价是前期要花几分钟建卡，但片子越长越划算：三五个镜头的短打可以不建卡直接写，十几个镜头起步的片子，建卡省下的返工时间远超这几分钟。&lt;/p&gt;
&lt;h2&gt;帧格规则：length % 17 == 5，不用你手算&lt;/h2&gt;
&lt;p&gt;H3 在 24fps 下对片长帧数有一条硬规则：&lt;strong&gt;总帧数 length 必须满足 &lt;code&gt;length % 17 == 5&lt;/code&gt;&lt;/strong&gt;，即帧数除以 17 余 5。5、22、39、56……这些才是合法帧数，不满足这个数的片长，模型侧要么报错，要么输出异常。&lt;/p&gt;
&lt;p&gt;好消息是这条规则不用你拿计算器守着：&lt;strong&gt;Director 编辑器会自动把片长吸附对齐到最近的合法帧数&lt;/strong&gt;，你拖分镜块、改总时长时，它顺手就把总帧数修正到满足公式的位置。你要做的只有一件事：心里知道有这么条规则存在——当你发现总时长被「微调」了一点点，或者在插件之外手动改帧数参数后生成异常，先回来对这条公式，别往别处瞎查。&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要绕开编辑器去手改帧数。&amp;lt;/span&amp;gt;在采样或模型加载节点里直接改 length 而不满足 &lt;code&gt;% 17 == 5&lt;/code&gt;，是生成失败里最隐蔽的一种：参数看起来只差几帧，实际已经踩出合法集合。改片长一律回 Director 里拖，让吸附对齐替你守规矩。
:::&lt;/p&gt;
&lt;h2&gt;两个开关：默认关着，各有各的用途&lt;/h2&gt;
&lt;p&gt;Director 侧带两个可选开关，默认都是关闭状态，理解了再开：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;开关&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;什么时候开&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Turbo&lt;/td&gt;
&lt;td&gt;挂四步蒸馏 LoRA，用极少的采样步数快速出片&lt;/td&gt;
&lt;td&gt;排完时间线先看草稿：镜头顺序、运镜、台词对位对不对，用它低成本验一遍&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Upscale&lt;/td&gt;
&lt;td&gt;二阶段放大：按百万像素预算把成片分辨率往上抬&lt;/td&gt;
&lt;td&gt;草稿确认无误、要出正式版时再开，走完整步数生成加放大&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;推荐的工作节奏是：&lt;strong&gt;Turbo 出草稿 → 在草稿上改分镜、改运镜、改台词 → 定稿后关 Turbo、开 Upscale 出正式版&lt;/strong&gt;。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要拿 Turbo 的草稿画质当最终质量下结论&amp;lt;/span&amp;gt;，四步蒸馏本来就是拿画质换速度的，草稿糊是正常的，它只负责让你确认「结构对不对」。反过来，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;结构还没定就开着 Upscale 反复重出&amp;lt;/span&amp;gt;，是纯粹烧时间和显存，放大阶段的成本比基础生成高得多。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：插件节点搜不到，或加载时报错。&lt;/strong&gt;
先查 ComfyUI 版本，低于 0.31.0 先升级本体再重启；版本没问题再看启动日志里 custom_nodes 的加载报错，确认克隆目录完整、没有套娃出双层文件夹（&lt;code&gt;custom_nodes/ComfyUI-MiniMaxDirector/ComfyUI-MiniMaxDirector/&lt;/code&gt; 这种）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：工作流报缺权重文件，或者生成出来没声音。&lt;/strong&gt;
数文件：扩散模型、文本编码器、视频 VAE、音频 VAE 四个齐不齐，各自目录对不对。没声音十有八九是音频 VAE 没下或没在节点里选上——两个 VAE 是两个文件，再强调一遍。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：生成直接失败，参数只动过片长。&lt;/strong&gt;
对帧格规则：24fps 下总帧数要满足 &lt;code&gt;length % 17 == 5&lt;/code&gt;。是不是绕开 Director 手改过 length？改回去，在编辑器里拖时长让它自动吸附。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：镜头顺序、运镜和排的不一样。&lt;/strong&gt;
先过 Report 节点看有没有规则项没过；再开 Prompt 节点读一遍编译出的最终提示词，确认分镜块的顺序和运镜三维度（类型、幅度、速度）编译得对不对。问题大多出在块排错了顺序或运镜只选了类型没选幅度和速度，模型只能自己脑补缺失维度。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：台词对不上口型，或者旁白被画面里的人「说」了出来。&lt;/strong&gt;
台词与画外音的写法混了：台词要标清说话人，画外音要明确标为画外音。逐块检查声音部分的写法，改完再跑一遍 Report。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：人物跨镜头变脸、换衣服，道具一会儿有一会儿没。&lt;/strong&gt;
没建主体卡片、靠每镜复述描述的典型症状。把人物、服装、关键道具都建成 WHO &amp;amp; WHAT 卡片，各镜点选引用编号插入，动作和音色常复现的也挂卡。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：画内文字是错字、糊字。&lt;/strong&gt;
画内文字没有逐字引用。把要上画的文字在分镜块里逐字引用写明，不要只描述「有一块招牌」。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：Turbo 草稿画质差，是不是模型不行？&lt;/strong&gt;
不是。四步蒸馏 LoRA 的定位就是快速草稿，糊是预期内的。用它确认结构，定稿后关掉 Turbo 走完整生成，画质问题大概率自动消失。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：显存爆了。&lt;/strong&gt;
H3 加 32B 文本编码器本身就吃显存，先关 Upscale 降回基础分辨率出片，确认流程没问题再谈放大；Turbo 模式步数少，也能缓解一部分压力。&lt;/p&gt;
&lt;h2&gt;适合谁&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;在用 ComfyUI 做 H3 短片、且片子已经长到「一段提示词管不住」的人&lt;/strong&gt;：多镜头、带台词、要画内文字、人物跨镜复现，这四个特征占得越多，这个插件的收益越大。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;习惯先搭结构再抠细节的创作者&lt;/strong&gt;：它的工作方式就是导演式的——先排时间线和分镜，草稿验结构，定稿出成片，和 &lt;a href=&quot;/posts/ai-muse-video-prompt/&quot;&gt;AI 视频提示词工作流&lt;/a&gt; 里「先结构后生成」的节奏天然合拍。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;只做单镜头、一句话出片的轻量玩法&lt;/strong&gt;：用不上，分镜块和主体卡片的前期成本收不回来，原生提示词框就够了。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;ComfyUI-MiniMaxDirector 的价值，一句话：**它把「写提示词」升级成了「排片子」。**H3 的 32B 文本编码器本来就读得懂分镜表，这个插件做的，就是给你一套把分镜表写对的工具——时间线分镜块是骨架，运动类型×幅度×速度的运镜词汇是镜头语言，台词与画内文字的规范写法是细节纪律，WHO &amp;amp; WHAT 主体卡片锁一致性，&lt;code&gt;length % 17 == 5&lt;/code&gt; 的帧格吸附替你守住模型侧的硬规则，Turbo 与 Upscale 则把「验结构」和「出成片」分成两个成本档位。&lt;/p&gt;
&lt;p&gt;用它的正确姿势是导演的姿势：先排、先验、先改结构，最后才花大成本出片。把运气的部分压到最低，把可控的部分全部攥在自己手里——这就是给模型当导演的意思。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：MiniMax H3 ComfyUI 工作流实战</title><link>https://www.anexns.cloudns.org/posts/ai-minimax-h3-workflow/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-minimax-h3-workflow/</guid><description>一份开箱即用的 MiniMax H3 ComfyUI 工作流：首尾帧、图生、文生三种模式合一，讲清四个模型文件的存放目录、Turbo LoRA 节点安装、总控参数、分辨率与帧数 17k+5 对齐规矩，以及显存不足、时长对不齐等常见问题的排查。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：H3 能出片，但从零搭工作流劝退人&lt;/h2&gt;
&lt;p&gt;MiniMax H3 是目前少数能一次生成「画面＋声音」的开源视频模型：给它首帧、尾帧和一段文字，它能补出中间的动作、镜头运动，连音轨都一起解码出来。问题是，想在 ComfyUI 里把这条链路从零搭起来，门槛一点都不低：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;模型不是一个文件，是四个&lt;/strong&gt;。基础模型、文本编码器、视频 VAE、音频 VAE 各管一段，放错目录节点就找不到。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;帧数有对齐规矩&lt;/strong&gt;。H3 的帧数必须落在 &lt;code&gt;17k + 5&lt;/code&gt; 的序列上，随手填一个整数帧数，采样阶段就可能直接报错或者被悄悄改掉。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;采样器、调度器、LoRA 要配套&lt;/strong&gt;。Turbo LoRA 用哪套采样参数、强度给多少、显存不够时开哪个开关，都是试错试出来的经验。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;节点连错就跑不出带声音的片&lt;/strong&gt;。视频和音频是两条解码链，最后还要合成一路输出，任何一环断了，成片要么没声、要么干脆没有成片。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;本篇的主线就是绕开这轮试错：用一份别人已经调通的工作流 JSON，把模型加载、Turbo LoRA、采样、分辨率计算、音视频解码全部封装好，自己只需要在外层总控面板上换图、改词、调参数，就能跑出首尾帧视频、图生视频和文生视频三种结果。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/pixelaigc/ComfyUI-MiniMax-H3-Workflow&lt;/p&gt;
&lt;h2&gt;它是什么：一份 JSON，三种模式，一个总控面板&lt;/h2&gt;
&lt;p&gt;这个仓库本体非常小，只有一个工作流文件 &lt;code&gt;video_minimax_h3_t2v_0909.json&lt;/code&gt; 和一份说明。它的设计思路是「子流程封装＋外层总控」：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;子流程里&lt;/strong&gt;封装了模型加载、Turbo LoRA 挂载、采样、分辨率计算、视频与音频分别解码再合成的完整链路，平时不用进去看。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;外层总控面板&lt;/strong&gt;把日常要调的东西全提了出来：首帧、尾帧两个图像输入，提示词，基础模型、文本编码器、视频 VAE、音频 VAE、Turbo LoRA 的文件选择，以及步数、时长、种子、宽高比、百万像素。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;三种模式合一&lt;/strong&gt;：首尾帧都接是首尾帧视频，只接首帧是图生视频，两个都不接是文生视频，切换靠断开输入连线，不用换工作流。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;这份工作流的价值不在节点本身，而在于它把 H3 的全部配套规矩一次配齐了：你调的每个参数，都已经落在能跑通的组合里。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;它和本系列第 18 篇 &lt;a href=&quot;/posts/ai-minimax-director/&quot;&gt;ComfyUI-MiniMaxDirector&lt;/a&gt; 是上下游关系：那篇的 MiniMaxDirector 是「写词」工具，把分镜、运镜和音频线索编译成 H3 能吃的结构化提示词；本篇这份工作流是「执行」工具，负责把提示词真正跑成带声音的片子。两篇配合，先用导演节点写词，再拖进这份工作流出片，是目前 H3 最顺手的一条流水线。ComfyUI 本身的安装与节点基础不熟的，先看 &lt;a href=&quot;/posts/ai-comfyui-beginner/&quot;&gt;ComfyUI 入门篇&lt;/a&gt; 补一遍再回来。&lt;/p&gt;
&lt;h2&gt;环境与依赖：ComfyUI 本体加一个 Turbo 节点包&lt;/h2&gt;
&lt;p&gt;运行这份工作流需要两样东西：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;支持 MiniMax H3 与子图（subgraph）功能的 ComfyUI&lt;/strong&gt;。工作流里的 &lt;code&gt;MiniMaxH3ImageToVideo&lt;/code&gt;、&lt;code&gt;ResolutionSelector&lt;/code&gt;、&lt;code&gt;ComfyMathExpression&lt;/code&gt; 都是 ComfyUI 核心自带节点，不需要额外装；如果导入后这几个节点报缺失，先查 ComfyUI 版本是不是太旧、启动日志有没有导入错误。JSON 里记录的前端版本是 1.47.11，那只是作者的导出环境信息，不是验证过的最低版本。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Turbo 节点包 ComfyUI-MiniMax-H3-Turbo&lt;/strong&gt;（作者 Larryvrh），它提供工作流用到的 &lt;code&gt;MiniMaxH3TurboLoRA&lt;/code&gt; 节点。在 ComfyUI 根目录执行：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;git clone https://github.com/Larryvrh/ComfyUI-MiniMax-H3-Turbo custom_nodes/ComfyUI-MiniMax-H3-Turbo
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;装完重启 ComfyUI 再导入工作流。注意这份工作流走的是普通 &lt;code&gt;KSamplerSelect&lt;/code&gt; 采样器路径，并没有用节点包里的专用 Turbo Sampler，不要看到节点包里有采样器就自己改线。&lt;/p&gt;
&lt;p&gt;:::warning
仓库和工作流 JSON 都不包含模型权重，也没有记录作者的显卡型号、显存峰值和运行耗时。模型要自己按下一节的表去下；自己的机器能不能跑、跑多快，以实测为准，不要轻信任何「最低显存」口头承诺。
:::&lt;/p&gt;
&lt;h2&gt;四个模型文件加一个 LoRA：照表放目录&lt;/h2&gt;
&lt;p&gt;JSON 当前保存的选择如下，下载后严格按目录放，放错一级节点列表里就刷不出来：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;th&gt;模型文件&lt;/th&gt;
&lt;th&gt;存放目录&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;基础模型&lt;/td&gt;
&lt;td&gt;&lt;code&gt;minimax_h3_fl2va_pruned_int8_convrot.safetensors&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ComfyUI/models/diffusion_models/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文本编码器&lt;/td&gt;
&lt;td&gt;&lt;code&gt;qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ComfyUI/models/text_encoders/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;视频 VAE&lt;/td&gt;
&lt;td&gt;&lt;code&gt;minimax_h3_video_vae_fp16.safetensors&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ComfyUI/models/vae/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;音频 VAE&lt;/td&gt;
&lt;td&gt;&lt;code&gt;minimax_h3_audio_vae_fp32.safetensors&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ComfyUI/models/vae/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Turbo LoRA&lt;/td&gt;
&lt;td&gt;&lt;code&gt;minimax_h3_turbo_4step_ema_ckpt850.safetensors&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ComfyUI/models/loras/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个细节：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;两个 VAE 同放 &lt;code&gt;vae/&lt;/code&gt; 目录，一个管画面解码、一个管声音解码，缺了音频 VAE，成片就是哑的。&lt;/li&gt;
&lt;li&gt;文本编码器是 Qwen3-VL 32B 的量化版，H3 的提示词理解全靠它，别拿普通 CLIP 顶替。&lt;/li&gt;
&lt;li&gt;备齐文件后刷新模型列表或重启 ComfyUI，在总控面板逐项确认五个下拉框都选中了表里的文件。如果换用其他检查点，要按那个检查点自己的说明配置参数，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把不同版本的文件当成等效默认值混用&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;快速开始：六步跑出第一条片&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;从仓库下载 &lt;code&gt;video_minimax_h3_t2v_0909.json&lt;/code&gt;，拖进 ComfyUI 画布。&lt;/li&gt;
&lt;li&gt;按上一节装好 Turbo 节点包、备齐五个模型文件，确认画布上没有缺失节点、面板上没有模型报错。&lt;/li&gt;
&lt;li&gt;在左侧两个图像加载节点上传图片：上方接 &lt;code&gt;first_frame&lt;/code&gt;（首帧），下方接 &lt;code&gt;last_frame&lt;/code&gt;（尾帧）。&lt;/li&gt;
&lt;li&gt;在 &lt;code&gt;Image to Video (MiniMax H3)&lt;/code&gt; 面板填写提示词，描述首尾帧之间的动作、镜头变化与声音。JSON 自带的外层提示词是海怪掀船、泰坦踩踏的示例场景，直接替换成自己的即可；子流程内部还留着旧示例文字，那不是当前输入，不用管。&lt;/li&gt;
&lt;li&gt;确认 LoRA、步数、时长和分辨率（下一节逐项讲），点击运行。&lt;/li&gt;
&lt;li&gt;在右侧 &lt;code&gt;SaveVideo&lt;/code&gt; 节点查看输出。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;JSON 里不包含图片本体&amp;lt;/span&amp;gt;：文件里只存了作者本地的两个素材文件名（&lt;code&gt;HPmuyFwbYAALgM9.jfif&lt;/code&gt;、&lt;code&gt;HPmu4ASbQAAVr8D.jfif&lt;/code&gt;），你那边根本没有这两个文件，第 3 步必须重新上传自己的首尾帧，否则会直接报图片不存在。&lt;/p&gt;
&lt;h2&gt;三种模式切换：靠「绕过」，不是删节点&lt;/h2&gt;
&lt;p&gt;模式切换只取决于两个图像输入接没接：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;生成模式&lt;/th&gt;
&lt;th&gt;首帧 &lt;code&gt;first_frame&lt;/code&gt;&lt;/th&gt;
&lt;th&gt;尾帧 &lt;code&gt;last_frame&lt;/code&gt;&lt;/th&gt;
&lt;th&gt;用法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;首尾帧视频&lt;/td&gt;
&lt;td&gt;输入&lt;/td&gt;
&lt;td&gt;输入&lt;/td&gt;
&lt;td&gt;用两张图锁住视频的起始与结束画面&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;图生视频&lt;/td&gt;
&lt;td&gt;输入&lt;/td&gt;
&lt;td&gt;绕过 / 不输入&lt;/td&gt;
&lt;td&gt;只以首帧为起点，结尾交给提示词发挥&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文生视频&lt;/td&gt;
&lt;td&gt;绕过 / 不输入&lt;/td&gt;
&lt;td&gt;绕过 / 不输入&lt;/td&gt;
&lt;td&gt;不用任何图像条件，纯文字生成&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这里的「绕过」指的是让对应图片不再传入子流程：可以断开那条图像输入连线；如果用节点的 Bypass 操作，也要确认该接口确实没有再收到图片。切换到文生视频后就不用准备任何图片素材。它和动画短片流水线里「首尾帧定格」的思路一致，&lt;a href=&quot;/posts/ai-muse-animated-film/&quot;&gt;AI 动画短片流水线&lt;/a&gt; 里对首尾帧关键帧的用法可以互相参照。&lt;/p&gt;
&lt;h2&gt;总控参数：面板上这几项都在管什么&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;当前保存值&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;prompt&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;中文海怪 / 泰坦场景&lt;/td&gt;
&lt;td&gt;内容、动作、镜头和声音的描述&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;noise_seed&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;614289519754737&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;噪声种子；想复现还要保持其他输入与环境一致&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;lora_name&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;minimax_h3_turbo_4step_ema_ckpt850.safetensors&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Turbo LoRA 文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;steps&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;8&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;实际采样步数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;duration&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;6&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;目标秒数，实际帧数会按下文公式对齐&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;aspect_ratio&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;16:9 (Widescreen)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;目标画面比例&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;megapixels&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0.4&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;当前计算分辨率为 &lt;code&gt;864 × 480&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;unet_name&lt;/code&gt; / &lt;code&gt;clip_name&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;见模型表&lt;/td&gt;
&lt;td&gt;基础模型与文本编码器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;vae_name&lt;/code&gt; / &lt;code&gt;audio_vae&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;见模型表&lt;/td&gt;
&lt;td&gt;视频 VAE 与音频 VAE&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;最容易踩的坑在步数：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;LoRA 文件名里写着 &lt;code&gt;4step&lt;/code&gt;，不代表采样步数会自动变成 4&amp;lt;/span&amp;gt;。实际步数只认面板上的 &lt;code&gt;steps&lt;/code&gt;，当前保存值是 8。仓库图解里展示的是另一组示例设置（6 步、目标 5 秒），图解只用来说明参数含义，默认值一律以 JSON 和本表为准。&lt;/p&gt;
&lt;h2&gt;两条硬规矩：分辨率按面积算，帧数按 17k+5 对齐&lt;/h2&gt;
&lt;h3&gt;分辨率：先算总面积，再对齐 32 的倍数&lt;/h3&gt;
&lt;p&gt;分辨率节点按 &lt;code&gt;megapixels × 1024 × 1024&lt;/code&gt; 算出目标总面积，结合宽高比拆成宽和高，再把宽高分别舍入到 32 的倍数。所以实际比例和像素面积会和设定值略有偏差，这是算法使然。16:9 下四档常用值算出的尺寸是：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;宽高比&lt;/th&gt;
&lt;th&gt;百万像素&lt;/th&gt;
&lt;th&gt;计算分辨率&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;16:9&lt;/td&gt;
&lt;td&gt;0.2&lt;/td&gt;
&lt;td&gt;608 × 352&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;16:9&lt;/td&gt;
&lt;td&gt;0.4&lt;/td&gt;
&lt;td&gt;864 × 480&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;16:9&lt;/td&gt;
&lt;td&gt;0.6&lt;/td&gt;
&lt;td&gt;1056 × 608&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;16:9&lt;/td&gt;
&lt;td&gt;0.8&lt;/td&gt;
&lt;td&gt;1216 × 672&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;显存吃紧先降这一项：从 0.4 降到 0.2，像素量直接减半，比改其他参数都立竿见影。&lt;/p&gt;
&lt;h3&gt;帧数：6 秒实际是 158 帧、约 6.58 秒&lt;/h3&gt;
&lt;p&gt;时长换算用的是下面这条表达式，&lt;code&gt;a&lt;/code&gt; 是目标秒数，帧率固定 24 fps：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;max(5, round(a * 24)) + (5 - (max(5, round(a * 24)) % 17)) % 17
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;说人话就是：先把秒数换成帧数，再向上对齐到最近的 &lt;code&gt;17k + 5&lt;/code&gt;。默认 6 秒先换算出 144 帧，向上对齐后是 &lt;strong&gt;158 帧&lt;/strong&gt;，按 24 fps 播出来约 &lt;strong&gt;6.58 秒&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;输出时长不等于填入的秒数，是帧数对齐的必然结果，不是工作流出了 bug。&amp;lt;/span&amp;gt;剪辑时按实际帧数算时间点，别按面板上的目标秒数硬对。&lt;/p&gt;
&lt;h2&gt;子流程内部参数：一般不用动，动之前先看懂&lt;/h2&gt;
&lt;p&gt;以下设置都藏在子流程里，要双击进入子流程才能改：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;设置&lt;/th&gt;
&lt;th&gt;当前值&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;采样器&lt;/td&gt;
&lt;td&gt;&lt;code&gt;res_multistep&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;调度器&lt;/td&gt;
&lt;td&gt;&lt;code&gt;simple&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;降噪强度&lt;/td&gt;
&lt;td&gt;&lt;code&gt;1.0&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;LoRA 强度&lt;/td&gt;
&lt;td&gt;&lt;code&gt;1.0&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;LoRA &lt;code&gt;low_vram&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;false&lt;/code&gt;（关闭）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;分辨率倍数 &lt;code&gt;multiple&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;32&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;视频帧率&lt;/td&gt;
&lt;td&gt;&lt;code&gt;24 fps&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;视频位深&lt;/td&gt;
&lt;td&gt;&lt;code&gt;8&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;其中只有一个开关日常可能用到：&lt;code&gt;low_vram&lt;/code&gt;。显存实在不够时可以进子流程把它打开，让 LoRA 以低显存方式加载；代价是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;可能影响量化模型的画面锐度&amp;lt;/span&amp;gt;，开之前先用同一组参数各跑一条对比，再决定要不要长期开。其余参数是和 Turbo LoRA 配套调好的组合，尤其采样器 &lt;code&gt;res_multistep&lt;/code&gt; 加调度器 &lt;code&gt;simple&lt;/code&gt; 这一对，没实测对比不要换。&lt;/p&gt;
&lt;h2&gt;输出位置：默认落在 output/video/&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;SaveVideo&lt;/code&gt; 节点当前的文件名前缀是 &lt;code&gt;video/MiniMax_H3_h9&lt;/code&gt;，格式与编码器都是 &lt;code&gt;auto&lt;/code&gt;，由保存节点自动决定扩展名。用默认输出目录时，成片保存在：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ComfyUI/output/video/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果启动 ComfyUI 时自定义过输出目录，以实际配置为准。找不到成片先确认这个前缀目录，而不是满硬盘搜文件名。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;导入后有缺失节点&lt;/strong&gt;
先看缺的是哪类：缺 &lt;code&gt;MiniMaxH3TurboLoRA&lt;/code&gt; 是 Turbo 节点包没装或没重启；缺 &lt;code&gt;MiniMaxH3ImageToVideo&lt;/code&gt;、&lt;code&gt;ResolutionSelector&lt;/code&gt;、&lt;code&gt;ComfyMathExpression&lt;/code&gt; 这类核心节点，是 ComfyUI 版本太旧或启动时导入失败，去启动日志里搜报错行。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;模型列表里找不到文件&lt;/strong&gt;
对照模型表逐项查目录和文件名：基础模型在 &lt;code&gt;diffusion_models/&lt;/code&gt;、文本编码器在 &lt;code&gt;text_encoders/&lt;/code&gt;、两个 VAE 在 &lt;code&gt;vae/&lt;/code&gt;、LoRA 在 &lt;code&gt;loras/&lt;/code&gt;。放对后刷新列表或重启，再在总控面板重新选择。记住 JSON 不打包模型权重，文件不在本地，列表里永远不会有。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;图片不存在报错&lt;/strong&gt;
JSON 里存的是作者本地的素材文件名，你的机器上没有。在两个图像加载节点重新上传自己的首帧、尾帧即可。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;显存不足（OOM）&lt;/strong&gt;
三档处理顺序：先把 &lt;code&gt;megapixels&lt;/code&gt; 从 0.4 降到 0.2；还不够就缩短 &lt;code&gt;duration&lt;/code&gt;；最后再进子流程打开 LoRA 的 &lt;code&gt;low_vram&lt;/code&gt;，但要接受画面锐度可能下降，改完同参数对比一条再定。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;输出时长比设置值长&lt;/strong&gt;
帧数对齐造成的，6 秒变约 6.58 秒是正常现象，公式和换算过程见上文「帧数」一节，不是参数没生效。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;声音异常或没有声音&lt;/strong&gt;
先确认音频 VAE 文件在位且面板里选对了，再检查音频 VAE、ComfyUI 本体和 Turbo 节点包三者的版本是否匹配。这份工作流用的是普通采样器路径，跨大版本组合的兼容性没有官方保证，升级其中任何一个组件后，先跑一条短片验证声音再批量生产。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这份工作流适合已经装好 ComfyUI、想直接上手 H3 又不想从零连节点的人：拖 JSON、装一个 Turbo 节点包、按表放五个模型文件、上传首尾帧、改提示词，就能跑通首尾帧、图生、文生三种模式。用的时候记住三件事：步数只认面板上的 &lt;code&gt;steps&lt;/code&gt;，不认 LoRA 文件名里的 &lt;code&gt;4step&lt;/code&gt;；时长按 &lt;code&gt;17k + 5&lt;/code&gt; 对齐，输出比设定略长是常态；分辨率按百万像素调，显存不够先降它。写词交给 &lt;a href=&quot;/posts/ai-minimax-director/&quot;&gt;MiniMaxDirector&lt;/a&gt;，执行交给这份工作流，H3 的一条完整流水线就齐了。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：Modern Web Guidance 让编程助手跟上现代 Web</title><link>https://www.anexns.cloudns.org/posts/ai-modern-web-guidance/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-modern-web-guidance/</guid><description>Modern Web Guidance 是 Chrome、Edge、Firefox 与 MDN 团队共同维护的技能包：把 250 个现代 Web 特性的专家指南与浏览器兼容数据直接喂进编程助手的上下文，让它少写老派代码、多用平台原生能力。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：AI 写前端，为什么总是一股「老味」&lt;/h2&gt;
&lt;p&gt;让编程助手写个弹窗，它给你手写遮罩层、焦点管理和关闭动画，洋洋洒洒两百行 JavaScript——可浏览器早就有了原生的 &lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt; 元素和 Popover API，几行代码的事。让它做个响应式卡片布局，它掏出一套媒体查询加浮动兜底，而容器查询（Container Queries）已经全线浏览器支持好几年了。&lt;/p&gt;
&lt;p&gt;这不是模型「笨」，是两个结构性原因：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;训练数据里旧代码太多&lt;/strong&gt;。大模型的语料横跨二十多年的 Web 开发史，老派写法在数量上碾压现代写法。模型按概率续写，自然优先吐出它见得最多的那一套：用一堆 JS 重造平台早就原生支持的轮子。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;知道 API 存在，不等于会写生产级代码&lt;/strong&gt;。就算模型「知道」某个新 API，它脑子里也缺少真实项目里那种高密度的现代实现范式——边界情况怎么处理、兜底怎么写、和无障碍怎么配合。知道和会用之间，差着一层专家经验。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;本篇主线：认识一个专门补这层经验的技能包——Modern Web Guidance。它不换模型、不改提示词技巧，而是把 Web 平台的专家指南和浏览器兼容数据直接嵌进编程助手的上下文里，从源头把助手往现代写法上带。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/GoogleChrome/modern-web-guidance&lt;/p&gt;
&lt;h2&gt;它是什么：四家一起维护的「现代 Web 教练」&lt;/h2&gt;
&lt;p&gt;Modern Web Guidance 是一套给编程助手用的技能（Skills），由 &lt;strong&gt;Google Chrome 团队牵头，Microsoft Edge、Mozilla Firefox 与 MDN 团队共同维护&lt;/strong&gt;，再加上 Web 开发社区的贡献。这个出身很重要：指南内容不是某个博主的心得，而是浏览器厂商和文档标准方的一手口径——哪些特性已经 Baseline 全线可用、哪些还在实验阶段，他们最清楚。&lt;/p&gt;
&lt;p&gt;它干的事可以拆成三块：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;现代浏览器 API 的正确结构&lt;/strong&gt;：专门纠正模型最容易用错的那批 API，给出规范的写法骨架。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;性能与无障碍优先&lt;/strong&gt;：优先推荐能被浏览器底层优化、且自带无障碍语义的平台级方案，而不是 JS 模拟出来的效果。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;负责任的兜底&lt;/strong&gt;：新特性用不了的老浏览器怎么办，它给的是轻量、针对性的小兜底，而不是动不动引一个重型 polyfill 或老牌类库。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;它和本系列上一篇的 &lt;a href=&quot;/posts/ai-skill-seekers/&quot;&gt;Skill Seekers&lt;/a&gt; 是互补关系：Skill Seekers 是把任意文档炼成技能的「加工厂」，Modern Web Guidance 则是浏览器厂商亲自下场、已经炼好的「成品技能」——一个造技能，一个直接是技能。&lt;/p&gt;
&lt;h2&gt;快速开始：装上，或者先白嫖三条命令&lt;/h2&gt;
&lt;p&gt;安装走交互式向导，一条命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx modern-web-guidance@latest install
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;向导会识别你在用的编程助手并把技能装到位。后续更新同样简单：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx modern-web-guidance@latest update
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;不想装？它的 CLI 本身就能直接试，三条命令覆盖三个典型动作。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一条：搜指南。&lt;/strong&gt; 用自然语言描述你想做的事，它返回最相关的指南：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx modern-web-guidance@latest search &quot;animate a dialog modal backdrop&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第二条：按 ID 取指南全文。&lt;/strong&gt; 搜索结果里拿到指南 ID 后，把完整指南（代码范式、坑点、兜底写法）取出来读：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx modern-web-guidance@latest retrieve &quot;animate-to-from-top-layer&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第三条：扫代码库里的遗留模式。&lt;/strong&gt; 对着一个老项目跑一遍，它会指出哪些写法可以用现代平台能力替换——这是给存量项目做现代化盘点最顺手的入口：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx modern-web-guidance@latest legacy-scan .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;除了官方安装器，它还适配了几乎所有主流助手的分发方式，挑你顺手的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# Vercel Skills CLI
npx skills add GoogleChrome/modern-web-guidance

# GitHub CLI
gh skill install GoogleChrome/modern-web-guidance
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Claude Code、Codex 等则有各自的插件市场装法（仓库 README 里有逐个助手的命令清单）。安装时还能用 &lt;code&gt;--choose&lt;/code&gt; 只选需要的技能包：主包 &lt;code&gt;modern-web-guidance&lt;/code&gt; 管现代 API、布局与性能，另一个 &lt;code&gt;chrome-extensions&lt;/code&gt; 包专管 Chrome 扩展开发（Manifest V3、后台 Service Worker、扩展 API 与上架发布）。&lt;/p&gt;
&lt;h2&gt;安装与分发大全：每家助手都有自己的装法&lt;/h2&gt;
&lt;p&gt;快速开始里给的是「通用入口」，但这个技能包的分发做得相当全：仓库里同时带了 Claude Code、Codex、Cursor、Grok 等助手的插件清单文件，还有 Gemini 的扩展清单。按你用的助手对号入座：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;安装方式&lt;/th&gt;
&lt;th&gt;命令或入口&lt;/th&gt;
&lt;th&gt;适合谁&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;官方安装向导&lt;/td&gt;
&lt;td&gt;&lt;code&gt;npx modern-web-guidance@latest install&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不确定装哪种时用它，向导会识别你的助手&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Vercel Skills CLI&lt;/td&gt;
&lt;td&gt;&lt;code&gt;npx skills add GoogleChrome/modern-web-guidance&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;已经在用 skills 生态统一管技能的人&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GitHub CLI&lt;/td&gt;
&lt;td&gt;&lt;code&gt;gh skill install GoogleChrome/modern-web-guidance&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;习惯用 &lt;code&gt;gh&lt;/code&gt; 管一切的人&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Claude Code 插件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/plugin marketplace add GoogleChrome/modern-web-guidance&lt;/code&gt; 后 &lt;code&gt;/plugin install modern-web-guidance@googlechrome&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Claude Code 用户，可在插件菜单里开启 AutoUpdate&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;OpenAI Codex 插件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;codex plugin marketplace add GoogleChrome/modern-web-guidance&lt;/code&gt; 后 &lt;code&gt;codex plugin add modern-web-guidance@googlechrome&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Codex 用户&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GitHub Copilot CLI 插件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/plugin marketplace add GoogleChrome/modern-web-guidance&lt;/code&gt; 后 &lt;code&gt;/plugin install modern-web-guidance@googlechrome&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Copilot CLI 用户&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Google Antigravity&lt;/td&gt;
&lt;td&gt;&lt;code&gt;agy plugin install https://github.com/GoogleChrome/modern-web-guidance&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Antigravity 用户&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Grok Build CLI&lt;/td&gt;
&lt;td&gt;&lt;code&gt;grok plugin install https://github.com/GoogleChrome/modern-web-guidance --trust&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Grok Build 用户&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Kimi Code&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/plugins install https://github.com/GoogleChrome/modern-web-guidance&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Kimi Code 用户&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;装的时候还有个选择题：&lt;strong&gt;技能包要装哪个&lt;/strong&gt;。用 &lt;code&gt;--choose&lt;/code&gt; 可以挑：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx modern-web-guidance@latest install --choose
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;modern-web-guidance&lt;/code&gt;（主包，技能描述约 205 tokens）：现代浏览器 API、布局与性能的全面指南，做网站就装它。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;chrome-extensions&lt;/code&gt;（约 175 tokens）：专管 Chrome 扩展开发——Manifest V3、后台 Service Worker、扩展 API 与 Chrome 应用商店上架发布。不做扩展的人可以不装，省下常驻上下文。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;更新节奏也要形成习惯。用官方安装器装的，跑一条 &lt;code&gt;update&lt;/code&gt; 即可；插件方式装的，按各自助手的插件更新流程走（Claude Code 可以在插件菜单里给它开 AutoUpdate，再配合 &lt;code&gt;/reload-plugins&lt;/code&gt; 重载）。为什么强调更新：指南内容跟着 Web 平台的发布列车走，特性从「易变」转「Baseline」、新指南上线，都要靠更新才能吃到。把它当成和升级浏览器同级别的例行动作就行。&lt;/p&gt;
&lt;h2&gt;内容家底：250 个特性、六大学科&lt;/h2&gt;
&lt;p&gt;它覆盖的是过去几年 Web 平台攒下的新特性，一共 &lt;strong&gt;250 个&lt;/strong&gt;，按技术域分成三摞：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;技术域&lt;/th&gt;
&lt;th&gt;特性数&lt;/th&gt;
&lt;th&gt;内容倾向&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;CSS 与布局&lt;/td&gt;
&lt;td&gt;140&lt;/td&gt;
&lt;td&gt;布局系统、动画、色彩、滚动、排版&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HTML 与 DOM&lt;/td&gt;
&lt;td&gt;36&lt;/td&gt;
&lt;td&gt;原生元素、弹窗、表单控件、DOM 行为&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;JavaScript 与 API&lt;/td&gt;
&lt;td&gt;74&lt;/td&gt;
&lt;td&gt;浏览器 API、调度、内置 AI、设备能力&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;按「学科」组织的六大核心方向，才是它真正的使用地图：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;学科&lt;/th&gt;
&lt;th&gt;解决什么&lt;/th&gt;
&lt;th&gt;代表特性&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;用户体验&lt;/td&gt;
&lt;td&gt;顺滑的视觉状态与转场&lt;/td&gt;
&lt;td&gt;View Transitions 视图过渡、滚动驱动动画、&lt;code&gt;scrollbar-color&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;CSS 布局&lt;/td&gt;
&lt;td&gt;现代布局与样式系统&lt;/td&gt;
&lt;td&gt;容器查询、Subgrid 子网格、&lt;code&gt;oklch&lt;/code&gt; 现代色彩空间、&lt;code&gt;text-wrap&lt;/code&gt; 排版调优&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;性能&lt;/td&gt;
&lt;td&gt;让页面快且稳&lt;/td&gt;
&lt;td&gt;推测预加载、INP 诊断、&lt;code&gt;scheduler.yield&lt;/code&gt; 任务调度&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;表单与 UI&lt;/td&gt;
&lt;td&gt;原生组件替代 JS 模拟&lt;/td&gt;
&lt;td&gt;Popover API、锚点定位（Anchor Positioning）、&lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt;、&lt;code&gt;:user-invalid&lt;/code&gt; 校验、字段自动尺寸&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;无障碍&lt;/td&gt;
&lt;td&gt;屏幕阅读器与键盘可达&lt;/td&gt;
&lt;td&gt;焦点管理、内容导航与可发现性、原生语义&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;浏览器内置 AI&lt;/td&gt;
&lt;td&gt;端侧本地模型能力&lt;/td&gt;
&lt;td&gt;本地翻译 API、摘要 API、语言检测 API&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;对照这张表就能看出它的取向：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;它教的不是「新语法」，而是「这件事现在应该用平台的哪个原生能力做」&amp;lt;/span&amp;gt;——弹窗用 Popover 而不是 div 模拟，提示气泡用锚点定位而不是 JS 算坐标，长任务用 &lt;code&gt;scheduler.yield&lt;/code&gt; 切分而不是硬扛主线程。每一个特性都是一次「把 JS 轮子还给浏览器」的机会。&lt;/p&gt;
&lt;p&gt;:::warning
六大学科里「浏览器内置 AI」这块要特别留神：本地翻译、摘要这类端侧 API 目前仍属较新的能力，浏览器支持面有限。指南会标注它们的成熟度，但&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;千万别不看兼容状态就把实验性 API 写进生产主流程&amp;lt;/span&amp;gt;，具体怎么安全采用，看后面「安全采用」一节。
:::&lt;/p&gt;
&lt;h2&gt;六大学科逐个深挖：每科都在治一种老毛病&lt;/h2&gt;
&lt;p&gt;上面那张表是地图，这一节逐科走一遍。每科的老毛病都一样：模型不是不知道新方案，而是默认先伸手去拿旧的那套。下面每个对照都是指南里真实存在的条目（括号里是对应的指南 ID，装好后可以 &lt;code&gt;retrieve&lt;/code&gt; 出来看全文）。&lt;/p&gt;
&lt;h3&gt;用户体验：动画交给合成器，别再手写编排&lt;/h3&gt;
&lt;p&gt;老毛病：页面切换、元素进出场全靠 JS 手动编排——加类名、监听 transitionend、算 FLIP 位移，代码又长又容易抖。现代平台的做法是把动画声明出来、交给浏览器合成器跑：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;// 老写法：手动记录元素位置、算位移、逐帧推动画
// （FLIP 四步：First / Last / Invert / Play，几十行起步）

// 现代写法：状态切换包进 View Transitions，浏览器自动做形变过渡
document.startViewTransition(() =&amp;gt; renderNewState());
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;滚动相关的效果同理。以前做阅读进度条要监听 &lt;code&gt;scroll&lt;/code&gt; 事件再 &lt;code&gt;requestAnimationFrame&lt;/code&gt; 节流计算，现在滚动驱动动画（指南 &lt;code&gt;scroll-progress-indicator&lt;/code&gt;）直接把动画进度绑到滚动位置上，一行监听都不用写。弹窗、抽屉这类进出 top layer 的元素进出场动画，有专门的指南 &lt;code&gt;animate-to-from-top-layer&lt;/code&gt;（下一节会把它整条拆开讲）。还有一条容易被忽略的：所有动效都要尊重 &lt;code&gt;prefers-reduced-motion&lt;/code&gt;——指南 &lt;code&gt;motion&lt;/code&gt; 专门讲怎么让动画留在合成器上跑、同时给晕动症用户留好降级。&lt;/p&gt;
&lt;h3&gt;CSS 布局：组件应该看自己的宽度，不是看屏幕的宽度&lt;/h3&gt;
&lt;p&gt;老毛病最典型：一个卡片组件，在侧边栏里要窄版、在主栏里要宽版，于是媒体查询断点越堆越多，组件和页面布局死死耦合。容器查询（指南 &lt;code&gt;size-aware-styling&lt;/code&gt;、&lt;code&gt;responsive-design&lt;/code&gt;）把判断依据从视口换成组件自己的容器宽度，组件从此自适应、可复用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/* 老写法：断点跟着屏幕走，组件搬个位置就要改样式 */
@media (max-width: 900px) { .card { flex-direction: column; } }
@media (max-width: 600px) { .card { font-size: 14px; } }

/* 现代写法：组件只关心自己有多宽 */
.card-wrap { container-type: inline-size; }
@container (min-width: 420px) {
  .card { flex-direction: row; }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;同科的其它「还轮子」动作还有：用 &lt;code&gt;subgrid&lt;/code&gt; 让嵌套网格的子项直接对齐父网格的轨道，省掉一层层手算；用 &lt;code&gt;oklch&lt;/code&gt; 和相对颜色语法从一个品牌色推导整套色阶，而不是手工调十几个十六进制值；标题排版用 &lt;code&gt;text-wrap: balance&lt;/code&gt; 让浏览器自动均衡断行，告别手写 &lt;code&gt;&amp;lt;br&amp;gt;&lt;/code&gt;；给手风琴、展开卡片做高度动画，以前要 JS 测高，现在 &lt;code&gt;interpolate-size: allow-keywords&lt;/code&gt; 让 &lt;code&gt;height: auto&lt;/code&gt; 也能过渡（指南 &lt;code&gt;animate-to-intrinsic-sizes&lt;/code&gt;）。还有 &lt;code&gt;:has()&lt;/code&gt;（指南 &lt;code&gt;style-parent-with-has&lt;/code&gt;）让「根据子元素状态给父元素上样式」这种以前必须 JS 的活儿回归纯 CSS。&lt;/p&gt;
&lt;h3&gt;性能：先量出来，再对症下药&lt;/h3&gt;
&lt;p&gt;这一科的特点是「诊断指南」和「处方指南」成对出现。先说诊断：页面点了没反应、INP（Interaction to Next Paint）难看，先用指南 &lt;code&gt;identify-inp-causes&lt;/code&gt; 定位是哪段 JS、哪次布局重算在拖后腿，再对着处方改：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;// 老写法：一个大循环同步跑完，主线程冻住，用户点什么都没反应
for (const item of hugeList) { process(item); }

// 现代写法：切分长任务，定期把主线程还给浏览器（指南 break-up-long-tasks）
for (const item of hugeList) {
  process(item);
  if (needsToYield()) await scheduler.yield();
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;资源加载侧的老毛病是「一视同仁」：所有图片都懒加载，结果首屏大图（LCP）也被拖慢；或者所有资源都高优先级，互相抢带宽。指南 &lt;code&gt;optimize-image-priority&lt;/code&gt; 的口径很明确：LCP 候选图给 &lt;code&gt;fetchpriority=&quot;high&quot;&lt;/code&gt;，屏外图片和视频才 &lt;code&gt;loading=&quot;lazy&quot;&lt;/code&gt;（指南 &lt;code&gt;lazy-load-video-and-audio&lt;/code&gt;）。再往前一步，下一页还没点就先备好：推测规则（Speculation Rules，指南 &lt;code&gt;improve-next-page-load-performance&lt;/code&gt;）可以声明式地预取甚至预渲染用户大概率要去的页面，点击时近乎瞬开——而且它属于「增强型」特性，老浏览器直接忽略，零风险。长列表、信息流页面则用 &lt;code&gt;content-visibility: auto&lt;/code&gt;（指南 &lt;code&gt;defer-rendering-heavy-content&lt;/code&gt;）跳过屏外内容的渲染。埋点上报也有专门指南（&lt;code&gt;batch-analytics-events&lt;/code&gt;、&lt;code&gt;full-session-analytics&lt;/code&gt;）：攒批、延后到用户离开时用 &lt;code&gt;fetchLater()&lt;/code&gt; 一次发走，别让每个事件都去抢网络。&lt;/p&gt;
&lt;h3&gt;表单与 UI：原生组件早就长大了&lt;/h3&gt;
&lt;p&gt;这是「JS 轮子」重灾区。下拉层、气泡提示、日历选择器，前端们用 div 模拟了二十年，定位、点击外部关闭、Esc 关闭、焦点管理，每样都要手写，每样都容易漏。平台现在的原生答案是成套的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;!-- 老写法：一个 div + 一大坨 JS（开关状态、外部点击监听、Esc 处理、焦点回收） --&amp;gt;
&amp;lt;div class=&quot;dropdown&quot; id=&quot;menu&quot;&amp;gt;...&amp;lt;/div&amp;gt;

&amp;lt;!-- 现代写法：Popover 属性 + 一个按钮，开关/关闭/层级全是浏览器管 --&amp;gt;
&amp;lt;button popovertarget=&quot;menu&quot;&amp;gt;菜单&amp;lt;/button&amp;gt;
&amp;lt;div id=&quot;menu&quot; popover&amp;gt;...&amp;lt;/div&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;气泡提示的定位同理：以前 JS 测算坐标、监听滚动重定位、处理边缘翻转，现在锚点定位（Anchor Positioning）把提示元素在 CSS 里「锚」到触发元素上，翻转交给浏览器。表单校验的老毛病是时机不对——页面一打开就一片红，或者用 &lt;code&gt;:invalid&lt;/code&gt; 在用户还没输入时就报错；现代口径是 &lt;code&gt;:user-invalid&lt;/code&gt;：只在用户交互过之后才标错（指南 &lt;code&gt;validate-input-after-interaction&lt;/code&gt;、&lt;code&gt;required-field-feedback&lt;/code&gt;），和屏幕阅读器的报错播报还要同步（这条归无障碍科，指南 &lt;code&gt;accessible-error-announcement&lt;/code&gt;）。文本框高度以前靠 JS 实时测 &lt;code&gt;scrollHeight&lt;/code&gt;，现在 &lt;code&gt;field-sizing: content&lt;/code&gt; 一行搞定（指南 &lt;code&gt;form-fields-automatically-fit-contents&lt;/code&gt;）。登录、支付、地址这些高频表单，指南直接给了带正确 &lt;code&gt;autocomplete&lt;/code&gt; 属性的完整范式（&lt;code&gt;autofill-sign-in-form&lt;/code&gt;、&lt;code&gt;autofill-payment-form&lt;/code&gt;、&lt;code&gt;autofill-address-form&lt;/code&gt;）——自动填充对上了，用户少打一半字。连短信验证码都有专门指南（&lt;code&gt;sms-otp-form&lt;/code&gt;，用 WebOTP 自动提取验证码）。还有个中文用户特别容易踩的坑：输入法组字时按回车被误提交——指南 &lt;code&gt;ime-safe-enter-submit&lt;/code&gt; 专门讲这个。&lt;/p&gt;
&lt;h3&gt;无障碍：不是加分项，是原生语义的副产品&lt;/h3&gt;
&lt;p&gt;这一科和前面几科是连体的：用原生 &lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt;、Popover、原生表单控件，键盘可达、焦点管理、读屏语义大半是白送的；用 div 模拟，每一样都要自己补，还经常补错。指南里这一科条目不多但都很要害：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;报错要让读屏用户在对的时机听到&lt;/strong&gt;。视觉上用 &lt;code&gt;:user-invalid&lt;/code&gt; 在交互后标红，程序状态上同步 &lt;code&gt;aria-invalid&lt;/code&gt;，两边对齐，读屏用户才不会一进页面就被报错淹没（指南 &lt;code&gt;accessible-error-announcement&lt;/code&gt;）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CSS 生成内容别坑读屏&lt;/strong&gt;。&lt;code&gt;::before&lt;/code&gt; / &lt;code&gt;::after&lt;/code&gt; 塞的图标字体、装饰字符会被某些读屏软件读出来，指南 &lt;code&gt;accessible-generated-content&lt;/code&gt; 讲怎么给生成内容配替代文本或正确隐藏。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;尊重系统文字缩放&lt;/strong&gt;。全站字号用 px 写死，等于无视用户在系统里调大的字体；用 rem 并尊重操作系统的文字缩放偏好（指南 &lt;code&gt;respect-os-text-scale&lt;/code&gt;），低视力用户才能正常用。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;自定义组件别裸奔&lt;/strong&gt;。真要造自定义元素，用 ElementInternals 的 ARIA 反射和 &lt;code&gt;delegatesFocus&lt;/code&gt; 把语义和焦点处理做对（指南 &lt;code&gt;accessible-web-components&lt;/code&gt;），而不是东拼西凑几个 &lt;code&gt;role&lt;/code&gt; 了事。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;浏览器内置 AI：能端侧跑的，别都往云上送&lt;/h3&gt;
&lt;p&gt;最新也最需要冷静看的一科。Chrome 正在把端侧模型能力做成 Web API：语言检测（指南 &lt;code&gt;language-detection&lt;/code&gt;）、翻译（指南 &lt;code&gt;translator&lt;/code&gt;）、摘要（指南 &lt;code&gt;summarizer&lt;/code&gt;），还有更通用的 Prompt API（指南 &lt;code&gt;language-model&lt;/code&gt;，支持流式输出、结构化 JSON 响应和多轮会话管理）。老写法是这类需求一律调云端 API——按量付费、数据出境、离线即残废；端侧 API 能跑通的场景（评论区语言识别、文章一键摘要、多语言站点的即时翻译），本地零成本、零延迟、数据不出设备。&lt;/p&gt;
&lt;p&gt;但这一科的指南同时也是「安全采用」策略的重点关照对象：这些 API 大多还新，支持面以 Chrome 为主，指南会如实标注成熟度，正确姿势是把它们当增强——有就用、没有就回退到云端或干脆不提供这个功能，而不是把主流程押在上面。&lt;/p&gt;
&lt;h2&gt;它怎么工作：本地搜索、按需取指南、评测剪枝&lt;/h2&gt;
&lt;p&gt;装好之后，日常使用你其实感知不到它——流程是助手在后台自己跑的：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;激活&lt;/strong&gt;：你给助手派了个 Web 相关的活，它判断任务相关，激活 &lt;code&gt;modern-web-guidance&lt;/code&gt; 技能，并被指示用它的 CLI 查平台问题。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;本地语义搜索&lt;/strong&gt;：助手执行 &lt;code&gt;modern-web-guidance search &quot;&amp;lt;查询&amp;gt;&quot;&lt;/code&gt;。搜索跑在本机，靠一个离线、零依赖的嵌入模型加 BM25 检索引擎匹配最相关的指南——&lt;strong&gt;全程不联网、不需要 API Key&lt;/strong&gt;，npm 包自包含、无额外依赖，延迟低，供应链面也小。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;取指南进上下文&lt;/strong&gt;：助手再用 &lt;code&gt;retrieve &amp;lt;指南 ID&amp;gt;&lt;/code&gt; 把命中的指南拉进上下文窗口——里面是成段的目标代码范式、已知的坑和兜底写法，助手照着这个写，而不是照着训练数据的老习惯写。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;有两个设计细节值得单独说：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一是指南按 Token 效率裁剪。&lt;/strong&gt; 指南不是把 MDN 整页塞进来。维护方跑评测来识别「模型本来就已经会」的内容并剪掉，只保留模型真正缺的那部分经验密度。上下文窗口寸土寸金，喂得准比喂得多重要。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二是有效性有评测背书，不是自我感觉。&lt;/strong&gt; 他们搭了完整的评测闭环：拿真实 Web 应用当考场，给出不点名任何 API 的真实需求（比如「让我的图片加载更快」），用 Playwright 检查器验证产出是否真的用了对的现代方案，再对比同一助手开/关技能的通过率。近期快照里，几个主流助手在两百多个任务上的通过率普遍从 50% 多提升到 80%–90% 多，也就是二三十个百分点的实打实提升。指南哪里没帮上忙，评测会暴露出来，内容随之迭代——这也是它敢说「经验密度」的底气。&lt;/p&gt;
&lt;h2&gt;一条指南的全程拆解：从搜到用，是什么样&lt;/h2&gt;
&lt;p&gt;抽象流程讲多了没感觉，拿官方快速开始里用的那条指南走一遍全程：给对话框的背景遮罩做进出场动画。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步，搜。&lt;/strong&gt; 你（或者你的助手）想做的是「dialog 打开时遮罩淡入、关闭时淡出」，搜的是任务描述，不是 API 名：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx modern-web-guidance@latest search &quot;animate a dialog modal backdrop&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;命中的指南里有一条 &lt;code&gt;animate-to-from-top-layer&lt;/code&gt;——专门讲怎么给 dialog、popover、tooltip 这类进出「顶层」（top layer）的元素做进场/退场动画。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二步，取。&lt;/strong&gt; 把指南全文拉进上下文：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx modern-web-guidance@latest retrieve &quot;animate-to-from-top-layer&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;指南的结构大致是四段：&lt;strong&gt;目标范式&lt;/strong&gt;（推荐的目标代码长什么样）、&lt;strong&gt;为什么这样写&lt;/strong&gt;（平台机制：元素进 top layer 前是 &lt;code&gt;display: none&lt;/code&gt;，普通 transition 根本没机会触发）、&lt;strong&gt;坑点&lt;/strong&gt;（退场动画最容易翻车的地方）、&lt;strong&gt;兜底&lt;/strong&gt;（不支持的浏览器怎么优雅降级）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三步，看代码怎么变。&lt;/strong&gt; 这个需求的老写法之所以难看，是因为要靠 JS 手动续命：关闭时先加一个 &lt;code&gt;.closing&lt;/code&gt; 类播退场动画，&lt;code&gt;setTimeout&lt;/code&gt; 等动画播完再真正关掉，还要防用户连点。指南给的现代范式把这些全收进 CSS：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/* 现代范式：进场起点、离散属性过渡，一次交代清楚 */
dialog {
  transition:
    opacity 0.25s ease-out,
    transform 0.25s ease-out,
    overlay 0.25s allow-discrete,
    display 0.25s allow-discrete;
}
dialog::backdrop {
  transition:
    opacity 0.25s ease-out,
    overlay 0.25s allow-discrete,
    display 0.25s allow-discrete;
}
/* @starting-style 定义元素「第一帧」的样子，进场动画才有起点 */
@starting-style {
  dialog[open] {
    opacity: 0;
    transform: translateY(10px);
  }
  dialog[open]::backdrop {
    opacity: 0;
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三个关键点，全是模型凭训练数据最容易漏的：一是 &lt;code&gt;@starting-style&lt;/code&gt; 提供进场动画的起始帧，没有它元素只会「啪」地出现、只有退场动画；二是 &lt;code&gt;display&lt;/code&gt; 和 &lt;code&gt;overlay&lt;/code&gt; 这类离散属性要显式写进 transition 并标 &lt;code&gt;allow-discrete&lt;/code&gt;，退场时元素才能留在 top layer 里把动画播完，而不是瞬间消失；三是遮罩 &lt;code&gt;::backdrop&lt;/code&gt; 要单独写它自己的过渡。这正是「知道 API 存在」和「会写生产级代码」之间的那层密度——也是这个技能包存在的全部理由。助手拿到这份指南后写出的代码，和它凭记忆写的，会是肉眼可见的两种东西。&lt;/p&gt;
&lt;h2&gt;评测体系：它凭什么说自己「有用」&lt;/h2&gt;
&lt;p&gt;技能包最容易沦为玄学：装上一堆指南，感觉代码变好了，但谁也拿不出证据。Modern Web Guidance 的做法是把这件事做成一条可重复的流水线，值得单独讲，因为这也是它和社区里各种「提示词合集」的根本区别。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;考场是真实应用，考题不点名 API。&lt;/strong&gt; 评测用的底座是两个真实风格的 Web 应用（代号 &lt;code&gt;daily-grind&lt;/code&gt;、&lt;code&gt;devtools-times&lt;/code&gt;），任务是模拟真实开发者的口吻提需求——比如「让我的图片加载更快」——故意不出现任何 API 或特性名。这一条很关键：它考的是助手能不能自己「发现」该用推测预加载、该调图片优先级，而不是听见关键词才想起来。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;判卷是自动化的断言检查。&lt;/strong&gt; 产出代码交给 Playwright 检查器，从四个层面验：源码里有没有用对模式、计算样式对不对、运行时 DOM 行为对不对、无障碍状态对不对。不是让另一个模型来「感觉一下好不好」，是硬断言。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;尺子先要校准。&lt;/strong&gt; 这是整套体系里最见功力的一环：同一套检查器，先跑专家写的黄金解（golden solutions，由 Claude、Codex、Antigravity 多家的解法校准），必须 100% 通过；再跑未改动的原始应用，必须 100% 不通过。两个极端都对上了，才证明检查器既不漏判也不误判，量出来的数才可信。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;最后才是对比实验。&lt;/strong&gt; 让编程助手在开/关技能两种模式下跑同一批任务，看通过率差。官方给两个指标：&lt;strong&gt;机会（opportunity）&lt;/strong&gt;＝100% − 裸奔通过率，是理论上能提升的空间；&lt;strong&gt;提升（uplift）&lt;/strong&gt;＝开启后 − 裸奔的通过率差，是实际吃到的部分。近期快照（200 多个任务、1700 多条断言）的数据长这样：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;助手 + 模型&lt;/th&gt;
&lt;th&gt;任务 / 断言数&lt;/th&gt;
&lt;th&gt;裸奔 → 开启技能（提升）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Antigravity CLI（Gemini 4 Argon）&lt;/td&gt;
&lt;td&gt;214 / 1673&lt;/td&gt;
&lt;td&gt;58% → 94%（+36pp）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Claude Code（Opus 5.5）&lt;/td&gt;
&lt;td&gt;215 / 1801&lt;/td&gt;
&lt;td&gt;57% → 88%（+31pp）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Codex CLI（GPT-6.1 Sol）&lt;/td&gt;
&lt;td&gt;215 / 1795&lt;/td&gt;
&lt;td&gt;54% → 82%（+28pp）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;读这张表要抓两个要点：第一，裸奔通过率都在 50% 多——不是模型不行，是「现代写法」这件事裸奔状态下本来就只有一半胜率，这正是机会所在；第二，提升幅度稳定在 30 个百分点上下，跨三家助手、三种模型都成立，说明涨的是指南的功，不是某个模型的脾气。完整的分助手、分指南明细在官方的 Eval Dashboard 上公开可查。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;评测还反过来决定指南的存废。&lt;/strong&gt; 闭环的最后一环：某个任务裸奔通过率已经很高，说明模型本来就会，对应指南就是在浪费 token，剪掉；某个任务裸奔老翻车、开了技能涨得最多，说明这条指南正中要害，保留并继续打磨。前面说的「指南按 token 效率裁剪」，靠的就是这套数据，而不是编辑的主观取舍。&lt;/p&gt;
&lt;h2&gt;安全采用：新特性不是无脑上&lt;/h2&gt;
&lt;p&gt;「多用新特性」如果理解成「哪里新用哪里」，迟早在老浏览器和边缘场景上翻车。这个技能包专门有一套安全采用策略，这也是它和普通「新特性安利文」拉开差距的地方：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;分清增强与关键行为&lt;/strong&gt;。纯增益型的特性（比如推测预加载）老浏览器静默忽略即可，不需要兜底；而对话框控件、网络信标这类关键行为，必须写经过认真考虑的低开销兜底。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;兜底要轻&lt;/strong&gt;。优先几十行以内的定制小兜底（官方口径是小于 50 行），或按需条件加载的 polyfill，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;拒绝为了一个小特性拖进一整个重型第三方包&amp;lt;/span&amp;gt;——那等于把省下的 JS 又加倍还回去。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;兼容数据跟着 Baseline 走&lt;/strong&gt;。指南接入 Baseline 项目的实时兼容数据，助手能按当前浏览器支持情况动态决定写法，而不是背某一年份的兼容表。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;坑点写在明处&lt;/strong&gt;。指南会记录平台的隐藏限制，比如 &lt;code&gt;fetchLater()&lt;/code&gt; 有 64KB 的载荷配额、macOS 特有的滚动条行为等——这些正是模型最容易凭感觉写错的地方。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;实验性特性要过闸&lt;/strong&gt;。Origin Trial 实验 API 和「易变特性」（单引擎刚发布三个月内、还在稳定期的特性）的指南可以被搜到，但 &lt;code&gt;retrieve&lt;/code&gt; 取全文时默认上锁，必须开发者显式同意才放行，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;防止助手自作主张把不稳定 API 用进项目&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;把上面几条落成一张对照表会更清楚：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;例子&lt;/th&gt;
&lt;th&gt;老浏览器上的表现&lt;/th&gt;
&lt;th&gt;兜底要求&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;增强型特性&lt;/td&gt;
&lt;td&gt;推测预加载、&lt;code&gt;content-visibility&lt;/code&gt;、滚动驱动动画&lt;/td&gt;
&lt;td&gt;静默忽略，页面照常工作&lt;/td&gt;
&lt;td&gt;不需要兜底，直接用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;关键行为特性&lt;/td&gt;
&lt;td&gt;对话框控件、网络信标（&lt;code&gt;fetchLater()&lt;/code&gt;）、表单校验&lt;/td&gt;
&lt;td&gt;功能缺失或行为错误&lt;/td&gt;
&lt;td&gt;必须写低开销兜底，或特性检测后条件降级&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;助手用 Baseline 数据的方式也值得说清：指南不是写死「某年某月起可用」，而是接入 Baseline 项目的实时兼容状态——某个特性刚进入 Baseline 广泛可用（Baseline Widely available）时，指南的口径会随之从「谨慎尝鲜」变成「放心默认」。你在项目里要做的，是把自己的支持目标告诉助手（比如「要照顾两年前的 Safari」），它会按这个目标在「直接用 / 特性检测 / 上兜底」之间选。&lt;/p&gt;
&lt;p&gt;至于实验特性为什么只锁 &lt;code&gt;retrieve&lt;/code&gt; 不锁 &lt;code&gt;search&lt;/code&gt;：这是个很克制的设计。锁搜索，等于让助手对这些能力一无所知，你问它「有没有办法做 X」它只会说没有；只锁全文，则助手知道有这么个东西、会主动向你说明「这是实验 API，需要你先开闸」，决策权回到人手里。单引擎发布三个月内的特性，API 形状还可能变——真金白银的项目代码，不该在不知情的情况下押上去。&lt;/p&gt;
&lt;p&gt;放行开关通过项目根目录的 &lt;code&gt;.mwgrc&lt;/code&gt; 配置文件控制，可以提交进仓库让全队共享：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 允许助手取用 Origin Trial 实验 API 的指南
npx modern-web-guidance@latest set-allow-origin-trials

# 允许助手取用易变特性的指南
npx modern-web-guidance@latest set-allow-volatile-features
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这两条命令分别往 &lt;code&gt;.mwgrc&lt;/code&gt; 里写入 &lt;code&gt;&quot;allowOriginTrials&quot;: true&lt;/code&gt; 和 &lt;code&gt;&quot;allowVolatileFeatures&quot;: true&lt;/code&gt;。用户级还可以放一份 &lt;code&gt;~/.mwgrc&lt;/code&gt; 作为全局兜底。默认两个都关——这是对的默认值：先让助手在全线可用的特性里把活干漂亮，真需要尝鲜时再由人来开闸。&lt;/p&gt;
&lt;h2&gt;&lt;code&gt;.mwgrc&lt;/code&gt; 详解：一个文件，统一全队的闸门&lt;/h2&gt;
&lt;p&gt;上一节的两条 &lt;code&gt;set-allow-*&lt;/code&gt; 命令，落点都是项目根目录的 &lt;code&gt;.mwgrc&lt;/code&gt;——一个 JSON 文件，内容就这么直白：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;allowOriginTrials&quot;: true,
  &quot;allowVolatileFeatures&quot;: false
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个键分工明确：&lt;code&gt;allowOriginTrials&lt;/code&gt; 管 Origin Trial 实验 API 的指南全文（对应命令 &lt;code&gt;set-allow-origin-trials&lt;/code&gt;），&lt;code&gt;allowVolatileFeatures&lt;/code&gt; 管单引擎新发布、还在稳定期的易变特性（对应命令 &lt;code&gt;set-allow-volatile-features&lt;/code&gt;）。查找顺序是：先看项目根目录的 &lt;code&gt;.mwgrc&lt;/code&gt;，没有再看用户级的 &lt;code&gt;~/.mwgrc&lt;/code&gt; 兜底。所以个人尝鲜可以放用户级，团队口径放项目级——项目级的存在会盖过个人设置，这正是想要的：进了这个仓库，所有人的助手都按同一套闸门行事。&lt;/p&gt;
&lt;p&gt;团队里用它，建议走三条规矩：第一，&lt;strong&gt;文件提交进仓库&lt;/strong&gt;，和代码一起评审，开闸关闸都是一次可见的变更，而不是某个人在自己机器上悄悄改的；第二，&lt;strong&gt;默认全关&lt;/strong&gt;，需要哪个开哪个，PR 里写明为什么要用这个实验特性、兜底在哪；第三，开了闸的特性要记一笔账——它们进入 Baseline 或正式发布后，把闸关回去、把当时的临时兜底清掉，别让「临时」变成「永久」。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;code&gt;.mwgrc&lt;/code&gt; 是全队生效的开关，不是个人偏好。给团队项目开实验闸之前先过评审：一个人尝鲜，全队的助手都会开始往代码里写实验 API。
:::&lt;/p&gt;
&lt;h2&gt;legacy-scan 实战：给老代码库做一次现代化体检&lt;/h2&gt;
&lt;p&gt;新项目靠指南「写对」，老项目靠的是先「查清」。&lt;code&gt;legacy-scan&lt;/code&gt; 就是那个体检入口：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx modern-web-guidance@latest legacy-scan .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它扫的是「遗留模式」——那些平台已经有原生替代、但代码还在用老写法实现的地方。报告怎么读、按什么顺序动手，建议照下面这套流程走：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步，先按学科归拢，别按文件归拢。&lt;/strong&gt; 扫描结果天然会聚成几类：弹窗类（div 模拟的 dialog/popover）、布局类（媒体查询断点堆叠、手写网格兜底）、性能类（同步长任务、全量渲染、图片优先级缺失）、表单类（自制校验、JS 测高）。同类问题用同一条指南批量解决，比逐个文件零敲碎打效率高得多。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二步，按风险分三档排顺序：&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一档，增强型（风险几乎为零）&lt;/strong&gt;：预加载缺失、&lt;code&gt;content-visibility&lt;/code&gt;、图片 &lt;code&gt;fetchpriority&lt;/code&gt; 这类——老浏览器自动忽略，直接改，改完抽查即可。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二档，组件替换型（风险中等）&lt;/strong&gt;：div 弹窗换 Popover/&lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt;、JS 定位换锚点定位、断点堆叠换容器查询——涉及交互与样式回归，逐个组件改，配视觉与交互回归测试。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三档，关键行为型（风险高）&lt;/strong&gt;：表单校验逻辑、数据上报信标——改错了影响业务正确性，按「安全采用」的兜底要求逐项来，改一项验一项。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三步，每改一项，retrieve 一条指南。&lt;/strong&gt; 扫描负责告诉你「哪里老」，指南负责告诉你「新写法长什么样、坑在哪」。比如扫出一个手写下拉层，先 &lt;code&gt;retrieve&lt;/code&gt; Popover 相关的指南再动手，而不是让助手凭记忆重写——凭记忆正是老毛病的来源。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第四步，改完跑一遍回归再继续。&lt;/strong&gt; 优先级最高的回归是交互路径（弹窗开关、表单提交）和无障碍状态（焦点、读屏播报），这两样恰好也是评测体系里 Playwright 检查器重点验的层面，可以借鉴同样的检查清单。&lt;/p&gt;
&lt;p&gt;:::warning
legacy-scan 给的是「可以现代化」的清单，不是「必须全改」的工单。十年老项目一次性全仓替换，等于把回归风险攒成一颗雷：按档位分批改、分批上线，每批都留好回滚余地。
:::&lt;/p&gt;
&lt;h2&gt;适合谁&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;天天用 AI 写前端的人&lt;/strong&gt;。如果你已经在用编程助手写页面（参见本系列的 &lt;a href=&quot;/posts/ai-coding-assistants/&quot;&gt;AI 编程助手实战&lt;/a&gt;），这个技能包是性价比极高的一层「品味校准」：模型不变、流程不变，只是它写出来的代码从「能跑的老派实现」变成「现代平台实现」。通过命令行使用助手的（参见 &lt;a href=&quot;/posts/ai-cli-assistants/&quot;&gt;命令行里的 AI 助手&lt;/a&gt;）同样适用，它对各家 CLI 助手都有对应的装法。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;想把老项目往现代平台迁的人&lt;/strong&gt;。先用 &lt;code&gt;legacy-scan&lt;/code&gt; 对代码库做一次遗留模式盘点，再按指南逐项替换——哪些 div 弹窗可以换 Popover、哪些手写布局可以换容器查询，路径是现成的。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;对包体积和性能敏感的项目&lt;/strong&gt;。它的整个导向就是「能用原生就不用库」，长期下来砍掉的是实打实的 JS 体积和维护面。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;反过来，如果你的项目压根不碰浏览器前端，或者技术栈被锁定在很老的浏览器环境（新特性大面积用不上），它的收益就有限——指南再好，落地不了也是白搭。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;装完之后，助手写代码还是老样子，技能没生效？&lt;/strong&gt;
先确认安装向导识别对了你的助手、技能文件落到了正确目录；插件方式安装的，装完通常要重载插件或新开一个会话。也可以手动验证 CLI 本身是通的：在项目目录跑一次 &lt;code&gt;npx modern-web-guidance@latest search &quot;popover&quot;&lt;/code&gt;，能返回指南列表，说明工具侧没问题，剩下的就是助手侧的激活配置。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;search&lt;/code&gt; 搜不到我想要的指南？&lt;/strong&gt;
换查询的表述方式再试：它匹配的是「你想做的事」，用描述任务的自然语言（比如 &quot;animate a dialog modal backdrop&quot;）通常比只敲一个 API 名效果好。也可能这个特性属于被上锁的实验/易变类别——能搜到标题却取不出全文时，先看是不是需要 &lt;code&gt;.mwgrc&lt;/code&gt; 放行。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;retrieve&lt;/code&gt; 提示指南被锁定（gated）？&lt;/strong&gt;
这是有意设计：Origin Trial 与易变特性的全文默认上锁。确认你真的要尝鲜后，在项目根目录执行对应的 &lt;code&gt;set-allow-*&lt;/code&gt; 命令生成 &lt;code&gt;.mwgrc&lt;/code&gt;，再重新取。团队项目里这个文件应该提交进仓库，让所有人的助手行为一致。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;指南里的写法和我们项目的浏览器支持目标冲突？&lt;/strong&gt;
指南接入的是 Baseline 实时兼容数据，面向的是当前主流支持面。如果你的项目还要照顾更老的浏览器，按「安全采用」一节的思路处理：关键行为补轻量兜底，或者干脆不用该特性——技能给的是建议，最终拍板的兼容策略在你手里。不要反过来把兜底写成主实现、新特性当摆设，那就本末倒置了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;它会把我的代码或提示词传出去吗？&lt;/strong&gt;
搜索与取指南全在本地跑，离线可用。但要注意：Google 会收集匿名使用信息（安装数、调用的助手名、被取用的指南 ID、助手生成的搜索查询词），不收集原始用户提示词。在意的可以在 Shell 配置里关掉：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;export DISABLE_TELEMETRY=1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;内容会不会过时？&lt;/strong&gt;
这正是它用 &lt;code&gt;npx ...@latest&lt;/code&gt; 分发的原因：每次拉的都是最新指南。用安装器装的跑一次 &lt;code&gt;update&lt;/code&gt; 即可；插件方式装的按对应助手的插件更新流程走。Web 平台半年一变，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;装完就不管、一年不更新，指南的价值会肉眼可见地缩水&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;它和直接查 MDN 有什么区别？&lt;/strong&gt;
MDN 是给人看的参考手册，信息全但密度平；这里的指南是给模型看的「纠偏材料」：只保留模型不知道或容易用错的部分，附带生产级范式、坑点和兜底，并且经过评测验证真的能改变模型产出。人查手册、助手吃指南，分工不同。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;指南的写法和我们项目现有的规范、组件库冲突，听谁的？&lt;/strong&gt;
听你项目的。指南给的是「平台层面的最佳实践」，不是强制标准：你们已经有成熟的弹窗组件、设计系统，就没必要为了用 Popover 把组件库推倒。正确用法是把指南当评审意见——它指出「这里平台有原生能力」，采纳不采纳由项目规范拍板。长期看，更值钱的动作是把「我们项目决定不用 X、因为 Y」这类结论沉淀下来，下次评审直接引用，而不是每次和助手重新争一遍。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;团队里每个人装的版本不一样，助手行为对不齐怎么办？&lt;/strong&gt;
先统一安装方式：要么全员用官方安装向导，要么全员用同一个插件市场，别混着来。然后把两件事固定下来：一是 &lt;code&gt;.mwgrc&lt;/code&gt; 提交进仓库，闸门口径全队一致（见前面 &lt;code&gt;.mwgrc&lt;/code&gt; 一节）；二是把「定期跑一次 update」写进团队的入职清单或迭代例行事项。版本差异的麻烦不在功能多少，而在同一个任务不同人跑出两种风格的代码，评审成本全耗在这种地方。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;离线或内网环境能用吗？&lt;/strong&gt;
用的时候完全可以：搜索和取指南都是本地跑的，零依赖、不联网、不需要 API Key，断网不影响助手查指南。需要联网的只有「获取」环节——第一次安装、后续更新要拉 npm 包。所以内网环境的标准做法是：在有网的机器上装好、更新好，再把环境同步进去；日常开发全程离线无碍。遥测按前面说的用 &lt;code&gt;DISABLE_TELEMETRY=1&lt;/code&gt; 关掉即可。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;两个技能包都要装吗？&lt;/strong&gt;
看你做什么。只做普通网站，主包 &lt;code&gt;modern-web-guidance&lt;/code&gt; 就够了；只有当你还要开发 Chrome 扩展时，才需要再加 &lt;code&gt;chrome-extensions&lt;/code&gt; 包（Manifest V3、Service Worker、扩展 API、上架发布那一套）。两个包的技能描述加起来也就几百 tokens，常驻成本不高，但没用到的包不装，是对上下文窗口的基本尊重。用 &lt;code&gt;--choose&lt;/code&gt; 在安装时挑好即可，后来想加随时能补装。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Modern Web Guidance 补的是 AI 编程助手最隐蔽的一块短板：不是不会写代码，而是写的代码停留在训练数据的平均年代。它的做法很务实——浏览器厂商和 MDN 的专家把 250 个现代特性的正确用法、兼容状态和兜底策略，裁剪成模型缺的那部分经验密度，通过本地 CLI 按需喂进上下文；再用评测闭环持续验证「喂了真的有用」，用 &lt;code&gt;.mwgrc&lt;/code&gt; 闸门守住实验性特性的边界。&lt;/p&gt;
&lt;p&gt;谁最值得装，排个序：第一是&lt;strong&gt;每天靠 AI 写前端、且对产出质量有要求的人&lt;/strong&gt;——你省下的不是打字时间，是逐行纠正老派写法的评审时间；第二是&lt;strong&gt;手里有老项目要长期维护的人&lt;/strong&gt;——&lt;code&gt;legacy-scan&lt;/code&gt; 加逐条指南，是把「现代化」从口号拆成可执行工单的最短路径；第三是&lt;strong&gt;团队的技术负责人&lt;/strong&gt;——与其在代码评审里一遍遍口头传达「我们这儿弹窗用原生、布局用容器查询」，不如把厂商指南加 &lt;code&gt;.mwgrc&lt;/code&gt; 闸门变成助手默认遵守的基础设施，规范落在工具里，比落在文档里管用。&lt;/p&gt;
&lt;p&gt;它和上一篇的 Skill Seekers 搭配起来，正好是一套组合：Modern Web Guidance 是「厂商出的成品」——平台的最佳实践不用你操心，装上就生效；Skill Seekers 是「自家作坊」——把你们项目的组件库文档、内部规范、业务手册炼成私有技能，补上厂商指南不可能覆盖的那部分。&lt;strong&gt;一个管「平台的规矩」，一个管「我们项目的规矩」&lt;/strong&gt;，两层都齐了，助手才既写得现代、又写得像你们团队的代码。&lt;/p&gt;
&lt;p&gt;如果你只记一件事：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;与其换更强的模型，不如先给现在的助手补上它缺的那层平台经验&amp;lt;/span&amp;gt;——这个技能包就是目前这条路上最权威、最省事的一份现成答案。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：motion-prompt 跟 AI 点单的动作词库</title><link>https://www.anexns.cloudns.org/posts/ai-motion-prompt/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-motion-prompt/</guid><description>motion-prompt 是一套给 AI 点单用的名字库：216 个动作、运镜与效果的正式名字，配动态样片和点单例句，装成技能后在画廊里点选就能发给助手，让「我想要那种效果」变成一句说得清的指令。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：做不出想要的效果，往往是不知道它「叫什么」&lt;/h2&gt;
&lt;p&gt;用 AI 做视频、做动效的人，多半都经历过这种憋屈：脑子里画面清清楚楚——标题从下方遮罩里滑出来、镜头贴着地面慢慢推近、页面滚动时元素一个接一个淡入——可真到写提示词的时候，只剩下「那个……就是那个效果」。&lt;/p&gt;
&lt;p&gt;于是提示词越写越长，全是形容词和比方：「像电影里那种慢慢靠近的感觉」「炫酷一点的入场动画」「高级感的转场」。模型收到这种描述，只能靠猜，猜出来的东西和脑子里的画面对不上，又说不清到底差在哪一句话上，只能重抽。&lt;/p&gt;
&lt;p&gt;motion-prompt 作者在仓库里讲了这个项目的由来：他发过几条给动态图形动作和镜头运动命名的短视频，评论区很多人说，卡住自己的&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;不是没想象力，而是不知道这种运动「叫什么名字」&amp;lt;/span&amp;gt;。这句话点破了整件事：&lt;strong&gt;专业创作者和 AI 之间缺的不是工具，是一套共同语言&lt;/strong&gt;。剪辑师跟导演说「dolly in」，双方都知道是轨道推镜、不是变焦；你跟 AI 说不出这个词，就只能用一整段形容去碰运气。&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;先看清它解决什么问题 → 拆开这套 216 个名字的词库长什么样 → 三种用法逐个上手 → 讲清「名字＋四要素」的点单方法 → 安装三路线与排障&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/showheyohtaki/motion-prompt ，在线画廊：https://showheyohtaki.github.io/motion-prompt/&lt;/p&gt;
&lt;h2&gt;它是什么：一套给 AI 点单用的名字库&lt;/h2&gt;
&lt;p&gt;motion-prompt 不是生成工具，它本身不产出任何视频或图片。它是一部&lt;strong&gt;带动态样片的词典&lt;/strong&gt;：把创作者平时要向 AI「点单」的东西——动态图形动作、镜头运动、转场、UI 组件、网页动效、照片观感、生图画风——逐个起上正式名字，每个名字配三样东西：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;一段会动的样片&lt;/strong&gt;。不是静态截图，名字对应的动作直接在画廊里动给你看，所见即所得。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;一句话释义&lt;/strong&gt;。这个名字到底指什么，一行说清，不用猜。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;一句点单例句&lt;/strong&gt;。向 AI 提出这个要求时，话应该怎么说，现成的句子可以直接抄改。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;全库共 &lt;strong&gt;216 个名字，分 9 套词包，每套 24 个&lt;/strong&gt;，编号从 001 排到 216。所有名单都有五种语言版本：英语、日语、西班牙语、简体中文、繁体中文——查中文名、抄英文名去喂视频模型，两种需求都照顾到了。在线画廊里每个样片都能动，名单也可以直接在 GitHub 的 &lt;code&gt;packs/&lt;/code&gt; 目录里读。&lt;/p&gt;
&lt;p&gt;它还有一层身份：仓库里带了一个同名 &lt;strong&gt;Skill（技能包）&lt;/strong&gt;，装进编程助手之后，助手能直接打开画廊、接收你的点选、把选中的效果做进你的项目里。所以它既是一本可以裸读的词典，也是一个能装进 Agent 的工作流组件。词典这层定位和 &lt;a href=&quot;/posts/ai-prompt-engineering/&quot;&gt;提示词工程&lt;/a&gt; 里讲的「把模糊意图翻译成模型能执行的描述」是一回事，只不过它把翻译工作提前做成了现成的名录。&lt;/p&gt;
&lt;h2&gt;九套词包速览&lt;/h2&gt;
&lt;p&gt;先用一张表把 9 套词包对齐，查的时候按需求翻对应的包就行：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;编号&lt;/th&gt;
&lt;th&gt;词包&lt;/th&gt;
&lt;th&gt;内容&lt;/th&gt;
&lt;th&gt;典型用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;001–024&lt;/td&gt;
&lt;td&gt;&lt;code&gt;motion&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;动态图形动作（第一辑）&lt;/td&gt;
&lt;td&gt;片头标题、字幕条、图形元素的入场与强调动作&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;025–048&lt;/td&gt;
&lt;td&gt;&lt;code&gt;camera&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;镜头运动与转场（第一辑）&lt;/td&gt;
&lt;td&gt;给视频模型下运镜指令、给剪辑定转场&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;049–072&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ui&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;UI 组件名&lt;/td&gt;
&lt;td&gt;向 AI 描述界面零件时用对名词，别再「那个框」「那个条」&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;073–096&lt;/td&gt;
&lt;td&gt;&lt;code&gt;lp&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;落地页与网页动效（第一辑）&lt;/td&gt;
&lt;td&gt;做产品页、官网时点名要滚动与悬停效果&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;097–120&lt;/td&gt;
&lt;td&gt;&lt;code&gt;photo&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;照片观感、光影与风格&lt;/td&gt;
&lt;td&gt;给照片类生成和修图下风格指令&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;121–144&lt;/td&gt;
&lt;td&gt;&lt;code&gt;motion2&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;动态图形动作（第二辑）&lt;/td&gt;
&lt;td&gt;第一辑之外的进阶动作补充&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;145–168&lt;/td&gt;
&lt;td&gt;&lt;code&gt;lp2&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;落地页与网页动效（第二辑）&lt;/td&gt;
&lt;td&gt;更多页面效果与交互动效&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;169–192&lt;/td&gt;
&lt;td&gt;&lt;code&gt;camera2&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;镜头运动与转场（第二辑）&lt;/td&gt;
&lt;td&gt;更细的运镜与转场名目&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;193–216&lt;/td&gt;
&lt;td&gt;&lt;code&gt;artstyle&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;生图画风&lt;/td&gt;
&lt;td&gt;给图片模型点名画风，同一张草图换不同风格&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个使用细节值得知道：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;每套包有自己的视觉风格&lt;/strong&gt;，不是全库一个模子。比如 &lt;code&gt;motion&lt;/code&gt; 系是深海军蓝底加四色，&lt;code&gt;camera&lt;/code&gt; 系是浅灰底加一抹蓝，&lt;code&gt;artstyle&lt;/code&gt; 包干脆不用绘图，而是拿同一张底稿让图片模型按每种画风重绘，再用斜向擦除动画对比原稿——选画风时对比感拉满。作者说得很明白：词包要做对的是&lt;strong&gt;名字&lt;/strong&gt;，不是统一的房屋风格。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;编号是全库统一的&lt;/strong&gt;。报号就能唯一定位一个效果，&lt;code&gt;#032&lt;/code&gt; 在任何语言版本里指的都是同一个运镜，这是后面「报号点单」能成立的基础。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;名单和画廊是同一份数据&lt;/strong&gt;。画廊里动的样片，和 &lt;code&gt;packs/&lt;/code&gt; 里读到的文字名单，一一对应，不会出现图里有、名单里查不到的情况。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;三种用法，逐个上手&lt;/h2&gt;
&lt;h3&gt;用法一：装成技能，在画廊里点选，直接发给助手&lt;/h3&gt;
&lt;p&gt;这是最省脑子的用法，适合「我知道想要哪种感觉，但叫不出名字」的场景。前提是把 motion-prompt 技能装进你的编程助手（安装方法见后面一节），之后流程是纯点选：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;对助手说一句：&lt;code&gt;Open the motion-prompt library.&lt;/code&gt;（打开 motion-prompt 词库），画廊会在浏览器里打开。想缩小范围可以点名类别，比如说只看镜头运动，画廊会过滤到 &lt;code&gt;camera&lt;/code&gt; 和 &lt;code&gt;camera2&lt;/code&gt; 两套一起显示。&lt;/li&gt;
&lt;li&gt;在画廊里逐个看样片，看中哪个就点它上面的 &lt;strong&gt;Pick&lt;/strong&gt;，可以连选多个；画廊底部有个备注栏，能写一句用途，比如「for the opening title」（用在片头标题上）。&lt;/li&gt;
&lt;li&gt;点 &lt;strong&gt;Send to AI&lt;/strong&gt;，你的点选就发回给助手了。&lt;/li&gt;
&lt;li&gt;回到对话里说要拿这些效果做什么，比如：&lt;code&gt;Edit the opening of this video like this.&lt;/code&gt;（把这段视频的片头按这个改）。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;助手这边会做什么，README 里写得很清楚：它只用你选中的那几样，不会自作主张加别的；它会去取这些效果的规格说明和参考代码，再结合你的项目实际产出方式（Canvas、Remotion、CSS、After Effects，或者给视频生成模型的提示词）把效果做进去。你没选、让它自己挑的时候，它会先建议打开画廊；你明确让它挑，它才按目录逐场搜索。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;知道编号时可以跳过画廊，直接报号点单&lt;/strong&gt;，这是熟练之后最快的路径，例句都是可以直接抄的句式：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Use the motion-prompt skill with #012 and #045 to make this product video look professional.
（用 motion-prompt 技能的 #012 和 #045，把这条产品视频做得专业一点。）
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;Replace the part where the title appears with #005 from motion-prompt. Keep the length and the transitions before and after it.
（把标题出现的那一段换成 motion-prompt 的 #005，时长和前后的转场保持不变。）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;没有装技能的助手也能用画廊：在画廊里点选完，点底部的 &lt;strong&gt;Copy picks&lt;/strong&gt;，会得到一段带样片和规格链接的文本，粘贴进任意对话窗口即可。&lt;/p&gt;
&lt;h3&gt;用法二：不装任何东西，查到名字直接写进提示词&lt;/h3&gt;
&lt;p&gt;词库的第二种用法零安装：打开名单或画廊，找到你想的那个效果，&lt;strong&gt;把它的名字原样写进提示词&lt;/strong&gt;。名字本身就是压缩过的专业描述，一个词顶一段形容。官方给的例句长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Bring the title in with a mask reveal from below, 0.6 s, each line slightly after the one before.
（标题用自下而上的遮罩揭示入场，0.6 秒，每行比上一行稍晚一点。）
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;Slow dolly in toward her face; move the camera, do not zoom.
（缓慢轨道推镜靠近她的脸；移动机位，不要变焦。）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这种用法在给&lt;strong&gt;视频生成模型&lt;/strong&gt;下运镜指令时尤其值钱。视频模型对镜头术语的响应远比对形容词稳定，你把画廊里某个运镜的名字拿出来，甚至可以让助手先帮你转写成目标模型的提示词，README 里就有现成句式：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Turn the camera move in motion-prompt #032 into an English prompt for Veo. The subject is a coffee cup on a desk.
（把 motion-prompt #032 的运镜改写成给 Veo 的英文提示词，主体是桌上的一只咖啡杯。）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这条路径和 &lt;a href=&quot;/posts/ai-muse-video-prompt/&quot;&gt;muse-video-prompt-skill 的六段式提示词工作流&lt;/a&gt; 正好接得上：六段式模板管的是每一镜的整体结构，motion-prompt 管的是其中「运镜」和「动作」这两段到底填哪个词。一个定框架，一个供词汇，配合使用时提示词既有章法又有准头。&lt;/p&gt;
&lt;h3&gt;用法三：给自己的领域和语言，做一套你自己的&lt;/h3&gt;
&lt;p&gt;这是这个仓库格局最大的一手。作者把「怎么做一套这样的词库」的提示词也开源了，放在 &lt;code&gt;make-your-own/&lt;/code&gt; 目录里，附带渲染视频的脚本和两个做完的范例（HTML 源码、三条视频、一张速查图）。三条路线：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;目标&lt;/th&gt;
&lt;th&gt;用哪份提示词&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;把现有视频换成另一种语言&lt;/td&gt;
&lt;td&gt;&lt;code&gt;make-your-own/prompts/en/01-translate.md&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;给你自己的领域起名，用你自己的视觉风格&lt;/td&gt;
&lt;td&gt;&lt;code&gt;make-your-own/prompts/en/02-your-own-field.md&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;做一页纸的速查图&lt;/td&gt;
&lt;td&gt;&lt;code&gt;make-your-own/prompts/en/03-cheatsheet-image.md&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;关键在于：&lt;strong&gt;领域不限于视频&lt;/strong&gt;。作者明说，灯光、声音、UI、摄影、烹饪、建筑——任何「知道名字才能开口要」的领域，都可以照这个模子做一套。因为限制人的从来不是领域，是那套共同语言还没人整理。仓库也开放贡献：懂某个领域的人可以按 &lt;code&gt;CONTRIBUTING.md&lt;/code&gt; 的说明新增词包，或给现有词包补一个语言版本。&lt;/p&gt;
&lt;h2&gt;为什么「名字」这么关键：点单四要素&lt;/h2&gt;
&lt;p&gt;把三种用法串起来看，会发现这套词库真正教的是一种点单方法：&lt;strong&gt;名字只是第一要素，说全了才准&lt;/strong&gt;。README 里那句提醒是核心——找到名字之后，再补上时长、强度和谁在动，结果才接近你想要的。拆开就是点单四要素：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;名字&lt;/strong&gt;：要哪种动作、运镜或效果，用正式名或编号锁定，不留猜测空间。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;时长&lt;/strong&gt;：这个动作持续多久。0.6 秒的遮罩揭示是利落，2 秒就是舒缓，完全两种气质。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;强度&lt;/strong&gt;：幅度多大。推镜推到特写还是中景，弹跳回弹一下还是三下，差一个量级就是两种风格。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;谁在动&lt;/strong&gt;：动的是镜头、主体还是背景元素。「镜头推近」和「主体迎面走来」画面完全不同，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;这一项说反，整条片子的空间感就全错了&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;为什么名字排第一？因为名字是其余三要素的挂载点。没有名字，你得用一整段话同时描述动作长什么样、持续多久、幅度多大，话越长模型越容易丢信息；有了名字，动作本体被一个词锚定，剩下的篇幅全用来调时长、强度和主体，指令的信噪比完全不同。这和 &lt;a href=&quot;/posts/ai-muse-video-skill/&quot;&gt;前期策划技能 muse-video-skill&lt;/a&gt; 的思路互为表里：策划管「这一镜要讲什么」，词库管「这一镜的动作具体叫什么、怎么调」。&lt;/p&gt;
&lt;p&gt;:::warning
名字要用对包、报对号。同名不同包的情况是存在的——比如转场类名字在 &lt;code&gt;camera&lt;/code&gt; 和 &lt;code&gt;lp&lt;/code&gt; 里都可能出现，一个是镜头转场、一个是页面切换效果。报号前先确认编号区间属于哪一套包，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;报对名字却报错包，助手会一本正经地把网页动效做进你的视频里&amp;lt;/span&amp;gt;。
:::&lt;/p&gt;
&lt;h2&gt;安装三路线（用法一的前置）&lt;/h2&gt;
&lt;p&gt;只有用法一需要安装，另外两种用法打开网页就能用。安装需要 &lt;strong&gt;Node.js 18 或更高版本&lt;/strong&gt;，先 &lt;code&gt;node --version&lt;/code&gt; 确认。三条路线任选：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;路线一：一句话让助手自己装。&lt;/strong&gt; 把下面这句粘贴进 Claude Code 或 Codex，助手会照仓库说明完成安装并回你三行用法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Read https://github.com/showheyohtaki/motion-prompt and install the motion-prompt skill in this environment. When it is installed, tell me how to use it in three lines.
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;路线二：命令行装。&lt;/strong&gt; 用通用的 skills 安装器，一条命令，兼容 Claude Code、Codex 等读取 Agent Skills 的助手：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx skills add showheyohtaki/motion-prompt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;路线三：Claude Code 插件。&lt;/strong&gt; 在 Claude Code 里依次执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/plugin marketplace add showheyohtaki/motion-prompt
/plugin install motion-prompt@motion-prompt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;手动安装&lt;/strong&gt;也行：把仓库的 &lt;code&gt;skills/motion-prompt&lt;/code&gt; 文件夹拷到对应目录——&lt;code&gt;~/.claude/skills/&lt;/code&gt; 是 Claude Code 全局生效，&lt;code&gt;~/.agents/skills/&lt;/code&gt; 是 Codex 等助手全局生效；放在项目内的 &lt;code&gt;.claude/skills/&lt;/code&gt; 或 &lt;code&gt;.agents/skills/&lt;/code&gt; 则只对该项目生效。&lt;/p&gt;
&lt;p&gt;装完可以自检一次：在技能目录下运行 &lt;code&gt;node &amp;lt;skill-dir&amp;gt;/scripts/motion-prompt.mjs info&lt;/code&gt;，能打印出数据源和元素数量就是装好了；&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;退出码 3 表示数据源连不上，先解决网络再重试，别对着一个没装成的技能反复下指令&amp;lt;/span&amp;gt;。另外想自己跑画廊的话，仓库支持本地启动画廊页面，具体命令见 README 的 Skill reference 一节。&lt;/p&gt;
&lt;h2&gt;适合谁&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;做短视频和动效的人&lt;/strong&gt;：片头、字幕条、转场这些高频需求，全在 &lt;code&gt;motion&lt;/code&gt; 和 &lt;code&gt;camera&lt;/code&gt; 四套包里，点选或报号都比打字形容快。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;给视频模型写运镜提示词的人&lt;/strong&gt;：这是这套词库最被低估的用法——运镜术语是视频模型的「母语」，查对名字再下单，出片稳定性明显不一样。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;做落地页和产品站的人&lt;/strong&gt;：&lt;code&gt;lp&lt;/code&gt;、&lt;code&gt;lp2&lt;/code&gt;、&lt;code&gt;ui&lt;/code&gt; 三套包把页面效果和组件名备齐了，跟 AI 协作改页面时沟通成本直接降一档。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;想给自己行业攒一套术语库的人&lt;/strong&gt;：&lt;code&gt;make-your-own/&lt;/code&gt; 的三份提示词就是现成的生产线，你的领域缺的那套共同语言，可以照着做出来。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;反过来，如果你只用聊天式助手写文案、从不碰视觉产出，这套词库暂时用不上，不必为了收藏而安装。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：我没装技能，画廊里选好的东西怎么给助手？&lt;/strong&gt;
A：在画廊底部点 &lt;strong&gt;Copy picks&lt;/strong&gt;，得到的文本自带样片与规格的链接，粘贴到对话里即可。装了技能的路径是点 &lt;strong&gt;Send to AI&lt;/strong&gt; 直达助手，助手会等你点选，最长等 15 分钟，慢慢挑没关系。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：报号点单，助手做的效果和样片对不上？&lt;/strong&gt;
A：先查两件事：一是编号有没有报错包（对照九套词包速览表的编号区间）；二是四要素有没有说全——只报名字不给时长和强度，助手只能按默认值发挥，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;偏差往往不在名字，在你没说的那三项上&amp;lt;/span&amp;gt;。把时长、强度、谁在动补齐再下一次单。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：&lt;code&gt;npx skills add&lt;/code&gt; 选助手的环节卡住或装错地方？&lt;/strong&gt;
A：安装器可能会问装给哪个 Agent，选你当前用的那个。不确定装到哪了，就按手动路径核对目录：全局是 &lt;code&gt;~/.claude/skills/&lt;/code&gt; 或 &lt;code&gt;~/.agents/skills/&lt;/code&gt;，项目级是项目内的同名目录。实在不行改走手动拷贝，最笨但最可控。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：运行自检脚本报退出码 3？&lt;/strong&gt;
A：这是数据源不可达的意思，技能本体没坏，是网络到不了数据地址。恢复网络后重跑 &lt;code&gt;info&lt;/code&gt; 命令确认即可，不要因此重装技能。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：中文名单和英文名单，实际用哪个？&lt;/strong&gt;
A：查阅用中文名单最快，理解零门槛；真正写进提示词时，喂视频模型和图片模型的指令建议换回英文名——主流生成模型对英文术语的训练覆盖更全。同一个编号在五种语言里指的是同一个效果，按编号对照着换语言不会串。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：能不能只装词库的一部分？&lt;/strong&gt;
A：技能是一个整体，装的是全套；但使用时完全可以只翻你需要的那两三套包。名单本身也可以只读 &lt;code&gt;packs/&lt;/code&gt; 里对应的文件，不装技能照样查。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;motion-prompt 做的事情，用一句话说：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;把「我想要那种效果」里说不出口的「那种」，逐个变成了有名字、有样片、有例句的现成词条&amp;lt;/span&amp;gt;。216 个名字、9 套词包、五种语言，装成技能可以点选直达助手，不装也能查名点单，还能照着它的生产线给你自己的领域做一套。&lt;/p&gt;
&lt;p&gt;给它在本系列里定位：前面的工具多在解决「怎么生成」「怎么拼接」「怎么策划」，这一篇解决的是更靠前的一环——&lt;strong&gt;开口之前，先把话说对&lt;/strong&gt;。名字对了，时长、强度、谁在动补齐了，后面用哪个模型、走哪条工作流，出片的下限都会稳很多。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：动画短片全流程 Muse-animated-short-film</title><link>https://www.anexns.cloudns.org/posts/ai-muse-animated-film/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-muse-animated-film/</guid><description>介绍 Muse 技能 Muse-animated-short-film：从一句想法出发，经角色设定、故事圣经、关键帧与 mega prompt 八个阶段，在对话里走完动画短片从剧本到 MP4 成片的完整流水线。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：AI 能生成片段，但片段不等于短片&lt;/h2&gt;
&lt;p&gt;现在让 AI 生成一段几秒钟的动画视频并不难，难的是把十几个片段拼成一部「像样的短片」：第一场里的小男孩，到了第三场换了一张脸；上一镜还是黄昏，下一镜突然正午；镜头之间没有衔接，观众一眼就看出是素材堆砌。再加上旁白、配音、拼接、混音这些后期环节，很多人卡在「生成了一堆片段，却交不出一部片子」这一步。&lt;/p&gt;
&lt;p&gt;Muse-animated-short-film 要解决的正是这个问题。它不是又一个视频生成模型，而是一套装在 Muse 里的&lt;strong&gt;动画短片制作技能（Skill）&lt;/strong&gt;：你给出一句粗略的想法，它按一条固定的八阶段流水线往下推进——角色设定、故事圣经、关键帧、提示词、逐段生成、旁白配音、ffmpeg 合成——每个阶段都产出明确的文件，每个阶段都停下来等你确认，最后交出一部完整的 MP4 成片。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/sonlovinbot-team/Muse-animated-short-film&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;它是什么 → 怎么装、开场先回答哪三个问题 → 八阶段流水线逐段拆解 → 贯穿全程的三条硬规则 → 官方样片《The Last Lantern》拆解 → 它沉淀的实战教训 → 适合谁、不适合谁&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;它是什么：一套「制片流程」，不是一个生成按钮&lt;/h2&gt;
&lt;p&gt;先把定位说清楚。Muse 本身具备生成图片、视频、音频的能力，但这些能力是零散的：你得自己想分镜、自己写每一段的提示词、自己操心人物一致性、自己动手拼接。Muse-animated-short-film 做的事情，是把一位动画导演的工作方法固化成技能文件（仓库里的 &lt;code&gt;SKILL.md&lt;/code&gt; 加一组分阶段的参考文档），让 Muse 按这套方法带着你走完整部片子。&lt;/p&gt;
&lt;p&gt;它和本系列其他两篇视频工具的分工很清楚：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;工具&lt;/th&gt;
&lt;th&gt;定位&lt;/th&gt;
&lt;th&gt;产出&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;muse-video-skill&lt;/td&gt;
&lt;td&gt;前期策划引擎：创意、剧本、分镜、美术方向&lt;/td&gt;
&lt;td&gt;策划案与模型调用指令&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;muse-video-prompt-skill&lt;/td&gt;
&lt;td&gt;生成端工作流：把分镜落成提示词并逐段生成验证&lt;/td&gt;
&lt;td&gt;单段/多段视频片段&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Muse-animated-short-film&lt;/td&gt;
&lt;td&gt;全流程制片：从想法一路管到成片交付&lt;/td&gt;
&lt;td&gt;完整的动画短片 MP4&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;也就是说，前面两篇解决的是「想清楚」和「生成好」，这一篇解决的是「从头到尾做完一部」。它的工作方式是对话式的：你不需要读仓库里的参考文档，Muse 会在每个阶段自己去读对应文件；你要做的只有在关键节点看产出、说「可以」或者「改这里」。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;这套技能的核心价值不在生成本身，而在于它把「人物锁定、关键帧衔接、逐段确认」这些制片纪律写进了流程，让业余玩家也能按专业片场的顺序做事。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;安装与开场三问&lt;/h2&gt;
&lt;p&gt;安装方式和大多数 Muse 技能一样：把整个仓库文件夹复制到你的 Muse 技能目录即可，例如：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;~/workspace/skills/animated-short-film/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;仓库结构大致如下，看懂这个结构，后面八个阶段的产物落在哪里就一目了然：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Muse-animated-short-film/
├── SKILL.md            # 主流程与运行规则，Muse 读
├── references/         # 分阶段详细指南（01 角色设定表 ～ 08 经验教训）
├── examples/
│   └── the-last-lantern/   # 官方样片的全部过程文件
└── docs/               # 介绍页与配图
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;装好之后，在对话里说一句「我想做一部动画短片」，技能就会启动，并且先问你三个问题：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;片子多长？&lt;/strong&gt; 时长决定场景数。场景数不是随口定的——每场戏对应一段生成视频，时长先定下来，后面关键帧和提示词的数量才有依据。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;用什么语言？&lt;/strong&gt; 这决定旁白脚本和配音的语言，仓库自带的样片就同时给了英文和越南文两版旁白脚本。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;画幅是 16:9 还是 9:16？&lt;/strong&gt; 横屏还是竖屏，必须在开工前定死，原因见后面「画幅严格锁定」那条硬规则。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;这三个问题看着简单，却是整条流水线的地基：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;时长、语言、画幅任何一项中途变更，都会让已经生成的关键帧和片段大面积作废&amp;lt;/span&amp;gt;，所以它放在第 0 阶段就问清楚，而不是边做边改。&lt;/p&gt;
&lt;h2&gt;八阶段流水线逐段拆解&lt;/h2&gt;
&lt;p&gt;整条流水线共八个阶段，先看汇总表，再逐段展开：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;阶段&lt;/th&gt;
&lt;th&gt;名称&lt;/th&gt;
&lt;th&gt;产出&lt;/th&gt;
&lt;th&gt;你要确认什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;0&lt;/td&gt;
&lt;td&gt;输入收集&lt;/td&gt;
&lt;td&gt;时长、语言、画幅与场景数&lt;/td&gt;
&lt;td&gt;三个开场问题的答案&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;角色设定表&lt;/td&gt;
&lt;td&gt;每个角色的多角度图＋表情图&lt;/td&gt;
&lt;td&gt;角色长相是否过关&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;故事圣经&lt;/td&gt;
&lt;td&gt;Logline、角色锁定说明、逐场大纲&lt;/td&gt;
&lt;td&gt;故事走向与每场内容&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;关键帧&lt;/td&gt;
&lt;td&gt;K1..K(N+1) 一组衔接帧&lt;/td&gt;
&lt;td&gt;帧与帧之间是否连贯&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;Mega Prompt&lt;/td&gt;
&lt;td&gt;每场一条可直接粘贴的完整提示词&lt;/td&gt;
&lt;td&gt;提示词是否准确表达该场&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;视频生成&lt;/td&gt;
&lt;td&gt;逐段的首帧→尾帧视频片段&lt;/td&gt;
&lt;td&gt;每段画面是否可用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;旁白与配音&lt;/td&gt;
&lt;td&gt;带时间轴的旁白脚本与配音音频&lt;/td&gt;
&lt;td&gt;文案语气与时长对位&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;合成成片&lt;/td&gt;
&lt;td&gt;ffmpeg 拼接混音后的 MP4&lt;/td&gt;
&lt;td&gt;终片整体效果&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;阶段 0：输入收集——先定场景数&lt;/h3&gt;
&lt;p&gt;除了开场三问，这一阶段还要把「时长 → 场景数」的换算定下来。一部短片由若干场戏组成，每场戏最终会生成一段视频，段与段之间靠关键帧衔接。场景太少故事讲不完，太多则生成成本和翻车概率都上升。样片《The Last Lantern》用的是 8 场结构，可以作为第一次尝试的参考量级。&lt;/p&gt;
&lt;h3&gt;阶段 1：角色设定表——把人物先锁死&lt;/h3&gt;
&lt;p&gt;这是整条流水线里最不能省的一步。技能会为每个角色生成一张设定表：同一角色的多个角度（正面、侧面、四分之三侧面等）加一组表情（喜、怒、哀、惊等），先把「这个人长什么样」钉死成图片资产。&lt;/p&gt;
&lt;p&gt;后面所有阶段——关键帧、每场的提示词——都要引用这张设定表作为人物依据。顺序反过来是不行的：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;如果跳过角色设定直接逐场生成，每一场里的人物都会被模型重新「想象」一遍，八场戏能给你八张不同的脸&amp;lt;/span&amp;gt;。先锁人、再讲故事，是这条流水线和「随手生成片段」最本质的区别。&lt;/p&gt;
&lt;h3&gt;阶段 2：故事圣经——把故事写成文件&lt;/h3&gt;
&lt;p&gt;这一阶段产出的是整部片子的总纲，样片里对应 &lt;code&gt;examples/the-last-lantern/STORY.md&lt;/code&gt;，内容包括：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Logline&lt;/strong&gt;：一句话说清这部片子讲什么。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;世界与角色锁定说明&lt;/strong&gt;：故事发生的世界长什么样、每个角色的外貌与性格锚点，和阶段 1 的设定表互相印证。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;逐场大纲&lt;/strong&gt;：每一场发生什么、情绪如何推进、有哪些贯穿全片的视觉母题（样片里反复出现的灯笼意象就是这样被写进总纲的）。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;故事圣经的意义在于「先文字、后画面」：故事层面的问题在这一阶段改，成本只是改几行字；等生成完视频再发现剧情不对，成本就是全部重做。&lt;/p&gt;
&lt;h3&gt;阶段 3：关键帧——K1 到 K(N+1) 与 match-cut&lt;/h3&gt;
&lt;p&gt;关键帧是这条流水线里最有「片场味」的一环。N 场戏需要 N+1 张关键帧：K1 是第一场的起始画面，K2 既是第一场的结束画面、又是第二场的起始画面，依此类推，直到 K(N+1) 收尾。样片的 &lt;code&gt;FLOW.md&lt;/code&gt; 里就完整记录了这条关键帧链。&lt;/p&gt;
&lt;p&gt;它遵循的是 &lt;strong&gt;match-cut 衔接律&lt;/strong&gt;：相邻两场在衔接点上画面要素要对得上——人物位置、姿态、光线、构图不能跳。原理很直接：每段视频是「从首帧生成到尾帧」，如果上一段的尾帧就是下一段的首帧，两段天然严丝合缝；反之，衔接处必然出现肉眼可见的跳变。&lt;/p&gt;
&lt;p&gt;:::warning
关键帧阶段最常见的偷懒是只给每场一张「代表图」而不是首尾共用的衔接帧。这样每段视频的起止画面互不对齐，拼起来必然跳帧，后期再怎么加转场也救不回来。N+1 张一张都不能少。
:::&lt;/p&gt;
&lt;h3&gt;阶段 4：Mega Prompt——每场一条，拿来就能粘&lt;/h3&gt;
&lt;p&gt;分镜和关键帧定稿后，这一阶段为每一场戏写一条「mega prompt」：一条完整、自包含、可以直接粘贴去生成的提示词，把该场的画面内容、人物引用、镜头运动、氛围、衔接要求全部写在一条里。样片里对应 &lt;code&gt;MEGA_PROMPTS.md&lt;/code&gt;，8 场戏就是 8 条，外加每条的参考图投喂顺序和合成备注。&lt;/p&gt;
&lt;p&gt;这种「一场一条大提示词」的写法，和 &lt;a href=&quot;/posts/ai-muse-video-prompt/&quot;&gt;AI 视频提示词工作流&lt;/a&gt; 里讲的六段式结构化提示词是同一个思路：把信息一次交代完整，减少模型自由发挥的空间，翻车了也容易定位是哪一项写错了。&lt;/p&gt;
&lt;h3&gt;阶段 5：视频生成——首帧到尾帧，逐段推进&lt;/h3&gt;
&lt;p&gt;拿着关键帧和 mega prompt 逐段生成视频：每段以本场的首帧为起点、尾帧为终点来生成（first-frame → last-frame）。一段确认一段，不合格就只重做这一段，不牵连其他场次。这也是为什么前面要把故事圣经和关键帧做扎实——生成阶段的问题越少，这一步就越接近「流水线作业」而不是「抽卡」。&lt;/p&gt;
&lt;h3&gt;阶段 6：旁白与配音&lt;/h3&gt;
&lt;p&gt;画面齐了之后写旁白脚本。样片里对应 &lt;code&gt;VO_SCRIPT.md&lt;/code&gt;：解说词按时间轴标注，每一段对应哪场画面、从第几秒开始，都写清楚，并且给了英越双语两版。脚本定稿后再生成配音音频。配音本身的工具选型（转写、合成、音色）可以参考 &lt;a href=&quot;/posts/ai-voice-whisper-tts/&quot;&gt;AI 语音实战&lt;/a&gt;，本技能负责的是「文案与画面对位」这一层。&lt;/p&gt;
&lt;h3&gt;阶段 7：合成成片——ffmpeg 收尾&lt;/h3&gt;
&lt;p&gt;最后一步是纯手工活的自动化：用 ffmpeg 把所有片段做规格化处理（统一分辨率、帧率、编码），按顺序拼接，再把配音（以及音乐）混进去，输出最终的 MP4。命令骨架大致如下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 逐段规格化：统一到 1920x1080、30fps、H.264
ffmpeg -i scene1_raw.mp4 -vf &quot;scale=1920:1080,fps=30&quot; -c:v libx264 -pix_fmt yuv420p s1.mp4

# 2. 按清单拼接
ffmpeg -f concat -safe 0 -i list.txt -c copy joined.mp4

# 3. 混入旁白音轨
ffmpeg -i joined.mp4 -i vo.mp3 -c:v copy -c:a aac -shortest final.mp4
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;-shortest&lt;/code&gt; 只是兜底写法，正经做法是让旁白脚本的时间轴在阶段 6 就和画面对齐，而不是靠合成时硬截断。&lt;/p&gt;
&lt;h2&gt;贯穿全程的三条硬规则&lt;/h2&gt;
&lt;p&gt;流水线之外，仓库还立了几条不许打折的硬规则，它们才是这套技能区别于「随便聊聊就生成」的关键。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一，物理真实律。&lt;/strong&gt; 动画可以夸张，但动作和物理必须讲得通：东西掉下去要加速，人物转身要有重心，水和布料的运动要符合常识。提示词和关键帧都要按真实物理来设计，否则生成出来的动作会透着一股「假」。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二，画幅严格锁定。&lt;/strong&gt; 开场定的 16:9 或 9:16，全程所有参考图、关键帧、生成片段必须同画幅。参考图和输出画幅不一致，是竖屏成片里人物变形、构图错位的一大来源，所以这条被写成全大写的严格规则。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三，每个阶段都有确认点。&lt;/strong&gt; 角色设定、故事圣经、关键帧、逐段视频、旁白、终片——每一关你都要看一眼再放行。这和 &lt;a href=&quot;/posts/ai-muse-video-skill/&quot;&gt;muse-video-skill&lt;/a&gt; 里「分阶段审核门禁」的理念一致：把返工留在便宜的阶段，别把问题攒到成片才发现。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;八个阶段加三条硬规则，本质上是把「导演的脑子」拆成了文件和检查点：创意可以天马行空，执行必须按表推进。&lt;/strong&gt;&lt;/p&gt;
&lt;h2&gt;样片拆解：《The Last Lantern》是怎么做出来的&lt;/h2&gt;
&lt;p&gt;判断一套流程靠不靠谱，最好的办法是看它有没有留下真实的过程文件。这个仓库附带了完整样片《The Last Lantern》（中译可作《最后一盏灯笼》）：8 场戏、2D 迪士尼/皮克斯风格，&lt;code&gt;examples/the-last-lantern/&lt;/code&gt; 目录里躺着四份真实文件，正好对应流水线的关键阶段：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;文件&lt;/th&gt;
&lt;th&gt;内容&lt;/th&gt;
&lt;th&gt;对应阶段&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;STORY.md&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;故事圣经：logline、世界观、角色锁定、8 场节拍、音乐母题&lt;/td&gt;
&lt;td&gt;阶段 2&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;MEGA_PROMPTS.md&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;8 条可直接粘贴的 mega prompt，附参考图投喂顺序与合成备注&lt;/td&gt;
&lt;td&gt;阶段 4&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;VO_SCRIPT.md&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;英越双语旁白脚本，带时间轴标注&lt;/td&gt;
&lt;td&gt;阶段 6&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;FLOW.md&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;全片如何流经八个阶段：每阶段做了什么、产出什么、在哪里确认、关键帧链如何衔接&lt;/td&gt;
&lt;td&gt;全程&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;从这四份文件能读出几个值得抄的细节：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;角色先行&lt;/strong&gt;：样片有 Milo、Lyra、Ember 三个角色，每个都先有设定表，故事圣经里再用文字把外貌锚点复述一遍，图片锁定加文字锁定双保险。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;母题贯穿&lt;/strong&gt;：灯笼作为视觉母题被写进故事圣经，在多场戏里反复出现，短片因此有了统一的记忆点，而不是八段互不相干的小品。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;过程可审计&lt;/strong&gt;：&lt;code&gt;FLOW.md&lt;/code&gt; 把每个阶段的确认点都记了下来，哪一步是谁拍的板、关键帧链怎么排布，事后都能复盘——这正是新手最缺的东西：不是「做出来了」，而是「知道自己是怎么一步步做出来的」。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;想上手的话，最稳妥的路径是先把这四份文件通读一遍，再照着同样的结构做自己的第一部短片，等于有了一份填空模板。&lt;/p&gt;
&lt;h2&gt;它沉淀的实战教训（挑典型的说）&lt;/h2&gt;
&lt;p&gt;仓库的参考文档里专门有一份经验教训（&lt;code&gt;references/08-lessons.md&lt;/code&gt;），收了十多条用真实翻车换来的结论。挑几条最典型的：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;人物不一致是头号杀手，而且病根在前面&lt;/strong&gt;。成片里角色变脸，十有八九不是生成阶段的问题，而是阶段 1 设定表没锁牢、或者后面的提示词没有严格引用设定表。修法永远是往上游追，而不是在成片上打补丁。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;衔接帧省不得&lt;/strong&gt;。曾经想省事跳过共用衔接帧，结果每段交界处都跳，返工量比老老实实做 N+1 张关键帧大得多。这也是 match-cut 被写成「律」的原因。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;参考图画幅不一致会污染全片&lt;/strong&gt;。只要有一张参考图画幅不对，它参与生成的那一段构图就会歪，还会把错误带进后续衔接。所以画幅锁定要在投喂任何素材之前先检查。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;旁白要按时间轴写，不要按文案写&lt;/strong&gt;。先写一篇优美散文再硬塞进画面，必然对不上；正确顺序是先有画面时长，再逐段配词，宁可句子短一点。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;一段一段确认，不要攒着批量生成&lt;/strong&gt;。八段一口气全生成完再看，等于把八次小返工攒成一次大返工。逐段确认看着慢，总账反而最快。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;这些教训的共同点是：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;翻车几乎都发生在「省了一步」的地方&amp;lt;/span&amp;gt;——省了设定表、省了衔接帧、省了逐段确认。流程之所以是流程，就是因为每一步都在替后面省钱。&lt;/p&gt;
&lt;h2&gt;适合谁、不适合谁&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;适合的人&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;想做完整短片而不是单个片段的内容创作者：故事短片、品牌小动画、节日祝福片、给孩子讲的故事动画。&lt;/li&gt;
&lt;li&gt;愿意按流程走、能在每个确认点花几分钟看产出的人——这套技能的价值一半在流程纪律，跳步使用等于自废武功。&lt;/li&gt;
&lt;li&gt;想学动画制片逻辑的新手：八个阶段本身就是一张动画生产地图，做完一部片子，整个行业的分工顺序也就摸清了。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;不适合的人&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;只想快速出一个几秒钟片段发着玩的——杀鸡用牛刀，直接用生成工具更快。&lt;/li&gt;
&lt;li&gt;追求长篇、强连续叙事的：它的场景量级是为短片设计的，长片的人物与剧情管理复杂度是另一个问题。&lt;/li&gt;
&lt;li&gt;完全不想做任何确认、只想一句话等成片的：它的设计哲学就是「每个阶段停一下」，和全自动流水线是两种取向。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
还有一条现实提醒：这套技能依赖 Muse 的图片、视频、音频生成能力，不同账号、不同地区可用的生成能力并不一致。开工前先确认自己的环境能生成视频和音频，否则流程会卡在阶段 5 和阶段 6，与其做到一半才发现，不如先拿一小段做端到端验证。
:::&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：做到一半发现角色在某一段变脸了，怎么办？&lt;/strong&gt;
回到阶段 1 检查该角色的设定表是否足够清晰（角度和表情是否齐全），再检查出问题那一段的 mega prompt 有没有正确引用设定表。只重做这一段，不要动其他已确认的段落。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：两段视频拼起来明显跳一下，是哪里的问题？&lt;/strong&gt;
优先怀疑关键帧链：上一段的尾帧和下一段的首帧是不是同一张 K 帧。如果当初是各场各用一张代表图，就会出现这个问题，需要补齐 N+1 张衔接帧后重做相邻段落。其次检查两段的分辨率、帧率是否一致，合成前先做规格化。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：竖屏片子里人物被拉长/压扁？&lt;/strong&gt;
典型的画幅污染：混入了横屏的参考图或关键帧。逐张检查本片用到的所有图片素材，画幅必须与开场定的 9:16 完全一致，不一致的重新生成，不要将就。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：旁白和画面对不上，总是快几秒或慢几秒？&lt;/strong&gt;
旁白脚本没有按时间轴写。回到阶段 6，按每场画面的实际时长逐段核算文案长度，先定时长、再填词；合成阶段只做微调，不要指望 &lt;code&gt;-shortest&lt;/code&gt; 之类的参数救场。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：能不能跳过故事圣经，边想边做？&lt;/strong&gt;
短片最忌讳这个。故事层面的改动在文字阶段成本最低，一旦进入关键帧和生成阶段，每改一次剧情都要连带重做帧和片段。真想调整，回到阶段 2 改文件，再顺着流水线往下重走受影响的部分。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：仓库文档有越南语，看不懂怎么办？&lt;/strong&gt;
仓库的技能文件与参考文档以越南语和英文为主，但你的使用界面是和 Muse 的对话：直接用中文提需求、中文确认即可，流程产出（故事圣经、旁白脚本等）的语言在开场三问里就定好了，选中文就会全程中文产出。样片文件里的英文部分（&lt;code&gt;STORY.md&lt;/code&gt;、&lt;code&gt;MEGA_PROMPTS.md&lt;/code&gt; 等）本身可读性也很好，配合翻译工具通读没有障碍。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：第一部片子建议做多长？&lt;/strong&gt;
建议从 8 场左右的短结构开始，和样片同量级：足够讲完一个完整小故事，又不至于因为战线太长而中途崩盘。流程跑顺之后再考虑加场。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Muse-animated-short-film 的价值，可以用一句话概括：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;它把动画短片制作从「灵感加抽卡」变成了「八个阶段的流水线作业」&amp;lt;/span&amp;gt;——先定三件事（时长、语言、画幅），再锁人物、写圣经、排关键帧、逐场生成、配旁白、ffmpeg 成片，三条硬规则（物理真实、画幅锁定、逐段确认）贯穿始终。&lt;/p&gt;
&lt;p&gt;它和本系列的另外两篇正好凑齐 AI 视频的完整链条：&lt;a href=&quot;/posts/ai-muse-video-skill/&quot;&gt;muse-video-skill&lt;/a&gt; 管前期策划，&lt;a href=&quot;/posts/ai-muse-video-prompt/&quot;&gt;muse-video-prompt-skill&lt;/a&gt; 管生成端提示词，这一篇管「把一部片子真正做完」。如果你手里已经攒了一堆互不相干的生成片段，缺的可能正是这样一条带检查点的流水线。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：AI 视频提示词工作流 muse-video-prompt-skill</title><link>https://www.anexns.cloudns.org/posts/ai-muse-video-prompt/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-muse-video-prompt/</guid><description>给 AI 助手装上 muse-video-prompt-skill 技能包：六段式提示词模板写准每一镜，多段拼接把 10 秒短片拼成连贯长片，再用抽帧脚本逐帧验证生成结果，把 AI 短视频从抽卡变成可复现的工作流。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：AI 短视频难的不是生成，是后面三件事&lt;/h2&gt;
&lt;p&gt;现在随便打开一个 AI 视频工具，输入一句话就能出片，看起来门槛已经低到没有了。但真动手做几条就会发现，卡住人的从来不是&quot;点生成&quot;这一下，而是三件具体的事：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;提示词写不准。&lt;/strong&gt; 脑子里画面很清楚，写出来三行字，模型理解成另一个样子。镜头语言、节拍、人物状态全靠临场发挥，每次生成都像开盲盒。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;长片拼不连贯。&lt;/strong&gt; 单段视频就十秒上下，想做 30 秒以上的内容只能分段生成，可段与段之间人物变脸、场景跳变、光线乱飘，拼起来像三个不同的人演的。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;人物不崩不住。&lt;/strong&gt; 参考图明明是同一个人，生成到第二段就换了张脸；你说不清是哪句提示词的问题，也没有验证手段，只能重抽。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这三件事的共同点是：它们都不是模型能力问题，而是&lt;strong&gt;流程问题&lt;/strong&gt;。没有模板，提示词质量全靠手感；没有拼接规范，长片必然散架；没有验证环节，偏差只能靠肉眼在成片里找，找到了也不知道怎么改。&lt;/p&gt;
&lt;p&gt;muse-video-prompt-skill 就是冲着这三件事来的：它是一套给 AI 助手用的技能包（Agent Skill），把&quot;写提示词 → 生成 → 拼接 → 验证&quot;做成一个有模板、有脚本、有案例库的实战闭环。本篇主线：&lt;strong&gt;装上技能包 → 用六段式模板写准提示词 → 三个变体覆盖常见拍法 → 多段拼接做长片 → 抽帧验证把偏差写在纸上 → 最后认清它的能力边界&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/masonmosen/muse-video-prompt-skill&lt;/p&gt;
&lt;h2&gt;它是什么：一套装在 Agent 里的视频实战闭环&lt;/h2&gt;
&lt;p&gt;先把定位说清楚。muse-video-prompt-skill 不是一个视频生成工具，它本身不生成任何视频。它是一套 &lt;strong&gt;Skill（技能包）&lt;/strong&gt;——一组写给 AI 助手读的规范文档加一个验证脚本，装进你用的 Agent（比如 Muse、Muse 这类支持 Skill 的助手）之后，助手在帮你做视频时会自动按这套规范干活：写提示词时套六段式模板，生成长片时按节拍拆段拼接，每段生成完自动抽帧核对，结果沉淀进案例库。&lt;/p&gt;
&lt;p&gt;仓库结构很小，一眼能看完：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;文件&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SKILL.md&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;技能入口：整套工作流与操作规范&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;CONSTITUTION.md&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;设计原则：诚实、成片优先、短闭环、复利、精简&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;references/prompt-template.md&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;六段式提示词模板＋三个变体&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;references/model-notes.md&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;内置视频模型的实测能力边界&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;references/consistency.md&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;人物一致性打法&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;references/dialogue.md&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;对白规范（默认台湾腔国语，可改）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;references/stitch-workflow.md&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;分段 → 拼接 → 验证流程&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;references/cases/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;案例库：每次实验一张案例卡&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;bin/extract_frames.py&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;抽帧自检脚本&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这套东西和&quot;前期策划型&quot;技能的分工不同：像 &lt;a href=&quot;/posts/ai-muse-video-skill/&quot;&gt;muse-video-skill&lt;/a&gt; 那种虚拟剧组引擎负责开拍前的剧本、分镜、美术策划，产出策划案；而 muse-video-prompt-skill 负责的是&lt;strong&gt;生成端闭环&lt;/strong&gt;——策划定了之后，提示词怎么写、片怎么拼、结果怎么验。两者一前一后，可以串起来用。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;一句话定位：它管的不是创意，是把创意稳定地变成成片的执行流程。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;安装：克隆下来放进 skills 目录&lt;/h2&gt;
&lt;p&gt;安装没有包管理器，就是克隆仓库、把目录放进你所用 Agent 的 skills 目录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git clone https://github.com/masonmosen/muse-video-prompt-skill.git

# 放进所用 Agent 的 skills 目录，例如 Claude Code：
# ~/.claude/skills/muse-video-prompt-skill/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;放好之后不用做任何配置。下次在对话里提出视频需求，Agent 会自动加载这套技能，按里面的模板和流程推进。抽帧验证依赖 &lt;code&gt;bin/extract_frames.py&lt;/code&gt;，它底层调 ffmpeg 抽帧，所以本机需要装有 ffmpeg，这个后面排障一节还会提到。&lt;/p&gt;
&lt;h2&gt;核心武器：六段式提示词模板逐段讲&lt;/h2&gt;
&lt;p&gt;整套技能的心脏是六段式提示词模板。它把一条视频提示词拆成六个固定段落，缺哪段补哪段，写的时候逐段过一遍，模型就没有发挥跑偏的空间。&lt;/p&gt;
&lt;h3&gt;第一段：时长与画幅&lt;/h3&gt;
&lt;p&gt;先钉死物理参数：总时长、画幅比例、帧率倾向。长片还要在这里写明分段方案（比如&quot;共 3 段，每段约 10 秒&quot;）。这一段看似废话，但画幅写错一次，整条片子的构图全废，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;返工成本最高的错误往往就出在这第一行&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h3&gt;第二段：人物&lt;/h3&gt;
&lt;p&gt;人物段只写&quot;不会变的东西&quot;：年龄段、发型发色、服装、体型、标志性特征。关键原则是&lt;strong&gt;用参考图锁定长相，用文字锁定状态&lt;/strong&gt;——文字里不要反复描摹五官细节，那样反而容易和参考图打架。跨段复用时，人物段整段原样复制，一个字不改，这是保连贯最便宜的办法。&lt;/p&gt;
&lt;h3&gt;第三段：场景&lt;/h3&gt;
&lt;p&gt;场景段写环境、时间、光线、氛围。光线尤其要写死：同一场景第二段光线从&quot;午后侧光&quot;飘成&quot;黄昏逆光&quot;，观众立刻出戏。场景段和人物段一样，跨段原样复用，只改动真正发生变化的部分（比如人物走进了另一个房间）。&lt;/p&gt;
&lt;h3&gt;第四段：节拍时间轴&lt;/h3&gt;
&lt;p&gt;这是六段里最重要、也最容易被省略的一段。把时长切成小段，每段写清这一两秒内发生什么动作、镜头怎么动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;0-3s：人物推门走入，镜头固定在门口机位
3-6s：人物走到窗边停下，镜头缓慢推近
6-10s：人物回头看向镜头，微笑，画面定格感收尾
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;没有节拍，模型会把十秒钟填满匀速的、无重点的运动；有了节拍，生成结果才有&quot;剪辑感&quot;。多段长片拆段时，也是按节拍表切段——每一段对应节拍表的一行或几行。&lt;/p&gt;
&lt;h3&gt;第五段：镜头语言&lt;/h3&gt;
&lt;p&gt;机位（固定/手持/轨道）、景别（特写/中景/全景）、运动方式（推/拉/摇/移）单独成段，不要混在动作描述里。把镜头语言独立出来有个好处：想换运镜时只改这一段，不会误伤人物和场景。&lt;/p&gt;
&lt;h3&gt;第六段：声音、对白与限制清单&lt;/h3&gt;
&lt;p&gt;最后一段收口，分三块：环境声与音乐要求；对白原文（逐字写出，标注语气，默认台湾腔国语，可按需改成其他口音或语言）；以及&lt;strong&gt;限制清单&lt;/strong&gt;——明确写出不要出现的东西：不要字幕水印、不要多余人物、不要镜头旋转、不要人物变形。限制清单不是凑数，实测里很多翻车都是因为该禁的没写。&lt;/p&gt;
&lt;h3&gt;一个完整可抄的示例&lt;/h3&gt;
&lt;p&gt;把六段拼起来，一条能直接用的提示词长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;10 秒，9:16 竖屏，单段成片。
28 岁女性，黑色长发低马尾，米白色针织开衫、浅蓝牛仔裤，
左手腕戴银色细手链。全程同一人、同一套服装。
晴天午后，老城区临街咖啡馆外摆区，木桌藤椅，
背景是虚化的行人与梧桐树影，阳光从画面左侧斜射，暖色调。
0-3s：人物端着咖啡从画面右侧走入，在木桌旁坐下；
3-6s：放下咖啡杯，抬头望向街道，头发被微风吹动；
6-10s：人物转头看向镜头，微笑，轻轻点头。
中景固定机位，轻微手持呼吸感，不推拉不旋转，
人物始终位于画面中下部。
环境声：街道远景人声、杯盘轻响、微风；
无对白；背景音乐：轻柔的原声吉他，音量低。
不要出现文字与水印；不要多余人物入镜特写；
不要改变人物长相与服装；不要快速运动与镜头旋转。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拿这个骨架对照自己以前写的提示词，差距通常出在节拍和限制两段——这两段恰恰是返工率最高的重灾区。&lt;/p&gt;
&lt;h2&gt;三个变体：POV、口播、多段长片&lt;/h2&gt;
&lt;p&gt;六段式是通用骨架，仓库里还给了三个针对高频拍法的变体，结构不变，侧重点不同：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;变体&lt;/th&gt;
&lt;th&gt;适用场景&lt;/th&gt;
&lt;th&gt;与通用版的关键区别&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;POV 生活流&lt;/td&gt;
&lt;td&gt;第一人称日常、探店、旅行记录&lt;/td&gt;
&lt;td&gt;人物段改为&quot;只露手部与局部&quot;，镜头段强调手持晃动与视线逻辑&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;口播&lt;/td&gt;
&lt;td&gt;出镜讲解、知识短视频&lt;/td&gt;
&lt;td&gt;节拍按文案句子切分，对白段逐句对齐时间轴，限制段禁字幕（字幕后期加）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;多段长片&lt;/td&gt;
&lt;td&gt;30 秒以上的剧情或记录短片&lt;/td&gt;
&lt;td&gt;每段独立六段式，靠节拍总表统一拆分，段间用快照接续（见下一节）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选变体的原则很简单：拍法对上号就用变体，对不上就用通用骨架自己裁。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要为了用变体而扭曲内容&amp;lt;/span&amp;gt;，模板是为内容服务的。&lt;/p&gt;
&lt;h2&gt;多段拼接：把 10 秒拼成 30 秒以上&lt;/h2&gt;
&lt;p&gt;内置视频生成单段大约 10 秒就是硬上限，想做长片只有一条路：拆段生成、无损拼接。这套工作流的拆法是&lt;strong&gt;按节拍拆&lt;/strong&gt;，不是按时长硬切：先写全片节拍总表，再在动作自然收束的节拍点上切段，每段独立写一份六段式提示词。&lt;/p&gt;
&lt;p&gt;连贯性靠两个动作保住：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;快照接续。&lt;/strong&gt; 上一段生成完，截取它的尾帧（或关键帧）作为快照，下一段生成时以这张快照为起点参考——人物站位、光线、服装状态从上一段的终点接着走，而不是每段从零脑补。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;复用段落。&lt;/strong&gt; 人物段、场景段在各段之间整段复制，只改节拍段和发生变化的局部。改得越少，漂得越少。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;拼接用 ffmpeg 无损合并（流复制，不重新编码），画质零损失，速度也快：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 先生成片段清单，再无损拼接
printf &quot;file &apos;seg1.mp4&apos;\nfile &apos;seg2.mp4&apos;\nfile &apos;seg3.mp4&apos;\n&quot; &amp;gt; list.txt
ffmpeg -f concat -safe 0 -i list.txt -c copy final.mp4
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
无损拼接的前提是各段的编码参数、分辨率、帧率完全一致。生成时把画幅和参数钉死在第一段里，就是为了让最后这一步能用 &lt;code&gt;-c copy&lt;/code&gt; 直接拼；参数不一致时 ffmpeg 会报错或拼出花屏，只能重编码，画质和时间都得搭进去。
:::&lt;/p&gt;
&lt;p&gt;仓库里的实测案例就是这么来的：一条 30 秒出头的旅行短片，9:16，按节拍拆成三段，逐段生成、快照接续、无损拼成成片——全过程沉淀在案例库里可查。&lt;/p&gt;
&lt;h2&gt;抽帧验证：生成完先别高兴，逐帧对账&lt;/h2&gt;
&lt;p&gt;这是这套技能和&quot;写完提示词就完事&quot;的教程最大的区别：&lt;strong&gt;每段生成完，自动抽帧核对&lt;/strong&gt;。用仓库自带的脚本：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;python bin/extract_frames.py &amp;lt;视频文件&amp;gt; &amp;lt;输出目录&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;脚本把视频按时间抽成一帧帧图片，然后逐项对账：提示词里写了的，哪些真的出现在画面里；没写的，哪些自己长出来了；人物和上一段比，脸、服装、发型漂了没有。对账结果要落成文字结论——哪段合格、哪段要重生成、重生成时改哪一句提示词。&lt;/p&gt;
&lt;p&gt;这一步看着繁琐，实际是省钱的：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;偏差在单段阶段发现，成本是重抽一段；拖到成片阶段才发现，成本是整条重做。&amp;lt;/span&amp;gt;尤其是人物漂移，单段抽帧时两张图并排一比就现形，混在成片里反而容易被动作和剪辑掩盖过去。&lt;/p&gt;
&lt;h2&gt;案例库：每次实验沉淀一张卡&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;references/cases/&lt;/code&gt; 是案例库，每次做片——不管成败——都沉淀一张案例卡，记录四件事：提示词要点、生成结果、偏差在哪、教训是什么。仓库里既有全链路跑通的正面案例（旅行短片：提示词 → 多段拼接 → 抽帧验证全程留档），也留着负面案例：一条三段的短片，三段用了三张不同的脸——快照接续没能锁住人物，这个失败被原样保留在库里，标注为能力上限的证据。&lt;/p&gt;
&lt;p&gt;案例库的价值在复利：下次遇到类似拍法，先翻卡，知道哪句提示词有效、哪个坑踩过，不用每次从零试错。用得越久，这套技能越贴合你自己的题材和翻车史。&lt;/p&gt;
&lt;h2&gt;诚实边界：锁脸弱，就别硬吹&lt;/h2&gt;
&lt;p&gt;最后必须正式说一节它的短板，因为这套技能自己把短板写在了明处，这也是它值得信任的原因。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;内置视频生成的锁脸能力是弱的。&lt;/strong&gt; 用参考图做首帧或快照接续，能提高相似度，但不保证像本人：快照传递的是构图和状态，不是面部身份。前面提到的负面案例就是实证——三段拼完，三张脸。技能的态度是动手前先把边界说清，而不是拿话术包装过去。&lt;/p&gt;
&lt;p&gt;所以适用与不适用要分清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;需求&lt;/th&gt;
&lt;th&gt;建议&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;视频提示词实验、写法打磨&lt;/td&gt;
&lt;td&gt;直接用，模板和验证闭环就是为此而生&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;短视频、多段拼长片（人物一致性要求一般）&lt;/td&gt;
&lt;td&gt;可以用，靠快照接续＋段落复用把漂移压到可接受&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;强锁脸项目（本人出镜、品牌代言人、剧情主角全程不换脸）&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要硬上内置生成&amp;lt;/span&amp;gt;，走 Seedance 等第三方视频模型，技能本身也会明确这样建议&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;把边界说在前面，不是劝退，是省得你在锁脸项目上烧掉一下午的生成次数才发现此路不通。这条诚实线和它背后的整套验证机制，恰恰是它区别于&quot;万能提示词大全&quot;的地方。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：装上技能后，助手没有按模板写提示词？&lt;/strong&gt;
先确认目录放对了：技能目录要完整放进所用 Agent 的 skills 目录下（目录名就是 &lt;code&gt;muse-video-prompt-skill&lt;/code&gt;，里面直接是 &lt;code&gt;SKILL.md&lt;/code&gt;）。放错一层、或者只拷了单个文件，Agent 就加载不到。另外要在对话里明确提出视频需求，技能是按需触发的。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：抽帧脚本跑不起来？&lt;/strong&gt;
&lt;code&gt;extract_frames.py&lt;/code&gt; 依赖 ffmpeg，先在终端跑 &lt;code&gt;ffmpeg -version&lt;/code&gt; 确认装了且在 PATH 里。视频路径带空格或中文时给路径加引号。还不行就手动抽一帧验证链路：&lt;code&gt;ffmpeg -i seg1.mp4 -vf &quot;select=&apos;eq(n\,0)&apos;&quot; -vframes 1 frame.png&lt;/code&gt;，能出图说明 ffmpeg 没问题，问题在脚本参数。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：多段拼接时 ffmpeg 报错或拼出来花屏？&lt;/strong&gt;
基本都是各段参数不一致：分辨率、帧率、编码器只要有一项不同，&lt;code&gt;-c copy&lt;/code&gt; 就拼不了。回生成环节把每段的画幅与参数对齐重生成问题段；实在对不齐，只能放弃无损拼接，用重编码方式合并（画质略有损失）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：人物第二段就换脸了，怎么办？&lt;/strong&gt;
先看抽帧对账：漂移出在人物段被改动、还是快照没接上。人物段必须跨段整段复制；快照要用上一段的尾帧而不是随便一帧。如果两样都做对了还是漂，那就是当前内置生成的锁脸上限——降低一致性要求（背影、侧脸、远景镜头绕开正脸特写），或者换第三方模型，这不是改提示词能解决的。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：对白口型对不上、口音不对？&lt;/strong&gt;
对白段要逐字写全，含标点和语气标注，模型对&quot;大概意思&quot;式的对白描述还原度很差。口音默认是台湾腔国语，想换在对白段开头明确写明目标口音或语言，别只在聊天里口头说一句。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：提示词写得很全，模型还是漏要素？&lt;/strong&gt;
把抽帧对账的结论喂回去：哪条没吃进去，就把那条从散文里拎出来，在对应段落里提前、加具体（比如把&quot;微笑&quot;改成&quot;嘴角上扬、露出上排牙齿的微笑&quot;）。一次只改一两处，改完重抽验证，别一口气重写整条提示词——那样你永远不知道哪句起的作用。更多通用的提示词方法论，可以看本系列的&lt;a href=&quot;/posts/ai-prompt-engineering/&quot;&gt;提示词工程实战&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：想做动画短片而不是实拍风短片，适合用这套吗？&lt;/strong&gt;
可以借用它的模板与验证流程，但动画短片有角色设定表、故事圣经这类专属环节，本系列另有 &lt;a href=&quot;/posts/ai-muse-animated-film/&quot;&gt;Muse 动画短片全流程&lt;/a&gt; 一篇专门讲那套技能，分工更对口。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;muse-video-prompt-skill 的价值不在某条神奇提示词，而在它把 AI 视频制作变成了有章法的流程：六段式模板让提示词写得准，节拍拆段＋快照接续＋ffmpeg 无损拼接让长片拼得连贯，抽帧验证让偏差在单段阶段就暴露，案例库让经验沉淀复用。它同样把边界写在明处：内置生成锁脸弱，强锁脸需求请走第三方模型——先说清，再开工。&lt;/p&gt;
&lt;p&gt;如果你正打算系统地做 AI 短视频，建议顺序是：先用本篇这套生成端闭环把单条片子做稳，再按需要往前接 &lt;a href=&quot;/posts/ai-muse-video-skill/&quot;&gt;muse-video-skill&lt;/a&gt; 的前期策划、往专精接动画短片流程。流程先行，抽卡靠后。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：虚拟剧组 muse-video-skill 视频前期策划</title><link>https://www.anexns.cloudns.org/posts/ai-muse-video-skill/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-muse-video-skill/</guid><description>muse-video-skill 把 AI Agent 变成一支虚拟剧组：六角色协作、38 个标杆案例技法库、8+1 阶段管线与审核门禁，从一句创意产出剧本、分镜、美术方向与可直接喂给下游视频模型的调用指令。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：视频做不出来，往往不是生成的问题，是策划的问题&lt;/h2&gt;
&lt;p&gt;很多人第一次做 AI 视频的流程是这样的：脑子里有个模糊的想法，打开生成工具，敲一句提示词，抽卡，等结果。不满意，改两个词，再抽。一下午过去，素材攒了一堆，没有一段能剪到一起。&lt;/p&gt;
&lt;p&gt;问题不在生成端，在开拍之前。真实剧组从来不是这么干活的：一部片子在按下录制键之前，先有剧本，再有分镜，美术定过色调，摄影定过机位，连字幕和音乐的路线都提前谈好了。生成阶段只是执行，策划阶段才决定成片长什么样。个人创作者缺的不是生成工具，缺的正是这套前期策划。&lt;/p&gt;
&lt;p&gt;muse-video-skill 就是补这一环的：它是一个装进 AI Agent 的技能（Skill），把 Agent 组织成一支虚拟剧组，专门产出&lt;strong&gt;一个视频开拍前需要的全部策划案&lt;/strong&gt;——剧本、分镜、美术方向、提示词，最后编译成下游视频模型可以直接执行的调用指令。本篇主线：&lt;strong&gt;它解决什么问题 → 虚拟剧组怎么分工 → 案例库怎么用 → 8+1 阶段管线与门禁 → 产出物长什么样 → Phase 7.5 模型编译 → 两条管线与场景模板 → 安装与分工边界&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/LuoJiangYong/muse-video-skill&lt;/p&gt;
&lt;h2&gt;它解决什么问题&lt;/h2&gt;
&lt;p&gt;对照真实创作里最常见的四个卡点，看它分别怎么接：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;痛点&lt;/th&gt;
&lt;th&gt;具体表现&lt;/th&gt;
&lt;th&gt;muse-video-skill 的解法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;不会写专业分镜&lt;/td&gt;
&lt;td&gt;有故事，没镜头语言，分镜表写不出来&lt;/td&gt;
&lt;td&gt;好莱坞格式剧本＋6/9 宫格分镜＋技术表，文学剧本、分镜卡片、编译预览、技术表四种成品一键导出&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;风格说不清楚&lt;/td&gt;
&lt;td&gt;想要某种感觉，只能堆形容词&lt;/td&gt;
&lt;td&gt;38 个标杆案例技法库，说「参考 Apple 1984」比描述「反乌托邦蓝灰色调」快十倍&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;策划来回改、改完还是散&lt;/td&gt;
&lt;td&gt;每改一轮，人物、色调、镜头各漂各的&lt;/td&gt;
&lt;td&gt;8+1 阶段管线，每阶段 Director 审核不超过 2 轮，全程产出可追溯&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;策划案下游用不上&lt;/td&gt;
&lt;td&gt;文档写得再漂亮，生成模型读不懂&lt;/td&gt;
&lt;td&gt;Phase 7.5 模型编译：六段式 prompt＋多模态参考图映射＋调用命令＋成本估算&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;还有一个隐形痛点：参考图满天飞、对不上号。它的做法是&lt;strong&gt;参考图引用链＋资产化&lt;/strong&gt;：人物、产品主体、关键分镜、关键道具都登记成资产，分配资产 ID，后续所有环节按 ID 引用，不靠口头转述——转述一次漂移一次，这是 AI 创作里人物不一致的主要来源。&lt;/p&gt;
&lt;p&gt;先把定位说死：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;muse-video-skill 只做策划，不做生成；它产出的是「想清楚」的部分，渲染和合成交给下游工具。&amp;lt;/span&amp;gt;它明确不做视频渲染/合成，也不做 AI 生图/生视频，实际生成由 HyperFrames、ComfyUI、Kling、火山引擎这类下游工具完成。&lt;/p&gt;
&lt;h2&gt;虚拟剧组：六个角色，各管一段&lt;/h2&gt;
&lt;p&gt;它把策划工作拆给六个角色，每个角色有独立的文档，按需加载，角色之间只通过一份 Project State（JSON Schema 定义的结构化状态）传递产出——这是它工程化的关键：角色之间不靠聊天记录传话，靠结构化数据交接，所以长流程里信息不丢、不漂。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;角色&lt;/th&gt;
&lt;th&gt;职责&lt;/th&gt;
&lt;th&gt;主要产出&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Director（导演）&lt;/td&gt;
&lt;td&gt;全局把控、阶段审核、风格裁决&lt;/td&gt;
&lt;td&gt;审核意见、门禁放行/打回、最终确认&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Writer（编剧）&lt;/td&gt;
&lt;td&gt;故事与剧本&lt;/td&gt;
&lt;td&gt;好莱坞格式文学剧本：场景、对白、动作、镜头语言&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;DP（摄影）&lt;/td&gt;
&lt;td&gt;镜头与光线&lt;/td&gt;
&lt;td&gt;分镜卡片里的机位、景别、灯光方案&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Art Director（美术）&lt;/td&gt;
&lt;td&gt;视觉风格与资产&lt;/td&gt;
&lt;td&gt;色调板（hex 值＋成因说明）、风格参考、场景构成、角色设定&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;VFX（特效）&lt;/td&gt;
&lt;td&gt;特效与合成需求&lt;/td&gt;
&lt;td&gt;分镜卡片里的 VFX 标注与实现路线&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Sound Designer（声音）&lt;/td&gt;
&lt;td&gt;音频路线&lt;/td&gt;
&lt;td&gt;配乐/配音/音效的路线选择与生成 brief（只定路线，不代生成）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;六个角色不是六个摆设：管线的每个阶段由对应角色产出，再由 Director 审核，最多 2 轮，过了才进下一阶段。这套「产出—审核」的节奏，就是把真实剧组的制片流程搬进了 Agent。&lt;/p&gt;
&lt;h2&gt;38 个标杆案例技法库：风格不用形容，用片名&lt;/h2&gt;
&lt;p&gt;跟 AI 描述风格是件低效的事。你说「要高级感、电影感、冷峻一点」，模型只能猜；你说「参考《银翼杀手 2049》的巨物美学」，锚点立刻就有了。muse-video-skill 内置 38 个标杆案例，按角色维度建成六组技法交叉索引（叙事/镜头/色彩美术/特效/声音/创意广告），策划时先匹配案例，把技法注入对应角色的提示词里。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;数量&lt;/th&gt;
&lt;th&gt;代表案例&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;商业广告&lt;/td&gt;
&lt;td&gt;25&lt;/td&gt;
&lt;td&gt;Apple 1984、Guinness Surfer、Honda Cog、Sony Balls&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;电影&lt;/td&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;银翼杀手 2049、花样年华、流浪地球、环太平洋&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;LOGO 演绎&lt;/td&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;NIO 十周年、Apple Event 合集、Pixar Luxo Jr.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;短片&lt;/td&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;ACHROMA、Cosmos Laundromat&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;其他&lt;/td&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;Piper（动画）、Koyaanisqatsi（纪录片）、Machine Hallucination（实验影像）、The One Moment（MV）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;用法很直接，在任何支持 Agent Skills 的 Agent 里像平常一样说话就行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;帮我策划一个产品广告，风格参考 Apple Don&apos;t Blink
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;帮我构思科幻短片的故事板，想要银翼杀手那种巨物美学
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Agent 会自动匹配案例技法、注入角色 prompt、走管线，最后导出 Creative Package（创意包）。&lt;/p&gt;
&lt;p&gt;:::warning
案例库收录的是影视作品与广告的技法拆解，仓库里明确标注了作品与创作者，定位是学习研究。拿案例当风格锚点没问题，但&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把策划产出包装成对原作的复刻去商用发布&amp;lt;/span&amp;gt;，商标与影像版权归各自权利人所有。
:::&lt;/p&gt;
&lt;h2&gt;8+1 阶段管线与审核门禁&lt;/h2&gt;
&lt;p&gt;Default 管线一共 8 个阶段＋1 个预留阶段，大致走向是：想法路由 → 参考拆解 → 剧本 → 美术定样 → 资产准备 → 分镜 → HTML 分镜确认 → 模型编译（Phase 7.5）。每个阶段的产出都要过 Director 审核，审核不过就地返工，不把问题带到下游——越往后改，成本越高，这是制片常识。&lt;/p&gt;
&lt;p&gt;流程中有几个需要你本人拍板的&lt;strong&gt;门禁（确认环节）&lt;/strong&gt;，这是它和「一键生成」工具最大的区别：关键节点它会停下来等你确认，而不是闷头跑完给你一个惊喜或者惊吓。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;触发点&lt;/th&gt;
&lt;th&gt;你要做的动作&lt;/th&gt;
&lt;th&gt;默认行为&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Phase 3.5 风格定样&lt;/td&gt;
&lt;td&gt;看图确认色调/风格方向&lt;/td&gt;
&lt;td&gt;生图不可用时跳过&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Phase 3.5 资产生成门禁&lt;/td&gt;
&lt;td&gt;决定关键资产（人物/产品）是否生成、生成范围&lt;/td&gt;
&lt;td&gt;先出候选清单再询问&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Phase 6 分镜&lt;/td&gt;
&lt;td&gt;决定是否调用生图生成分镜图&lt;/td&gt;
&lt;td&gt;显式询问&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Phase 7 HTML 分镜&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;唯一最终确认关卡&lt;/strong&gt;，确认即锁定&lt;/td&gt;
&lt;td&gt;逐项核对后确认（四选项＋默认）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Phase 7.5 编译预览&lt;/td&gt;
&lt;td&gt;二次确认模型调用指令（含音频模型引导）&lt;/td&gt;
&lt;td&gt;导出编译预览 HTML 核对&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;Phase 7 是全局的锁定点：HTML 分镜确认之后，剧本、分镜、美术全部冻结，后面的编译只是翻译，不再改内容。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;锁定之后再想大改，等于推翻重走管线，成本最高&amp;lt;/span&amp;gt;，所以这一关值得逐项慢慢核对，不要随手点过。&lt;/p&gt;
&lt;h2&gt;产出物清单：一套 Creative Package 里有什么&lt;/h2&gt;
&lt;p&gt;一次完整策划跑完，你拿到的不是一段聊天记录，而是一套结构化成品：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;组成&lt;/th&gt;
&lt;th&gt;内容&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;剧本&lt;/td&gt;
&lt;td&gt;场景/对白/动作/镜头语言，文学剧本 HTML 导出，Courier 标准格式（好莱坞剧本的等宽字体规范）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;分镜&lt;/td&gt;
&lt;td&gt;6/9 宫格分镜卡片，每格带画面描述、机位、灯光、美术、VFX 与生图 prompt&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;美术方向&lt;/td&gt;
&lt;td&gt;色调板（hex 值＋成因字段，说明为什么是这个颜色）、风格参考、场景构成、角色设定&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;提示词&lt;/td&gt;
&lt;td&gt;每格分镜的 image_prompt，以及全片 video prompt 素材&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;字幕层&lt;/td&gt;
&lt;td&gt;文案（中/英/双语）×字体族×位置，与画面 prompt 解耦，单独编译为烧录 spec&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;音频路线&lt;/td&gt;
&lt;td&gt;配乐/配音/音效的路线选择＋生成 brief（解耦，不代生成）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;模型调用指令&lt;/td&gt;
&lt;td&gt;Phase 7.5 编译产物，见下一节&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这里有两个设计值得单独说。一是&lt;strong&gt;字幕层与画面解耦&lt;/strong&gt;：字幕文案、字体、位置单独管理，最后编译成烧录规格，而不是把字幕要求混进画面提示词里——混在一起的结果通常是模型把字「画」进画面，又丑又改不掉。二是&lt;strong&gt;色调板带成因字段&lt;/strong&gt;：不只给 hex 值，还写明每个颜色为什么在这里，后续换场景、换资产时，美术方向能延续而不是每镜重新发明。&lt;/p&gt;
&lt;h2&gt;Phase 7.5 模型编译：策划案变成机器能执行的指令&lt;/h2&gt;
&lt;p&gt;这是整个技能的收口环节，也是它区别于普通「分镜文档生成器」的地方。策划案是给人看的，视频模型要的是另一套东西。Phase 7.5 把冻结的策划案编译成：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;六段式 prompt&lt;/strong&gt;：按下游模型的提示词结构组织的完整提示词，而不是从剧本里随手摘抄的句子；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;多模态参考图映射&lt;/strong&gt;：哪张图是首帧、哪张是尾帧、哪张是形象参考（image_ref），按资产 ID 一一对应；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;调用命令&lt;/strong&gt;：可直接执行的命令行调用（如 arkcli 命令），不用你再手工拼参数；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;成本估算&lt;/strong&gt;：按镜头数与规格先算一遍账，生成之前心里有数。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;目前已适配 Seedance 2.0，下游工具配置还覆盖 ComfyUI、HyperFrames、Kling 等。编译完成后会导出一份编译预览 HTML 让你二次确认（这就是门禁表里最后一个关卡），逐镜展开核对 prompt、参考图映射和成本，没问题再真正调用下游生成。&lt;/p&gt;
&lt;p&gt;仓库里有一次完整实测可供参考：一支 90 秒棚拍广告，从参考视频拆解（Phase 1 拉片表：80 帧逐镜拆解镜头、光影、运镜、节奏、声音、字幕、技法）一路走到模型编译，19 个镜头的分镜网格、编译预览、文学剧本全部有截图留档。这种「全程留痕」的风格贯穿始终：每阶段产出带元信息，可追溯是哪一步定的、为什么这么定。&lt;/p&gt;
&lt;h2&gt;两条管线与四种场景模板&lt;/h2&gt;
&lt;p&gt;不是每个想法都值得走完 8+1 阶段。它提供两条管线：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;管线&lt;/th&gt;
&lt;th&gt;适用&lt;/th&gt;
&lt;th&gt;特点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Default&lt;/td&gt;
&lt;td&gt;完整创作：短片、广告、正经项目&lt;/td&gt;
&lt;td&gt;8 阶段＋1 预留，阶段审核齐全，门禁一个不少&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Fast-Track&lt;/td&gt;
&lt;td&gt;简单需求、快速验证想法&lt;/td&gt;
&lt;td&gt;合并阶段，一稿过，先出东西再说&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;另外内置四种场景模板：&lt;strong&gt;棚拍广告、产品演示、LOGO 演绎、科幻设定&lt;/strong&gt;，开局的路由决策树会先判场景类型与复杂度，套对应模板推进，也可以扩展自定义模板。经验法则：练手和验证想法用 Fast-Track；要交付、要系列化生产的，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;老老实实走 Default，门禁省下的返工时间远比它花掉的多。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;安装&lt;/h2&gt;
&lt;p&gt;技能采用通用 Agent Skills 格式（一个 SKILL.md 入口），任何支持 Skills 的 AI Agent 都能装。方式一是克隆，始终是最新版：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git clone https://github.com/LuoJiangYong/muse-video-skill.git

# 放入所用 Agent 的 skills 目录，例如：
#   Claude Code  → ~/.claude/skills/muse-video/
#   Hermes Agent → ~/.hermes/skills/creative/muse-video/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;方式二是通过 Hermes Skills Hub 一行安装：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;hermes skills install muse-video-skill
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;装完不用记命令，直接用自然语言提需求（参考前面案例库一节的说法），Agent 会自己走路由、匹配案例、推进管线。仓库自带开发自检脚本，装好后想验一下完整性可以跑：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;python scripts/build_index.py --check --deps   # 索引完整性 + 死链检查，期望 0 errors
python scripts/inventory.py --json             # 文件级盘点（按角色分类）
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;与生成端技能的分工&lt;/h2&gt;
&lt;p&gt;把本系列这几篇放在一起看，分工就清楚了：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;muse-video-skill（本篇）管「想清楚」&lt;/strong&gt;：剧本、分镜、美术、提示词与调用指令，止步于开拍之前；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;生成端技能管「做出来」&lt;/strong&gt;：比如 &lt;a href=&quot;/posts/ai-muse-video-prompt/&quot;&gt;muse-video-prompt-skill&lt;/a&gt; 走的是六段式提示词→生成→多段拼接→抽帧验证的实操闭环，直接对接内置视频生成；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;动画短片全流程技能管「一条龙」&lt;/strong&gt;：&lt;a href=&quot;/posts/ai-muse-animated-film/&quot;&gt;Muse-animated-short-film&lt;/a&gt; 把角色、剧本、关键帧、配音、合成打包成从想法到 MP4 的完整流水线；&lt;/li&gt;
&lt;li&gt;真正执行渲染的还可以落到 &lt;a href=&quot;/posts/ai-comfyui-beginner/&quot;&gt;ComfyUI&lt;/a&gt; 这类节点工作流工具上，Phase 7.5 的编译产物正好能喂给它。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;简单记：前期重、要专业策划案，先过虚拟剧组这一关；想法已经成熟、只差生成执行，直接用生成端技能。两边并不冲突——策划案编译出的六段式 prompt 和参考图映射，本来就是为生成端准备的。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：装上之后 Agent 没有自动走管线，还是普通聊天？&lt;/strong&gt;
先确认技能目录放对了位置、且目录里有 SKILL.md 入口文件；再确认你的 Agent 支持 Agent Skills 并已加载。提需求时把意图说明确（「帮我策划一个……」），路由决策树靠场景与复杂度判断，说法太含糊可能不会触发完整管线。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：它能直接把视频生成出来吗？&lt;/strong&gt;
不能，这是定位不是缺陷。它不做渲染/合成、不做生图/生视频，产出是策划案与模型调用指令；生成要接下游工具（Seedance、Kling、ComfyUI、HyperFrames、火山引擎等）。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;如果你的需求是「一句话直接出片」，用错了工具&amp;lt;/span&amp;gt;，应该看生成端技能那篇。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：Phase 7 确认时看不懂 HTML 分镜怎么办？&lt;/strong&gt;
HTML 分镜就是把分镜卡片排成网页版：每格的画面、描述、字幕、机位、VFX、审核状态都在上面。逐项核对的重点是三件事：镜头顺序对不对、人物/产品资产引用对不对、字幕文案有没有错别字。这一步是唯一最终确认关卡，确认即锁定，别赶时间。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：审核为什么最多 2 轮？想多改几轮不行吗？&lt;/strong&gt;
这是它的设计宪法之一：每阶段 Director 审核 ≤2 轮，逼着问题在早期收敛。如果 2 轮还过不了，通常不是细节没调好，而是方向本身有问题——回退到案例匹配或场景模板重选，比在原地磨第五轮有效。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：参考图对不上号、人物漂移怎么办？&lt;/strong&gt;
检查资产化是否落实：人物、产品、关键分镜、关键道具都应登记资产 ID，全链按 ID 引用。如果流程中出现用文字转述代替 ID 引用的环节，漂移基本就出在那里，回到那一步改掉。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：成本估算和实际生成费用对不上？&lt;/strong&gt;
Phase 7.5 的估算是按镜头数与规格做的预估，下游模型的价格、重试次数、分辨率档位都会影响实际账单。把它当预算量级参考，正式批量生成前先跑 1–2 个镜头核对单价，再回头修正估算。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：Fast-Track 出来的东西能转成 Default 继续吗？&lt;/strong&gt;
Fast-Track 是合并阶段的一稿，适合验证想法。想法验证通过后，建议按 Default 重新走一遍完整管线补齐审核与门禁，而不是在一稿上硬续——缺失的风格定样与资产门禁，后期补的代价更高。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;muse-video-skill 的价值不在「生成」，而在把专业剧组的前期流程——剧本、分镜、美术定样、资产管理、审核门禁、模型编译——压缩成一个 Agent 可执行的技能：六角色分工、38 个案例当风格锚点、8+1 阶段管线层层审核，最后由 Phase 7.5 把策划案编译成下游模型能直接执行的六段式 prompt、参考图映射与调用命令。它管想清楚，生成端管做出来，两段接起来，才是一条完整的 AI 视频生产线。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：Ollama 部署本地大模型</title><link>https://www.anexns.cloudns.org/posts/ai-ollama-local-llm/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-ollama-local-llm/</guid><description>用 Ollama 在自己的服务器或电脑上跑开源大模型：硬件门槛对照、官方脚本与 Docker 三种部署路线、OpenAI 兼容 API 调用、关键环境变量与性能调优，一篇配齐。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说结论：本地跑模型，门槛比你想象的低&lt;/h2&gt;
&lt;p&gt;一提到&quot;本地部署大模型&quot;，很多人脑子里浮现的是满机柜的 GPU 和看不懂的推理框架。其实这两年工具链已经把门槛压得很低了：Ollama 就是目前最省心的那个入口——一行命令装好，一行命令拉模型，一行命令开始对话，自带 HTTP API，还兼容 OpenAI 的接口格式，生态里的大多数客户端都能直接接。&lt;/p&gt;
&lt;p&gt;本地跑模型图什么？三件事：&lt;strong&gt;数据不出门&lt;/strong&gt;（文档、代码、聊天记录都在自己机器上推理）、&lt;strong&gt;没有按量账单&lt;/strong&gt;（电费之外零成本，半夜批量跑任务也不心疼）、&lt;strong&gt;离线可用&lt;/strong&gt;（断网照样工作）。代价也很明确：模型规模受自己硬件限制，答不出云端旗舰模型的效果。&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;搞清硬件门槛 → 三种路线选一条装好 → 拉模型对话 → 用 API 接进自己的工具链 → 把关键参数调明白&lt;/strong&gt;。模型本身怎么选、量化版本什么意思，可以先看系列上一篇&lt;a href=&quot;/posts/ai-open-models-guide/&quot;&gt;开源模型怎么选&lt;/a&gt;，本篇专注把 Ollama 这套运行时部署好、用顺。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/ollama/ollama&lt;/p&gt;
&lt;h2&gt;Ollama 是什么&lt;/h2&gt;
&lt;p&gt;Ollama 是一个本地大模型运行时，可以把它理解成&quot;模型界的 Docker&quot;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;模型管理像拉镜像&lt;/strong&gt;。&lt;code&gt;ollama pull 模型名&lt;/code&gt; 把模型权重、配置打包下载到本地仓库，&lt;code&gt;ollama list&lt;/code&gt; 查看，&lt;code&gt;ollama rm&lt;/code&gt; 删除，版本用标签区分（如 &lt;code&gt;qwen2.5:7b-instruct-q4_K_M&lt;/code&gt;）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;推理服务开箱即用&lt;/strong&gt;。启动后监听本机 11434 端口，既能在终端里直接对话，也提供 HTTP API 给其他程序调用。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;自动调度硬件&lt;/strong&gt;。有 NVIDIA GPU 就用 GPU 推理，没有就退回 CPU + 内存，还支持 Apple 芯片的 Metal 加速，不需要自己折腾 CUDA 环境。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;底层是 llama.cpp&lt;/strong&gt;。GGUF 格式的量化模型是它的主力，这也是它能在消费级硬件上跑起来的原因。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Ollama 的定位不是最强的推理引擎，而是最低门槛的那个：先让模型在你机器上跑起来，跑顺了再谈调优。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;硬件门槛：先对号入座&lt;/h2&gt;
&lt;p&gt;本地推理的瓶颈主要是&lt;strong&gt;显存（有 GPU 时）或内存（纯 CPU 时）&lt;/strong&gt;：模型权重必须完整装进显存/内存才跑得动，装不下就只能 CPU、内存、硬盘来回倒腾，速度惨不忍睹。下表是常见规模在 Q4 量化下的经验值：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;模型规模&lt;/th&gt;
&lt;th&gt;权重大小（Q4 量化）&lt;/th&gt;
&lt;th&gt;最低显存/内存&lt;/th&gt;
&lt;th&gt;舒适配置&lt;/th&gt;
&lt;th&gt;典型用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1.5B–3B&lt;/td&gt;
&lt;td&gt;1–2.5 GB&lt;/td&gt;
&lt;td&gt;4 GB&lt;/td&gt;
&lt;td&gt;6 GB&lt;/td&gt;
&lt;td&gt;简单分类、摘要、小设备尝鲜&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7B–8B&lt;/td&gt;
&lt;td&gt;4.5–5.5 GB&lt;/td&gt;
&lt;td&gt;8 GB&lt;/td&gt;
&lt;td&gt;10–12 GB&lt;/td&gt;
&lt;td&gt;日常对话、代码补全、文档问答&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;14B&lt;/td&gt;
&lt;td&gt;8.5–10 GB&lt;/td&gt;
&lt;td&gt;12 GB&lt;/td&gt;
&lt;td&gt;16 GB&lt;/td&gt;
&lt;td&gt;质量明显更好，推理与写作&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;32B&lt;/td&gt;
&lt;td&gt;19–21 GB&lt;/td&gt;
&lt;td&gt;24 GB&lt;/td&gt;
&lt;td&gt;32 GB&lt;/td&gt;
&lt;td&gt;接近中杯云端模型的体验&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;70B&lt;/td&gt;
&lt;td&gt;40–43 GB&lt;/td&gt;
&lt;td&gt;48 GB&lt;/td&gt;
&lt;td&gt;64 GB 以上&lt;/td&gt;
&lt;td&gt;多卡或大内存机器的领域&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;表里是&lt;strong&gt;只算权重&lt;/strong&gt;的数字。实际运行还要留上下文（KV Cache）的空间，长上下文会再吃掉几 GB，所以&quot;最低&quot;那一列是能启动、不是能舒服用。&lt;/li&gt;
&lt;li&gt;纯 CPU 也能跑 7B，只是生成速度大概每秒几个 token，只适合批处理、不适合聊天。内存带宽决定 CPU 推理速度，DDR5 双通道会比单通道快不少。&lt;/li&gt;
&lt;li&gt;没有独显的 VPS 也不是不能玩：2 核 4 GB 的小机器跑 3B 模型做摘要、分类完全够用。先按自己的硬件选规模，别硬上大模型。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;安装路线一：官方脚本（裸机 / VPS 首选）&lt;/h2&gt;
&lt;p&gt;在 Linux 服务器上，最稳妥的是官方安装脚本，它会装好二进制并注册 systemd 服务：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -fsSL https://ollama.com/install.sh | sh

# 验证安装
ollama --version
systemctl status ollama
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;装完服务默认就已启动并设为开机自启，监听 &lt;code&gt;127.0.0.1:11434&lt;/code&gt;。直接拉个模型就能用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ollama pull qwen2.5:7b
ollama run qwen2.5:7b
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;进入对话界面后输入问题即可，&lt;code&gt;/bye&lt;/code&gt; 退出。macOS 和 Windows 则去官网下载安装包，装完是带托盘图标的桌面程序，命令行用法完全一致。&lt;/p&gt;
&lt;h2&gt;安装路线二：Docker 部署&lt;/h2&gt;
&lt;p&gt;如果你习惯把所有服务都收进 Compose 管理（比如和&lt;a href=&quot;/posts/selfhost-open-webui/&quot;&gt;自建的 Open WebUI&lt;/a&gt; 放在同一台机器上），用官方镜像：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    ports:
      - &quot;127.0.0.1:11434:11434&quot;
    volumes:
      - ollama_data:/root/.ollama

volumes:
  ollama_data:
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker exec -it ollama ollama pull qwen2.5:7b
docker exec -it ollama ollama list
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;模型文件存在数据卷里，容器重建不会丢。注意端口我只绑了 &lt;code&gt;127.0.0.1&lt;/code&gt;——原因见后面的安全一节，这一条非常关键。&lt;/p&gt;
&lt;h2&gt;安装路线三：Docker ＋ GPU 直通&lt;/h2&gt;
&lt;p&gt;有 NVIDIA 显卡时，在上面的 Compose 基础上加 GPU 直通，推理速度直接上一个台阶：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    ports:
      - &quot;127.0.0.1:11434:11434&quot;
    volumes:
      - ollama_data:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  ollama_data:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;前提是宿主机装好了 NVIDIA 驱动和 NVIDIA Container Toolkit。GPU 直通本身的驱动、工具包安装细节，本系列不展开，站内已有一篇专门讲的：&lt;a href=&quot;/posts/docker-gpu-nvidia/&quot;&gt;Docker 调用 NVIDIA GPU&lt;/a&gt;，先把那篇配通再回来加这段配置。&lt;/p&gt;
&lt;p&gt;验证 GPU 是否真在干活：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 对话进行中另开一个终端执行
ollama ps
# PROCESSOR 一列显示 100% GPU 才算全程在显卡上跑；显示 CPU/GPU 混合说明显存不够、部分层被卸载到了内存
nvidia-smi
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;日常命令速查&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;ollama pull llama3.1:8b        # 拉模型（不带标签默认 latest）
ollama run llama3.1:8b         # 拉取并直接对话
ollama list                    # 本地已有模型
ollama ps                      # 正在内存/显存里运行的模型
ollama show qwen2.5:7b         # 看模型详情与参数
ollama stop qwen2.5:7b         # 立即卸载模型释放显存
ollama rm qwen2.5:7b           # 删除本地模型文件
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;一个容易忽略的点：模型在最后一次请求后默认还会&lt;strong&gt;在显存里保留 5 分钟&lt;/strong&gt;才卸载，方便连续对话。&lt;code&gt;ollama ps&lt;/code&gt; 里能看到到期时间，显存紧张时用 &lt;code&gt;ollama stop&lt;/code&gt; 手动释放，或者把环境变量 &lt;code&gt;OLLAMA_KEEP_ALIVE&lt;/code&gt; 调小。&lt;/p&gt;
&lt;h2&gt;API 调用：原生端点与 OpenAI 兼容端点&lt;/h2&gt;
&lt;p&gt;Ollama 真正的价值不在终端聊天，而在 API——接进脚本、接进自己的应用、接进各种现成客户端。它提供两套端点：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;端点&lt;/th&gt;
&lt;th&gt;风格&lt;/th&gt;
&lt;th&gt;典型路径&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;原生 API&lt;/td&gt;
&lt;td&gt;Ollama 自有格式&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/api/generate&lt;/code&gt;、&lt;code&gt;/api/chat&lt;/code&gt;、&lt;code&gt;/api/tags&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;自己写脚本、要用 Ollama 特有参数时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;OpenAI 兼容 API&lt;/td&gt;
&lt;td&gt;与 OpenAI 同格式&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/v1/chat/completions&lt;/code&gt;、&lt;code&gt;/v1/models&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;接现成的 OpenAI 生态客户端与 SDK&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;原生端点调用示例：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl http://localhost:11434/api/chat -d &apos;{
  &quot;model&quot;: &quot;qwen2.5:7b&quot;,
  &quot;messages&quot;: [
    {&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;用一句话解释什么是向量数据库&quot;}
  ],
  &quot;stream&quot;: false
}&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;不带 &lt;code&gt;stream: false&lt;/code&gt; 时默认是&lt;strong&gt;流式返回&lt;/strong&gt;——一行一个 JSON 分片往外吐，脚本里处理要注意；调试时先关掉流式，看完整响应更省事。&lt;/p&gt;
&lt;p&gt;OpenAI 兼容端点则让所有按 OpenAI 写的工具无痛接入，只需要改地址和模型名，API Key 随便填一个非空字符串：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl http://localhost:11434/v1/chat/completions -d &apos;{
  &quot;model&quot;: &quot;qwen2.5:7b&quot;,
  &quot;messages&quot;: [
    {&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;写一个 bash 一行命令，统计当前目录下所有 .log 文件的总行数&quot;}
  ]
}&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Python 里同样如此：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;from openai import OpenAI

client = OpenAI(
    base_url=&quot;http://localhost:11434/v1&quot;,
    api_key=&quot;ollama&quot;,  # Ollama 不校验 key，但 SDK 要求非空
)

resp = client.chat.completions.create(
    model=&quot;qwen2.5:7b&quot;,
    messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;你好，介绍一下你自己&quot;}],
)
print(resp.choices[0].message.content)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;记住一个原则：新项目优先接 /v1 兼容端点，生态工具全通用；只有需要 Ollama 特有能力时才用原生 API。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;关键环境变量&lt;/h2&gt;
&lt;p&gt;裸机安装时改 systemd 服务，Docker 安装时写进 &lt;code&gt;environment&lt;/code&gt;，常用的是这几个：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;变量&lt;/th&gt;
&lt;th&gt;默认值&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OLLAMA_HOST&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;127.0.0.1:11434&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;监听地址与端口，改成 &lt;code&gt;0.0.0.0:11434&lt;/code&gt; 才允许局域网/远程访问&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OLLAMA_MODELS&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;~/.ollama/models&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;模型存放目录，系统盘小的时候指到大盘上&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OLLAMA_NUM_PARALLEL&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;1（新版为 4 起步视版本）&lt;/td&gt;
&lt;td&gt;单模型并行处理请求数，提高并发但更吃显存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OLLAMA_MAX_LOADED_MODELS&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;按硬件推导&lt;/td&gt;
&lt;td&gt;同时驻留显存的模型个数，多模型切换场景才需要动&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OLLAMA_KEEP_ALIVE&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;5m&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;模型闲置多久后卸载，设 &lt;code&gt;0&lt;/code&gt; 为用完即走&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OLLAMA_CONTEXT_LENGTH&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;4096（视版本）&lt;/td&gt;
&lt;td&gt;默认上下文长度，长文档场景要调大，代价是更吃显存&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;裸机改配置的标准做法是给 systemd 服务加覆盖文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl edit ollama
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;在打开的编辑区里填：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Service]
Environment=&quot;OLLAMA_HOST=0.0.0.0:11434&quot;
Environment=&quot;OLLAMA_MODELS=/data/ollama/models&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;保存后重启生效：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl daemon-reload
sudo systemctl restart ollama
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Docker 路线则直接写进 Compose 的 &lt;code&gt;environment:&lt;/code&gt; 段，重建容器即可。&lt;/p&gt;
&lt;h2&gt;远程访问：先把安全说清楚&lt;/h2&gt;
&lt;p&gt;把 &lt;code&gt;OLLAMA_HOST&lt;/code&gt; 改成 &lt;code&gt;0.0.0.0&lt;/code&gt; 之后，&lt;strong&gt;任何能连到 11434 端口的人都能免费用你的算力&lt;/strong&gt;——Ollama 本身没有任何鉴权机制，API Key 参数只是摆设、不做校验。&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不要把 11434 端口直接暴露在公网上。&amp;lt;/span&amp;gt;网上长期有扫描器专门搜裸奔的 Ollama 实例，轻则被白嫖算力，重则被当成跳板和数据窃取通道。需要远程用时，只走这三种方式：SSH 隧道转发、内网组网、或者套一层带鉴权的反向代理，并且防火墙只放行可信来源。
:::&lt;/p&gt;
&lt;p&gt;本机或内网自用时，最省事的是 SSH 隧道：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 在自己电脑上执行，把服务器的 11434 映射到本机
ssh -L 11434:127.0.0.1:11434 user@your-server
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这样服务本身继续只监听服务器的 &lt;code&gt;127.0.0.1&lt;/code&gt;，你本机的程序访问 &lt;code&gt;localhost:11434&lt;/code&gt; 就等于访问服务器，既加密又不用改任何监听配置。&lt;/p&gt;
&lt;h2&gt;性能调优要点&lt;/h2&gt;
&lt;p&gt;模型跑起来之后慢，多半不是 Ollama 的问题，而是参数和硬件没对齐。按这个顺序排查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;先看卸载比例&lt;/strong&gt;。&lt;code&gt;ollama ps&lt;/code&gt; 的 PROCESSOR 列如果是 CPU/GPU 混合，说明显存装不下全部层，速度会被内存带宽拖住。要么换小一号的模型，要么换更低的量化，要么加显存，没有第四条路。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;量化版本别乱选&lt;/strong&gt;。同一模型的不同量化标签（如 &lt;code&gt;q8_0&lt;/code&gt;、&lt;code&gt;q4_K_M&lt;/code&gt;、&lt;code&gt;q3_K_M&lt;/code&gt;）是体积与质量的取舍：Q4_K_M 是多数官方标签的默认档，质量损失小、体积适中，是默认推荐；显存实在紧张再降到 Q3，低于 Q3 质量下降会变得明显。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;上下文长度按需给&lt;/strong&gt;。请求里可以通过 &lt;code&gt;options&lt;/code&gt; 传 &lt;code&gt;num_ctx&lt;/code&gt; 临时放大上下文：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;curl http://localhost:11434/api/chat -d &apos;{
  &quot;model&quot;: &quot;qwen2.5:7b&quot;,
  &quot;messages&quot;: [{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;总结这篇长文……&quot;}],
  &quot;stream&quot;: false,
  &quot;options&quot;: {&quot;num_ctx&quot;: 16384}
}&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;上下文翻倍，KV Cache 的显存占用也跟着翻倍。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要无脑把 num_ctx 拉到模型标称上限&amp;lt;/span&amp;gt;，先从 8192 起步，按实际文档长度给。&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;并发别贪多&lt;/strong&gt;。&lt;code&gt;OLLAMA_NUM_PARALLEL&lt;/code&gt; 调大能同时处理更多请求，但每个请求都要单独占一份 KV Cache，显存不够时反而互相挤兑、整体变慢。个人自用保持默认即可。&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：&lt;code&gt;ollama run&lt;/code&gt; 第一次特别慢，是不是装坏了？&lt;/strong&gt;
不是。首次运行要把权重从硬盘加载进显存/内存，7B 模型十几秒很正常。之后用 &lt;code&gt;ollama ps&lt;/code&gt; 能看到模型驻留中，连续对话就快了；隔了超过 5 分钟再问，又会重新加载一次。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：拉模型中途断网/报错，重跑会从头下载吗？&lt;/strong&gt;
不会。&lt;code&gt;ollama pull&lt;/code&gt; 支持断点续传，重新执行同一条命令会接着未完成的分片继续。但如果反复卡在同一个百分比，先检查磁盘空间——模型目录所在分区满了是最常见的原因。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：明明有独显，速度却和 CPU 差不多？&lt;/strong&gt;
按顺序查：&lt;code&gt;ollama ps&lt;/code&gt; 看 PROCESSOR 列是不是 100% GPU；&lt;code&gt;nvidia-smi&lt;/code&gt; 看推理时显存有没有涨；Docker 部署的检查 GPU 直通配置有没有生效（容器里执行 &lt;code&gt;nvidia-smi&lt;/code&gt; 能不能看到卡）。还有一种情况是模型太大被部分卸载，见调优第 1 条。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：局域网其他设备连不上 API？&lt;/strong&gt;
先确认 &lt;code&gt;OLLAMA_HOST&lt;/code&gt; 已改成 &lt;code&gt;0.0.0.0:11434&lt;/code&gt; 并重启了服务，再查服务器防火墙有没有放行 11434。Docker 部署的注意端口映射别再绑 &lt;code&gt;127.0.0.1&lt;/code&gt;。改完监听等于把服务开放给整个局域网，务必只在可信网络里这么做。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：磁盘被模型吃满了怎么办？&lt;/strong&gt;
&lt;code&gt;ollama list&lt;/code&gt; 看每个模型占多大，&lt;code&gt;ollama rm 模型名&lt;/code&gt; 删不用的。同一模型拉了多个量化标签是重灾区，留一个常用的就行。长期玩建议一开始就用 &lt;code&gt;OLLAMA_MODELS&lt;/code&gt; 把模型目录放到大盘上。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：API 返回里中文是乱码/被转义？&lt;/strong&gt;
那是 JSON 的 Unicode 转义，不是乱码，任何标准 JSON 解析库读出来都是正常中文。用 &lt;code&gt;curl&lt;/code&gt; 直接看原始输出时加 &lt;code&gt;-s&lt;/code&gt; 并把结果管道给 &lt;code&gt;jq&lt;/code&gt; 就能正常显示。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：想换个端口，11434 被占了？&lt;/strong&gt;
改 &lt;code&gt;OLLAMA_HOST&lt;/code&gt; 为 &lt;code&gt;127.0.0.1:新端口&lt;/code&gt; 即可，客户端调用时把地址里的端口同步改掉。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Ollama 是本地跑开源模型门槛最低的运行时：模型管理像拉镜像，自带 API 且兼容 OpenAI 格式。&lt;/li&gt;
&lt;li&gt;动手前先对硬件表：显存/内存决定你能跑多大的模型，Q4 量化下 8 GB 能舒服跑 7B–8B。&lt;/li&gt;
&lt;li&gt;部署三条路线：裸机用官方脚本＋systemd，容器化用官方镜像，有 N 卡再加 GPU 直通。&lt;/li&gt;
&lt;li&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;11434 端口没有任何鉴权，永远不要裸奔公网&amp;lt;/span&amp;gt;，远程访问走 SSH 隧道或带鉴权的反代。&lt;/li&gt;
&lt;li&gt;调优先看 &lt;code&gt;ollama ps&lt;/code&gt; 的卸载比例，再谈量化与 &lt;code&gt;num_ctx&lt;/code&gt;，顺序别反。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;下一篇我们聊怎么给 Ollama 套一个像样的聊天界面——不用敲命令、能管会话、能传文档的那种。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：开源模型怎么选</title><link>https://www.anexns.cloudns.org/posts/ai-open-models-guide/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-open-models-guide/</guid><description>选本地开源模型不靠玄学：看懂模型名里的参数与后缀、搞懂量化格式的体积与质量账、用公式算清显存和 KV Cache，再按中文对话、代码、长文档、多模态对号入座。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说结论：选模型是一道算术题&lt;/h2&gt;
&lt;p&gt;上一篇我们用 &lt;a href=&quot;/posts/ai-ollama-local-llm/&quot;&gt;Ollama 把本地大模型跑了起来&lt;/a&gt;，&lt;code&gt;ollama run&lt;/code&gt; 一行命令很爽，但爽完之后问题立刻就来：模型库里几百个名字长得差不多的模型，到底下哪个？&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;同一个模型有十几个版本：7B、8B、14B、32B，Q4、Q5、Q8、FP16，Instruct、Coder、VL……下错一个，要么显存爆了跑不起来，要么跑起来了质量一言难尽。&lt;/li&gt;
&lt;li&gt;网上的推荐帖大多只说&quot;某某模型很强&quot;，很少有人告诉你它在你这张显卡上到底能不能跑、能跑多快、要留多少余量。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这篇就把选型拆成四步可计算的动作：&lt;strong&gt;看懂名字 → 搞懂量化 → 算显存账 → 按用途对号入座&lt;/strong&gt;。走完这四步，你在 Ollama 和 Hugging Face 上筛模型时，心里应该有一把尺子。&lt;/p&gt;
&lt;p&gt;先把最重要的结论放前面：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;本地部署选模型的顺序是先算显存、再看量化、最后才比&quot;谁更强&quot;——跑不起来的模型，再强也和你无关。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;第一步：看懂模型名&lt;/h2&gt;
&lt;p&gt;开源模型的名字不是随便起的，基本是一串结构化信息。以几个真实风格的名字为例：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Qwen3-32B-Instruct-2507
Llama-3.1-8B-Instruct
DeepSeek-R1-Distill-Qwen-32B
Qwen3-30B-A3B
Mistral-Small-3.1-24B-Instruct-2503
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐段拆解：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;组成部分&lt;/th&gt;
&lt;th&gt;例子&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;系列名&lt;/td&gt;
&lt;td&gt;Qwen、Llama、DeepSeek、Mistral、Gemma、Phi&lt;/td&gt;
&lt;td&gt;出品方与模型家族，决定&quot;血统&quot;和中文/代码等基础倾向&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;版本号&lt;/td&gt;
&lt;td&gt;3、3.1、2.5&lt;/td&gt;
&lt;td&gt;同一系列的迭代代次，一般越新越好&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;参数规模&lt;/td&gt;
&lt;td&gt;8B、32B&lt;/td&gt;
&lt;td&gt;B 是 Billion（十亿），参数总量，直接决定体积和显存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;角色后缀&lt;/td&gt;
&lt;td&gt;Instruct、Chat&lt;/td&gt;
&lt;td&gt;经过指令微调，能正常对话；没有这个后缀的是 Base 基座模型&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;能力后缀&lt;/td&gt;
&lt;td&gt;Coder、VL、Math&lt;/td&gt;
&lt;td&gt;专项强化：Coder 写代码，VL 带视觉（看图），Math 偏数学&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;特殊标记&lt;/td&gt;
&lt;td&gt;Distill、A3B&lt;/td&gt;
&lt;td&gt;Distill 是蒸馏版；A3B 是 MoE 的激活参数量（见下）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;日期后缀&lt;/td&gt;
&lt;td&gt;2507、2503&lt;/td&gt;
&lt;td&gt;2025 年 7 月、2025 年 3 月发布的版本快照&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这里有三个最容易踩的点：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一，Base 和 Instruct 是两个物种。&lt;/strong&gt; Base 模型只会&quot;续写文本&quot;，你问它问题，它可能接着你的问题再编几个问题出来。日常对话、编程助手要的一律是带 Instruct 或 Chat 后缀的版本。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;下错 Base 模型是新手&quot;模型怎么傻乎乎的&quot;第一大原因&amp;lt;/span&amp;gt;，不是模型不行，是你拿错了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二，参数规模决定下限。&lt;/strong&gt; 同一系列里，参数越大通常越聪明，但边际收益递减且成本陡增。粗略的体感分档：3B 以下适合简单分类、摘要类任务；7B～9B 是本地日常对话的起步线；14B～32B 质量明显上一个台阶，是当前本地部署的主力区间；70B 级别接近第一梯队闭源模型的体验，但硬件门槛陡峭。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三，MoE 和稠密（Dense）要分清。&lt;/strong&gt; 稠密模型推理时全部参数参与计算；MoE（混合专家）模型只激活一部分专家。名字里带 &lt;code&gt;A数字B&lt;/code&gt; 的就是 MoE：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;Qwen3-30B-A3B&lt;/code&gt;：总参数 30B，每次推理只激活约 3B。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;Mixtral-8x7B&lt;/code&gt;：总参数约 46.7B，激活约 12.9B。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;DeepSeek-V3&lt;/code&gt;：总参数 671B，激活约 37B。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;MoE 的账要分开算：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;生成速度看激活参数量，占多少显存看总参数量。&amp;lt;/span&amp;gt;30B-A3B 跑起来有 3B 级别的速度，但 30B 的权重一个字节都不少地要装进显存或内存。很多人冲着&quot;3B 的速度&quot;去下 30B-A3B，然后在 16GB 显卡上当场爆显存，就是栽在这个误会里。&lt;/p&gt;
&lt;h2&gt;第二步：量化是怎么回事&lt;/h2&gt;
&lt;p&gt;模型权重原本是 FP16（半精度浮点）存储的，每个参数占 2 字节。32B 模型光权重就是约 64GB——没几张消费级显卡装得下。量化就是把每个参数用更少的比特表示，把体积压下来，代价是损失一点点精度。&lt;/p&gt;
&lt;p&gt;本地部署最常见的量化格式来自 GGUF 生态（Ollama、llama.cpp 都用它），命名里的 &lt;code&gt;K&lt;/code&gt; 指 K-quants 分块量化，&lt;code&gt;M&lt;/code&gt; 指该档位的中等规模变体。速查表如下（体积以每个参数的平均字节数估算，含少量元数据开销）：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;量化格式&lt;/th&gt;
&lt;th&gt;每参数约占&lt;/th&gt;
&lt;th&gt;相对 FP16 体积&lt;/th&gt;
&lt;th&gt;质量损失&lt;/th&gt;
&lt;th&gt;定位&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;FP16 / BF16&lt;/td&gt;
&lt;td&gt;2.0 字节&lt;/td&gt;
&lt;td&gt;100%&lt;/td&gt;
&lt;td&gt;无（基准）&lt;/td&gt;
&lt;td&gt;显存管够时的原汁原味&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Q8_0&lt;/td&gt;
&lt;td&gt;约 1.03 字节&lt;/td&gt;
&lt;td&gt;约 52%&lt;/td&gt;
&lt;td&gt;几乎无感&lt;/td&gt;
&lt;td&gt;显存富裕时的首选&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Q6_K&lt;/td&gt;
&lt;td&gt;约 0.8 字节&lt;/td&gt;
&lt;td&gt;约 41%&lt;/td&gt;
&lt;td&gt;极小&lt;/td&gt;
&lt;td&gt;高质量与体积的平衡点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Q5_K_M&lt;/td&gt;
&lt;td&gt;约 0.68 字节&lt;/td&gt;
&lt;td&gt;约 35%&lt;/td&gt;
&lt;td&gt;小&lt;/td&gt;
&lt;td&gt;质量敏感任务可用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Q4_K_M&lt;/td&gt;
&lt;td&gt;约 0.58 字节&lt;/td&gt;
&lt;td&gt;约 30%&lt;/td&gt;
&lt;td&gt;可感知但可接受&lt;/td&gt;
&lt;td&gt;本地部署甜点位&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Q4_0&lt;/td&gt;
&lt;td&gt;约 0.55 字节&lt;/td&gt;
&lt;td&gt;约 28%&lt;/td&gt;
&lt;td&gt;略大于 Q4_K_M&lt;/td&gt;
&lt;td&gt;老格式，速度略快&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Q3_K_M&lt;/td&gt;
&lt;td&gt;约 0.42 字节&lt;/td&gt;
&lt;td&gt;约 21%&lt;/td&gt;
&lt;td&gt;明显&lt;/td&gt;
&lt;td&gt;只为塞进小显存时考虑&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Q2_K&lt;/td&gt;
&lt;td&gt;约 0.33 字节&lt;/td&gt;
&lt;td&gt;约 17%&lt;/td&gt;
&lt;td&gt;大&lt;/td&gt;
&lt;td&gt;极限场景，不推荐日常用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;IQ 系列&lt;/td&gt;
&lt;td&gt;与同档 Q 相当&lt;/td&gt;
&lt;td&gt;相当&lt;/td&gt;
&lt;td&gt;同体积下略优于普通 Q&lt;/td&gt;
&lt;td&gt;配合 imatrix 校准的低比特方案&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个使用口径：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Q4_K_M 是社区公认的甜点位。&lt;/strong&gt; 体积只有 FP16 的三成左右，主流任务的质量损失大多数人感知不到，速度还因为数据量小而更快。本篇后面的显存速查表都以它为基准列。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;量化损失不是均匀的。&lt;/strong&gt; 写代码、做数学、长链推理这类对精度敏感的任务，低比特量化的掉点比闲聊明显得多；如果模型是拿来写代码的，预算允许时优先 Q5_K_M 或 Q6_K。&lt;/li&gt;
&lt;li&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Q3 以下（含 Q2）不要拿来当主力。&amp;lt;/span&amp;gt;省下的那点显存，换来的是逻辑开始飘、格式开始乱、重复率上升，省下的显存还不够你多开一会儿上下文的，买卖不划算。&lt;/li&gt;
&lt;li&gt;同一量化档位下，文件实际大小会因模型结构（词表大小、是否带视觉编码器等）浮动 5%～10%，下载前以仓库文件列表里标注的实际大小为准。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;第三步：算显存账——权重只是第一笔&lt;/h2&gt;
&lt;p&gt;新手算显存最常见的错误，是只算权重文件大小。一张显卡要装下的东西有三笔：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;总需求 ≈ 权重大小 + KV Cache + 运行时开销
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第一笔：权重。&lt;/strong&gt; 公式很简单：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;权重大小(GB) ≈ 参数量(B) × 每参数字节数
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;比如 14B 模型用 Q4_K_M：14 × 0.58 ≈ 8.1GB（实际文件约 9GB，多出的是词表与元数据，正常）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二笔：KV Cache。&lt;/strong&gt; 这是注意力机制用来缓存历史 Token 的键值对，&lt;strong&gt;随上下文长度线性增长&lt;/strong&gt;，而且经常是新手爆显存的真正元凶。它的大小由模型结构决定：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;每 Token 的 KV(字节) = 层数 × KV 头数 × 每头维度 × 2(K 和 V) × 每元素字节数
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;以 Llama 3.1 8B 为例：32 层、8 个 KV 头（GQA 分组注意力已经帮我们省了很多）、每头维度 128、FP16 存储：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;每 Token KV = 32 × 8 × 128 × 2 × 2 = 131072 字节 ≈ 0.125MB
开满 32K 上下文 = 0.125MB × 32768 ≈ 4GB
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;也就是说，这个 8B 模型光 KV Cache 就能吃掉 4GB。好在现在主流推理框架都支持 KV Cache 量化（Ollama 可通过 &lt;code&gt;OLLAMA_KV_CACHE_TYPE=q8_0&lt;/code&gt; 开启），Q8 量化后这笔账直接减半，质量影响很小。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三笔：运行时开销。&lt;/strong&gt; 计算图、激活值、框架自身占用，一般按 0.5～1.5GB 预留；多模态模型还要再算上视觉编码器。&lt;/p&gt;
&lt;p&gt;把所有账汇总成速查表（权重为 GGUF 实际文件的常见大小，KV 按 FP16、32K 上下文估算，运行时开销按约 1GB 计）：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数规模&lt;/th&gt;
&lt;th&gt;FP16 权重&lt;/th&gt;
&lt;th&gt;Q8_0 权重&lt;/th&gt;
&lt;th&gt;Q4_K_M 权重&lt;/th&gt;
&lt;th&gt;KV Cache(32K)&lt;/th&gt;
&lt;th&gt;Q4_K_M 总需求约&lt;/th&gt;
&lt;th&gt;能舒适装下的配置&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;7B / 8B&lt;/td&gt;
&lt;td&gt;约 16GB&lt;/td&gt;
&lt;td&gt;约 8.5GB&lt;/td&gt;
&lt;td&gt;约 4.9GB&lt;/td&gt;
&lt;td&gt;约 2～4GB&lt;/td&gt;
&lt;td&gt;约 9GB&lt;/td&gt;
&lt;td&gt;12GB 显卡&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;14B&lt;/td&gt;
&lt;td&gt;约 29GB&lt;/td&gt;
&lt;td&gt;约 15.7GB&lt;/td&gt;
&lt;td&gt;约 9GB&lt;/td&gt;
&lt;td&gt;约 3～5GB&lt;/td&gt;
&lt;td&gt;约 14GB&lt;/td&gt;
&lt;td&gt;16GB 显卡&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;32B&lt;/td&gt;
&lt;td&gt;约 65GB&lt;/td&gt;
&lt;td&gt;约 34.8GB&lt;/td&gt;
&lt;td&gt;约 19.8GB&lt;/td&gt;
&lt;td&gt;约 4～8GB&lt;/td&gt;
&lt;td&gt;约 26GB&lt;/td&gt;
&lt;td&gt;32GB 显卡或双卡&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;70B&lt;/td&gt;
&lt;td&gt;约 141GB&lt;/td&gt;
&lt;td&gt;约 75GB&lt;/td&gt;
&lt;td&gt;约 40.5GB&lt;/td&gt;
&lt;td&gt;约 5～10GB&lt;/td&gt;
&lt;td&gt;约 48GB&lt;/td&gt;
&lt;td&gt;64GB 内存混跑或多卡&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;表里有几个口径要说清：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;KV Cache 一列随模型结构浮动很大：层数多、KV 头多的模型更吃 KV；开的上下文不是 32K 而是 8K 时，这笔账按比例除以 4。&lt;/li&gt;
&lt;li&gt;&quot;总需求&quot;超过显存不等于完全跑不了——Ollama 会把放不下的层卸载（Offload）到内存用 CPU 算，但速度会断崖式下跌。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;选型的标准应该是&quot;全量装进显存&quot;，而不是&quot;能启动&quot;&amp;lt;/span&amp;gt;，能启动但每秒吐三个字，那不叫能用。&lt;/li&gt;
&lt;li&gt;没有独立显卡、纯靠内存跑（比如大内存的 Mac 或核显机器）同理，把表里的&quot;显存&quot;换成&quot;可用内存&quot;即可，只是速度预期要放低。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
算账时最容易漏的就是 KV Cache：很多人照着权重大小买了张&quot;刚好&quot;的显卡，结果上下文一拉长就 OOM（显存溢出）。留白原则：总需求控制在显存的 85% 以内，剩下的留给上下文波动和系统占用。
:::&lt;/p&gt;
&lt;h2&gt;第四步：按用途对号入座&lt;/h2&gt;
&lt;p&gt;算力账算清之后，才轮到&quot;哪个系列强&quot;。下面按用途给定位，不纠结某个具体小版本（版本迭代太快），记系列名和定位就够用很久：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;th&gt;首选系列&lt;/th&gt;
&lt;th&gt;定位与特点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;中文对话、中文写作&lt;/td&gt;
&lt;td&gt;Qwen（通义千问）&lt;/td&gt;
&lt;td&gt;国产系列里中文语料与中文指令跟随最扎实，尺寸梯度最全，从 0.6B 到 200B+ 都有&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;中文对话备选&lt;/td&gt;
&lt;td&gt;GLM（智谱）、DeepSeek&lt;/td&gt;
&lt;td&gt;GLM 中文与工具调用不错；DeepSeek 的对话版中文也在一线&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;写代码&lt;/td&gt;
&lt;td&gt;Qwen Coder、DeepSeek&lt;/td&gt;
&lt;td&gt;Coder 专项系列在补全、改 Bug、读仓库上明显强于同尺寸通用模型&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数学与深度推理&lt;/td&gt;
&lt;td&gt;DeepSeek R1 及其蒸馏版&lt;/td&gt;
&lt;td&gt;会输出长思维链，慢但能啃硬题；蒸馏版把能力压进小尺寸，本地可跑&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;长文档处理&lt;/td&gt;
&lt;td&gt;Llama、Qwen、Mistral&lt;/td&gt;
&lt;td&gt;三家都有长上下文版本；选型时重点看下一节说的&quot;实际可用长度&quot;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;看图多模态&lt;/td&gt;
&lt;td&gt;Qwen VL、MiniCPM-V、InternVL&lt;/td&gt;
&lt;td&gt;名字带 VL/Vision 的才是多模态版；MiniCPM-V 在小尺寸下性价比突出&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;英文与通用&lt;/td&gt;
&lt;td&gt;Llama（Meta）、Mistral、Gemma（Google）&lt;/td&gt;
&lt;td&gt;生态最大、微调与量化资源最丰富；纯英文场景体验好&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;极小尺寸/端侧&lt;/td&gt;
&lt;td&gt;Phi（微软）、Gemma 小尺寸版、Qwen 小尺寸版&lt;/td&gt;
&lt;td&gt;3B 上下干分类、摘要、格式化这类轻活，速度飞快&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;落到具体搭配上，给三套可以直接抄的组合：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;16GB 显卡的均衡组合&lt;/strong&gt;：主力 Qwen 14B 级 Instruct（Q4_K_M，约 9GB），再备一个同系列 Coder 版处理代码，显存还够两个模型热切换。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;24GB 显卡的进阶组合&lt;/strong&gt;：32B 级 Instruct（Q4_K_M，约 19.8GB）当主力，上下文开 16K～32K 都稳；这是目前本地体验的&quot;甜点机&quot;配置。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;纯 CPU/大内存机器&lt;/strong&gt;：优先考虑 MoE，比如 30B-A3B 这类总参不大、激活小的模型，Q4_K_M 装内存里跑，速度比同体积稠密模型友好得多。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;选好主力模型只是开始：把它接进编程工具里当私有助手，看 &lt;a href=&quot;/posts/ai-continue-local-coding/&quot;&gt;Continue ＋ 本地模型搭私有编程助手&lt;/a&gt;；想让多个应用共用同一个模型入口，看 &lt;a href=&quot;/posts/ai-litellm-gateway/&quot;&gt;LiteLLM 网关篇&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;第五步：上下文长度的真相&lt;/h2&gt;
&lt;p&gt;模型介绍页上动辄写着 128K、256K、1M 上下文。先说清这个数字的含义：它只是&quot;位置编码能编到的最大长度&quot;，约等于&lt;strong&gt;能塞进去&lt;/strong&gt;，不等于&lt;strong&gt;塞满了还能用好&lt;/strong&gt;。实际使用中有三笔折损：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;注意力衰减与&quot;迷失中间&quot;。&lt;/strong&gt; 学术界著名的 Lost in the Middle 现象：长上下文里，模型对开头和结尾的内容记得牢，对中段内容的利用率明显下降。塞满 128K 时，中间那几万 Token 的关键信息可能被&quot;读过但没读进去&quot;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;KV Cache 跟着爆。&lt;/strong&gt; 上一节算过，32K 上下文就是几个 GB；真开到 128K，KV Cache 能再吃掉十几 GB，显存不够直接 OOM，或者被迫卸载到 CPU 慢如蜗牛。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;速度变慢。&lt;/strong&gt; 每次生成都要回看全部历史，上下文越长，每 Token 的计算量越大，长会话后半段肉眼可见地变卡。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;经验口径：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;日常实际可用长度按标称的四分之一到二分之一估算比较稳妥。&amp;lt;/span&amp;gt;标称 128K 的模型，当 32K～64K 来用，体验和稳定性都在线；真有超长文档需求，优先考虑分块摘要、RAG 检索这类工程手段，而不是无脑堆上下文。另外推理型模型（R1 那类）自己输出的思维链也占上下文，留预算时要把这部分算进去。&lt;/p&gt;
&lt;h2&gt;第六步：实操——在 Ollama 和 Hugging Face 上筛模型&lt;/h2&gt;
&lt;p&gt;把前面的尺子落成具体动作。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;在 &lt;a href=&quot;https://github.com/ollama/ollama&quot;&gt;Ollama&lt;/a&gt; 里筛：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 看模型详情：参数量、量化、上下文都在里面
ollama show qwen3:14b

# 看当前实际占用：谁在显存里、占了多少
ollama ps

# 拉取指定量化版本：tag 里直接带量化名
ollama pull qwen3:14b-instruct-q4_K_M
ollama pull qwen3:32b-instruct-q8_0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;要点：Ollama 的默认 tag 往往已经是某个量化版本（常见是 Q4_K_M），&lt;code&gt;ollama show&lt;/code&gt; 里会写明，别默认下到的就是原版 FP16。跑起来后用 &lt;code&gt;ollama ps&lt;/code&gt; 确认 PROCESSOR 一列是 100% GPU——如果显示 CPU/GPU 混合，就是显存不够在卸载，回去换小一号的量化或尺寸。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;在 Hugging Face 里筛（找 GGUF 文件时）：&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;搜索时勾选 GGUF 格式筛选，或直接找带 &lt;code&gt;-GGUF&lt;/code&gt; 后缀的仓库；社区里 bartowski、unsloth、mradermacher 等发布者的量化包质量稳定、文件命名规范。&lt;/li&gt;
&lt;li&gt;进仓库看 Files 列表：每个量化档位的文件大小都标好了，和本篇速查表对照，选&quot;权重＋KV＋开销 ≤ 显存 85%&quot;的那一档。&lt;/li&gt;
&lt;li&gt;同一仓库里优先选带 &lt;code&gt;imatix&lt;/code&gt;（imatrix 校准）标记的低比特版本，同体积下质量更好。&lt;/li&gt;
&lt;li&gt;注意仓库是否包含多模态投影文件（mmproj）：VL 模型少了它就看不了图，Ollama 导入时也要一起带上。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;一个现成的估算示例&lt;/strong&gt;，可以直接套自己的机器：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;我的显卡：16GB
目标模型：14B Instruct，Q4_K_M  → 权重约 9GB
计划上下文：16K                 → KV Cache 约 2GB（FP16）
运行时开销：约 1GB
合计：约 12GB ≤ 16 × 0.85 = 13.6GB  ✅ 能全量进显存
若换 Q8_0：权重约 15.7GB，仅权重就超预算 ❌ 放弃
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：模型能跑，但慢得像打字机。&lt;/strong&gt;
先 &lt;code&gt;ollama ps&lt;/code&gt; 看 PROCESSOR 列。出现 CPU 参与就是显存不够发生了卸载，对策按顺序：换低一档量化 → 缩小 &lt;code&gt;num_ctx&lt;/code&gt; → 开 KV Cache 量化 → 还不行就换小一号尺寸。另外别把 MoE 和稠密搞混：拿激活参数估速度、拿总参数估显存，两个数别用反。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：回答到一半质量骤降、开始胡言乱语或重复。&lt;/strong&gt;
大概率是上下文超限被截断，或者量化档位太低（Q3 以下）在长输出时崩坏。先把上下文长度调小验证，再考虑升一档量化。推理型模型还要检查是不是思维链太长把上下文吃满了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：问它问题，它不回答，只会顺着我的话往下编。&lt;/strong&gt;
你下到 Base 基座模型了。换成同系列带 Instruct / Chat 后缀的版本，这是选型第一课，十有八九的新手&quot;模型很傻&quot;都是这个问题。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：中文回答里总夹英文，或者英文提示词才听话。&lt;/strong&gt;
模型系列的语料倾向问题。中文场景优先 Qwen、GLM、DeepSeek 这类中文一线系列；同系列内选 Instruct 版而不是只针对英文优化的衍生版。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：文件明明只有 9GB，为什么 12GB 显卡还是爆显存？&lt;/strong&gt;
你只算了权重。加上 KV Cache（上下文越长越大）和运行时开销就超了。按第三节的公式重算，或者直接开 &lt;code&gt;OLLAMA_KV_CACHE_TYPE=q8_0&lt;/code&gt; 把 KV 那笔账砍半。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：同一个模型，Ollama 上的和 Hugging Face 上的大小对不上。&lt;/strong&gt;
正常。Ollama 库里的版本有它自己的量化选择和模板封装，和社区 GGUF 包不一定是同一档量化。对照 &lt;code&gt;ollama show&lt;/code&gt; 里写的 Quantization 字段判断，别只看名字猜。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;选本地开源模型，把这条链路走顺就不会错：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;看懂名字&lt;/strong&gt;：系列定倾向，B 数定体积，Instruct 才是对话版，MoE 分开算速度与显存。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;量化选甜点&lt;/strong&gt;：Q4_K_M 是默认答案，质量敏感升 Q5/Q6，Q3 以下不碰主力。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;显存算全账&lt;/strong&gt;：权重 + KV Cache + 开销 ≤ 显存的 85%，标准是全量进显存而不是能启动。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;用途对号入座&lt;/strong&gt;：中文找 Qwen，代码找 Coder，推理找 R1 系，看图找 VL。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;上下文打折看&lt;/strong&gt;：标称长度按四分之一到二分之一当实际可用，长文档靠工程手段解决。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;模型选定之后，回到 &lt;a href=&quot;/posts/ai-ollama-local-llm/&quot;&gt;Ollama 部署篇&lt;/a&gt; 把它跑起来，就是你自己的本地 AI 班底了。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：提示词工程实战</title><link>https://www.anexns.cloudns.org/posts/ai-prompt-engineering/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-prompt-engineering/</guid><description>提示词不是玄学：从六要素万能骨架、五个立竿见影的技巧，到总结、翻译、改代码、写测试、数据提取的可抄模板库，再到 bad case 迭代法，把和大模型对话变成可复现的工程方法。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;同一个模型，为什么别人用得比你好&lt;/h2&gt;
&lt;p&gt;很多人第一次认真用大模型，体验是这样的：问它写周报，它回一篇正确的废话；让它改代码，它把能跑的代码改出三个新 Bug；让它提取表格数据，它每次给的格式都不一样。于是得出结论：这东西不过如此。&lt;/p&gt;
&lt;p&gt;但换个人来问，同一个模型，输出却条理清楚、格式整齐、一次到位。差别不在模型，在提示词。&lt;/p&gt;
&lt;p&gt;这一篇是本系列的「内功篇」。前面几篇讲工具和部署——&lt;a href=&quot;/posts/ai-tools-overview/&quot;&gt;AI 工具全景图与选型指南&lt;/a&gt;帮你选对工具，这一篇讲怎么把工具用对。主线很简单：先理解提示词为什么有效，再掌握一个万能骨架和五个立竿见影的技巧，然后直接抄按场景准备的模板库，最后学会用 bad case 迭代法把提示词越调越稳。学完之后，你和模型的对话方式会从「碰运气聊天」变成「可复现的工程」。&lt;/p&gt;
&lt;h2&gt;提示词为什么有效：模型是续写机器&lt;/h2&gt;
&lt;p&gt;要写好提示词，先要放下两个误解。&lt;/p&gt;
&lt;p&gt;第一个误解：把模型当搜索引擎。你给它一个关键词，它「查」出一个答案。实际上大语言模型（LLM）做的事只有一件：&lt;strong&gt;根据前面的文字，预测后面最可能出现的文字&lt;/strong&gt;。它不是在查库，是在续写。你给的提示词，就是这篇「文章」的开头；它后面的全部输出，都是在努力让这篇文章读起来连贯、合理、像那么回事。&lt;/p&gt;
&lt;p&gt;这解释了很多现象：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;你写「写得好一点」，它不知道什么叫好，只能按训练数据里最常见的「好文章」样子去续，于是给你一篇正确的废话。&lt;/li&gt;
&lt;li&gt;你在提示词里先写了一段高质量的文字，它会不自觉地模仿这个水准往下写——因为「保持风格一致」正是续写最核心的本能。&lt;/li&gt;
&lt;li&gt;你自相矛盾，它只能随机挑一条执行，因为文章没法同时往两个方向续。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;第二个误解：把提示词当许愿。实际上更准确的比喻是：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;上下文即程序，提示词就是你写给模型的源代码&amp;lt;/span&amp;gt;。每一个字都在改变输出的概率分布：角色设定决定了语气和知识边界，示例决定了格式和风格，约束决定了哪些输出被提前排除。写提示词和写代码一样，有结构、有调试、有版本管理——这正是它叫「提示词工程」而不是「提示词玄学」的原因。&lt;/p&gt;
&lt;p&gt;理解了这一层，下面的骨架和技巧就都不是死记硬背的口诀，而是顺理成章的推论：既然模型在续写，你要做的就是把「开头」写得足够明确，让唯一合理的续写方向，就是你想要的那个结果。&lt;/p&gt;
&lt;p&gt;:::warning
在开始之前先立一条安全规矩：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把 API 密钥、账号密码、未脱敏的用户数据贴进提示词&amp;lt;/span&amp;gt;，尤其是发给云端模型的对话。这些内容会离开你的机器，是否被记录、保留多久，不由你控制。需要处理敏感材料时，要么先脱敏，要么改用本地部署的模型。
:::&lt;/p&gt;
&lt;h2&gt;万能骨架：六要素&lt;/h2&gt;
&lt;p&gt;不管什么任务，一条结构完整的提示词都由六个要素组成。缺哪个，模型就在哪个维度上自由发挥——而自由发挥的方向，通常不是你想要的。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;要素&lt;/th&gt;
&lt;th&gt;回答的问题&lt;/th&gt;
&lt;th&gt;缺失时的典型症状&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;角色&lt;/td&gt;
&lt;td&gt;你是谁、按什么水准说话&lt;/td&gt;
&lt;td&gt;语气飘忽，时而科普时而论文&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;任务&lt;/td&gt;
&lt;td&gt;具体要做什么动作&lt;/td&gt;
&lt;td&gt;答非所问，或者只做了一半&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;背景&lt;/td&gt;
&lt;td&gt;材料从哪来、用在什么场合&lt;/td&gt;
&lt;td&gt;不懂轻重，抓不住重点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;约束&lt;/td&gt;
&lt;td&gt;边界在哪、不要做什么&lt;/td&gt;
&lt;td&gt;超长、跑题、编造细节&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;格式&lt;/td&gt;
&lt;td&gt;输出长什么样&lt;/td&gt;
&lt;td&gt;每次格式都不同，没法直接用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;示例&lt;/td&gt;
&lt;td&gt;照着这个样子来&lt;/td&gt;
&lt;td&gt;风格和粒度全靠猜&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;下面用一个完整案例看六要素怎么把一条烂提示词改好。任务：把一段产品更新日志，改写成发给用户的更新公告。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;反例：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;帮我把这段更新日志改得通俗一点：
v2.4.1 修复若干问题，优化启动性能，新增导出模块的重试机制，调整缓存策略。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这条提示词只有「任务」半个要素。模型不知道写给谁、多长、什么语气，只能按平均水准续写，结果大概率是一篇四平八稳、谁看都行、谁看都没感觉的公告。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;改法：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 角色
你是一名 SaaS 产品的用户运营文案，擅长把技术变更翻译成用户能感知的收益。

# 任务
把下面的版本更新日志，改写成一则面向普通用户的 App 内更新公告。

# 背景
我们的用户是中小企业的行政和财务人员，不懂技术术语。公告会推送到 App 首页，
用户平均只会看 5 秒，所以第一句必须是最重要的变化。

# 约束
- 总字数不超过 120 字
- 不出现「缓存」「重试机制」这类技术词，换成用户能感知的说法
- 只写日志里有的变化，不许自行补充新功能

# 格式
第一行是标题（10 字以内），空一行后是正文，正文用短句，一句一行。

# 示例
标题：导出报表更快了
正文：
导出的文件如果中途失败，现在会自动接着传，不用重新等。
App 打开速度提升了，点开就能用。

# 待改写日志
v2.4.1 修复若干问题，优化启动性能，新增导出模块的重试机制，调整缓存策略。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐条对照：角色锁定了语气（运营文案，不是工程师）；背景告诉它读者是谁、阅读场景是 5 秒扫一眼，于是它会把最重要的变化放第一句；约束堵死了三个最常见的翻车点——超长、用术语、编造；格式让它输出即成品，不用你再排版；示例则给了它一个可模仿的标杆，「自动接着传」这种说法就是从示例的风格里续出来的。&lt;/p&gt;
&lt;p&gt;不需要每次都写满六段。任务越重要、越要复用，越值得写全；一次性小问题，两三个要素也够。判断标准是：&lt;strong&gt;输出不满意时，先看看缺的是哪个要素，补上它，而不是把整条提示词推倒重写&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;五个立竿见影的技巧&lt;/h2&gt;
&lt;p&gt;骨架解决「全不全」，下面五个技巧解决「灵不灵」。每一个都配反例和改法，看完马上能用。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;技巧&lt;/th&gt;
&lt;th&gt;解决的问题&lt;/th&gt;
&lt;th&gt;一句话写法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;给示例（Few-shot）&lt;/td&gt;
&lt;td&gt;格式、风格、粒度对不齐&lt;/td&gt;
&lt;td&gt;先给 1–3 个输入输出对&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;先想后答&lt;/td&gt;
&lt;td&gt;复杂问题一步到位容易算错&lt;/td&gt;
&lt;td&gt;要求先列分析步骤再给结论&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;分步拆解&lt;/td&gt;
&lt;td&gt;大任务做一半就跑偏&lt;/td&gt;
&lt;td&gt;拆成多轮，每轮只做一件事&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;限定输出格式&lt;/td&gt;
&lt;td&gt;结果没法直接喂给下一步&lt;/td&gt;
&lt;td&gt;指定 JSON 字段或 Markdown 表格&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;负面约束&lt;/td&gt;
&lt;td&gt;总爱多做、爱编、爱啰嗦&lt;/td&gt;
&lt;td&gt;明确列出禁止项&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;技巧一：给示例（Few-shot）&lt;/h3&gt;
&lt;p&gt;与其用三百字描述你想要什么风格，不如直接给一个例子。续写机器最擅长的就是模式复制：给它看一遍，它就照着来。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;反例：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;把下面的评论分类，要分成正面、负面、中性，语气强烈的要特别标注，
不太确定的就标待定，简短一点：
「这破软件又闪退了，第三次了！！」
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;描述写了一堆，模型还是要猜：输出纯文字还是带括号？强烈怎么标？结果每次都不一样。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;改法：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;按示例的格式给评论分类，只输出分类结果，不要解释。

示例：
输入：「物流很快，包装也仔细。」
输出：正面 | 强度：普通

输入：「等了半个月才发货，客服还联系不上。」
输出：负面 | 强度：强烈

输入：「就那样吧，能用。」
输出：中性 | 强度：普通

待分类：「这破软件又闪退了，第三次了！！」
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个示例胜过一段说明：分隔符、字段顺序、取值范围，全都定死了。这就是 Few-shot——用少量示例教会模型任务的样子。分类、提取、格式转换这类任务，Few-shot 是性价比最高的技巧，没有之一。&lt;/p&gt;
&lt;h3&gt;技巧二：先想后答&lt;/h3&gt;
&lt;p&gt;让模型直接给答案，相当于让它把思考和回答挤在同一句话里，复杂一点的问题必然翻车。改法是明确要求它先展开推理，再给结论。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;反例：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;我们团队 6 个人，项目还剩 9 天，其中 2 人下周要请 2 天假，
任务清单一共 34 项，已经完成 11 项，还来得及吗？
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;改法：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;先一步步算给我看，再给结论：
1. 先算剩余总人天（注意扣掉请假）
2. 再算已完成任务的平均耗时，估算剩余任务需要的人天
3. 对比两者，给出「来得及 / 来不及 / 勉强」的结论和缺口

数据：团队 6 人，项目还剩 9 个工作日，其中 2 人下周各请 2 天假；
任务共 34 项，已完成 11 项，已完成部分实际花了 28 人天。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;区别在于：反例里模型会凭感觉先甩一个结论，再倒推理由凑数；改法里它被迫把计算过程写出来，每一步都是下一步的上下文，算错的概率大幅下降，你也能顺着过程检查它错在哪。涉及数字、逻辑、多条件判断的任务，一律先想后答。&lt;/p&gt;
&lt;h3&gt;技巧三：分步拆解&lt;/h3&gt;
&lt;p&gt;一个任务如果包含「理解、加工、产出」多个阶段，不要指望一条提示词全干完。拆成多轮对话，每轮只做一件事，做完你确认了再往下走。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;反例：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;读一下这篇行业报告，提炼观点，写一篇 1500 字的评论文章，
要有数据支撑，观点要犀利，最后再起 5 个标题。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;模型会在一轮里同时干五件事，结果是观点提炼得潦草、评论写得平庸、标题凑数——每个环节都只有六成力。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;改法（分三轮）：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;第一轮：只做提炼。把这篇报告的核心观点列成清单，每条注明出处段落，不要评论。
（确认清单无误后）
第二轮：基于清单第 2、4 条观点，写 800 字评论草稿，先不要标题。
（改完草稿后）
第三轮：针对定稿内容起 5 个标题，风格分别是严肃、提问、数字型各至少一个。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拆解的本质是把「一次生成定生死」变成「流水线分段验收」，每一段的输入都是上一段确认过的产物，误差不会累积放大。写长文、做方案、处理复杂代码改动时，这个技巧配合 &lt;a href=&quot;/posts/ai-coding-assistants/&quot;&gt;AI 编程助手实战&lt;/a&gt; 里「先复述再动手」的方法一起用，效果最好。&lt;/p&gt;
&lt;h3&gt;技巧四：限定输出格式&lt;/h3&gt;
&lt;p&gt;如果输出还要被程序处理、或者要贴进表格和文档，就必须在提示词里把格式钉死。最常用的两种：JSON 和 Markdown 表格。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;反例：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;从这段话里提取公司名、金额和日期：
「星野科技于 3 月 12 日宣布完成 B 轮融资，金额 2.3 亿元，由澜江资本领投。」
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;模型可能回你一整段话：「星野科技在 3 月 12 日完成了 2.3 亿元的 B 轮融资……」信息全在，但你还得手工再抠一遍。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;改法：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;从文本中提取信息，只输出一个 JSON 对象，不要任何解释文字。字段定义：
- company：公司全称（字符串）
- event_date：事件日期（格式 YYYY-MM-DD，年份缺失时用 null）
- amount_cny：金额，单位人民币元（纯数字，无法确定时用 null）
- event：事件类型（字符串）

文本：「星野科技于 3 月 12 日宣布完成 B 轮融资，金额 2.3 亿元，由澜江资本领投。」
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出会是规规矩矩的 &lt;code&gt;{&quot;company&quot;: &quot;星野科技&quot;, &quot;event_date&quot;: null, ...}&lt;/code&gt;，可以直接被程序解析。关键细节有三个：声明「只输出 JSON」堵住解释性废话；逐个字段给类型和格式；&lt;strong&gt;给缺失值留好出口（null）&lt;/strong&gt;，否则模型为了填满字段会编一个出来——这是数据类任务最常见的翻车点，在 &lt;a href=&quot;/posts/ai-rag-knowledge-base/&quot;&gt;RAG 个人知识库&lt;/a&gt; 里处理文档提取时同样致命。&lt;/p&gt;
&lt;p&gt;不需要机器处理时，Markdown 表格是给人看的最优格式：「用 Markdown 表格输出，列为：方案、成本、风险、工期，一行一个方案」，比一大段散文好读得多。&lt;/p&gt;
&lt;h3&gt;技巧五：负面约束&lt;/h3&gt;
&lt;p&gt;模型有个讨人喜欢的倾向：多做、做满、显得 helpful。你不想要的东西，必须明说禁止。常见的负面约束清单：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;不要编造：原文没有的信息写「未提及」，不要推测补全&lt;/li&gt;
&lt;li&gt;不要啰嗦：不要开场白、不要总结性套话，直接给内容&lt;/li&gt;
&lt;li&gt;不要多做：只改我指定的函数，其他代码原样保留&lt;/li&gt;
&lt;li&gt;不要解释：只输出结果，不要说明理由&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;反例：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;帮我润色这段话：我们公司下周二要开新品发布会，欢迎大家来。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它可能给你五个版本、每版附一段赏析，最后问你喜欢哪个——你只是想要一句话而已。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;改法：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;润色下面这句话，只输出润色后的一句，不要给多个版本，不要解释改动，不要加感叹号：
「我们公司下周二要开新品发布会，欢迎大家来。」
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意负面约束要具体、可判定。「不要写得太差」不是约束，「不超过 100 字、不用感叹号、只给一个版本」才是。写不出具体禁止项，说明你自己还没想清楚要什么——这时候先别怪模型。&lt;/p&gt;
&lt;h2&gt;按场景的模板库&lt;/h2&gt;
&lt;p&gt;下面五个模板覆盖最高频的场景，结构都是六要素的裁剪版，替换掉尖括号里的部分就能用，建议存成笔记长期复用。&lt;/p&gt;
&lt;h3&gt;模板一：长文总结&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;你是一名信息分析师。把下面的长文总结成给管理层看的简报。

要求：
- 先给 3 句话的核心结论，再给要点清单
- 要点按重要性排序，每条不超过 40 字，必须能在原文找到依据
- 涉及数字、时间、人名时保留原文表述，不要换算和推测
- 原文没结论的部分单独列一节「原文未明确」，不要替作者下结论

输出格式：
## 核心结论
（3 句）
## 要点
- ……
## 原文未明确
- ……

原文：
&amp;lt;把长文贴在这里&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;模板二：翻译&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;你是一名资深译者，做&amp;lt;目标语言&amp;gt;本地化翻译，不做机翻腔直译。

规则：
- 意译优先：成语、俚语换成目标语言里的等效说法，不要逐字硬译
- 专业术语按&amp;lt;行业&amp;gt;领域的通行译法，全文统一
- 人名、公司名、产品名保留原文
- 原文的段落结构和语气（正式/口语）保持不变
- 拿不准的句子在译文后用（注：……）标出你的处理方式

待翻译：
&amp;lt;原文&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;模板三：改代码&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;你是一名资深&amp;lt;语言&amp;gt;工程师。修改下面的代码，目标：&amp;lt;要解决的问题，如「消除重复查询」&amp;gt;。

约束：
- 只改与目标直接相关的部分，其他函数和逻辑原样保留
- 不引入新依赖，不改变对外接口和函数签名
- 保持原有代码风格（命名、缩进、注释密度）

输出格式：
1. 先用 3 句话说明改动思路
2. 再给修改后的完整代码
3. 最后列出你没动但值得注意的潜在问题（没有就写「无」）

代码：
&amp;lt;代码&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;编程场景的更多打法（让模型先复述需求、分步验收）可以看 &lt;a href=&quot;/posts/ai-coding-assistants/&quot;&gt;AI 编程助手实战&lt;/a&gt;，模板和流程是配套的。&lt;/p&gt;
&lt;h3&gt;模板四：写测试&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;你是一名测试工程师。为下面的函数编写单元测试，使用&amp;lt;测试框架，如 pytest&amp;gt;。

覆盖要求：
- 正常路径：至少 2 个典型输入
- 边界值：空值、零、最大值、刚好越界各至少 1 个
- 异常路径：每个会抛出的异常至少 1 个用例
- 每个用例只测一个行为，命名用「test_场景_预期结果」格式
- 不要 mock 被测函数本身，只 mock 它的外部依赖

只输出测试代码，必要的断言注释可以写，不要写使用说明。

函数：
&amp;lt;函数代码和签名说明&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;模板五：数据提取&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;从下面的非结构化文本中提取记录，输出 JSON 数组，不要解释。

每条记录的字段：
- name：姓名（字符串，缺失用 null）
- phone：手机号（只保留数字，缺失用 null）
- intent：意向等级，只能取 &quot;高&quot; / &quot;中&quot; / &quot;低&quot;，依据是文本中的明确表述，
  没有明确表述时用 &quot;低&quot;，不要凭语气猜测拔高
- note：其他值得记录的信息（一句话，没有写空字符串）

文本里有几条提取几条，不要合并，不要遗漏。

文本：
&amp;lt;文本&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;五个模板有个共同点：都给缺失和异常留了明确出口（写 null、写「无」、单列一节）。这是模板能不能长期稳定复用的分水岭——模型在没路走的时候一定会编，给它留一条「诚实交代」的路，它就很少编。&lt;/p&gt;
&lt;h2&gt;迭代方法：把提示词当代码来调&lt;/h2&gt;
&lt;p&gt;一次写出完美提示词的人不存在，稳定好用的提示词都是迭代出来的。流程和调代码一模一样：收集失败案例、一次只改一处、留版本记录。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步：收集 bad case。&lt;/strong&gt; 准备一个文档（笔记、表格都行），每次输出不满意，把三样东西存下来：当时的提示词、模型的输出、你认为它错在哪。攒到 5 条以上再动手改——凭一两个案例改提示词，很容易过拟合到个例上，把原来对的也改坏。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二步：定位缺的要素。&lt;/strong&gt; 对照 bad case 逐条归因：格式乱是缺示例，跑题是约束没写全，算错是没让它先想后答，编造是没给缺失出口。归因到要素，改动就有了靶子。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三步：一次只改一处。&lt;/strong&gt; &amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;迭代时最忌讳一口气重写整条提示词&amp;lt;/span&amp;gt;——输出变好了你不知道是哪处改动起的作用，变差了也不知道该回滚哪句。一次加一条约束、换一个示例，跑一遍 bad case 集合看通过率，再决定下一步。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第四步：版本管理。&lt;/strong&gt; 提示词定稿后像代码一样存档：文件名带版本号（&lt;code&gt;周报总结-v3.md&lt;/code&gt;），文件头写清楚适用模型、最后修改日期、这版解决了哪几个 bad case。模型换代时旧提示词可能失效，有版本记录才知道从哪一版开始重新调。&lt;/p&gt;
&lt;p&gt;走完几轮你会发现一个规律：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;提示词工程的本质是迭代，不是灵感&amp;lt;/span&amp;gt;。高手和新手的差距不在第一稿写得多漂亮，而在有没有一套收集失败、定位问题、小步验证的笨办法。&lt;/p&gt;
&lt;h2&gt;三个常见误区&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;误区一：堆形容词。&lt;/strong&gt; 「写一篇精彩绝伦、引人入胜、文采飞扬的文章」——形容词对续写分布的影响微乎其微，模型只会多给你几个感叹号。形容词要换成可执行的描述：不说「精彩」，说「每段不超过 3 句、第一句必须是结论」；不说「专业」，说「用行业术语、给出处」。把主观感受翻译成客观规格，是写提示词的基本功。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;误区二：一次塞十个任务。&lt;/strong&gt; 「帮我翻译这篇文章，顺便总结一下，再写个摘要，提取关键词，最后翻译标题」——多任务挤在一条里，模型会按自己的优先级取舍，通常是最容易的做满、最难的糊弄。真有十个任务，就拆成十轮，或者明确编号并要求逐个输出、逐个交付，方便你逐个验收。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;误区三：自相矛盾的约束。&lt;/strong&gt; &amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;「要非常详细，一个细节都不能漏，但总字数不能超过 200 字」这类互相打架的要求，会让模型随机放弃其中一条&amp;lt;/span&amp;gt;，而且每次放弃的还不一样，输出稳定性直接归零。下笔前把约束列出来互相检查一遍：长度、深度、风格之间有没有不可能三角，有冲突就先自己排优先级，并把优先级写进提示词（「字数优先于细节完整度」）。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：提示词写得很全了，输出还是太啰嗦怎么办？&lt;/strong&gt;
先查是不是只有定性要求（「简短一点」）没有定量约束，改成「不超过 150 字」「只给结论不给理由」。还不行就加示例：给一段你认可的简短输出做标杆。另外注意开场白问题——明确写「不要开场白和结束语，直接从内容开始」，这一条对啰嗦的抑制效果出奇地好。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：要求了 JSON 格式，它还是夹带解释文字怎么办？&lt;/strong&gt;
把要求写得更硬：「只输出 JSON，不要 Markdown 代码围栏，不要任何前后缀文字」。还夹带的话，通常是任务本身让它为难——比如字段定义不清、文本里根本提不到某个字段，它只好用文字解释。回去检查字段定义和缺失值出口，多数是提示词的问题，不是模型不听话。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：长文档喂进去，它总是丢中间的内容？&lt;/strong&gt;
这是长上下文的固有现象：模型对开头和结尾的注意力最强，中间部分容易被忽略。解法有三个：把最关键的要求放在提示词的开头和结尾各写一遍；长文档先分段提炼再合并（分步拆解）；提问时点名要它引用原文段落，逼它回去看中间部分。文档量再大，就该上 &lt;a href=&quot;/posts/ai-rag-knowledge-base/&quot;&gt;RAG 个人知识库&lt;/a&gt; 的方案，而不是硬塞上下文。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：同一条提示词，每次输出差别很大怎么办？&lt;/strong&gt;
先接受一部分随机性是正常的，然后逐项收紧：格式用示例钉死、取值范围用枚举限定、步骤用编号固定。通过 API 调用时还可以把 temperature 参数调低（0 到 0.3）换取稳定性。收紧之后还飘，多半是任务本身开放度高——比如起标题、想创意，这类任务就该一次要 5 个候选再挑，而不是追求每次都一样。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：它一本正经地胡说八道，怎么防？&lt;/strong&gt;
三招：一是给缺失出口，明确「不知道就写不知道，不要推测」；二是要求给依据，事实类问题让它标注信息来自原文哪一段，标不出来的自动露馅；三是关键结论人工复核，尤其是数字、人名、日期和 API 用法——这类内容模型编起来毫无心理负担，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;凡是要直接用在生产环境、发给客户、写进代码的输出，都必须过一遍人工检查&amp;lt;/span&amp;gt;，没有例外。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：提示词越写越长，有没有上限？&lt;/strong&gt;
有。约束互相稀释、重点被淹没，长提示词的边际收益下降很快。经验上，日常任务控制在骨架六要素齐全即可；超过千字的提示词，先删重复表述和互相矛盾的条款，再考虑分步拆解——把一轮说完改成多轮确认，通常比继续加长更有效。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;回头看这一篇的逻辑链：因为模型是续写机器，所以上下文即程序；因为上下文是程序，所以要用六要素把规格写全，用示例代替形容词、用步骤代替许愿、用格式约束代替事后整理、用负面清单堵住多做和编造；因为一次写不到位，所以要像调代码一样收集 bad case、小步迭代、留版本。&lt;/p&gt;
&lt;p&gt;具体落地就三件事：把模板库里和你工作最相关的两三个模板抄走改成自己的；下次输出不满意时，先归因缺哪个要素再动手；攒一个 bad case 文档，改提示词从「凭感觉」变成「看数据」。&lt;/p&gt;
&lt;p&gt;本系列的其他篇目：工具怎么选看&lt;a href=&quot;/posts/ai-tools-overview/&quot;&gt;全景图与选型指南&lt;/a&gt;，本地部署看 Ollama 与 RAG 两篇，编程场景看编程助手实战。提示词是所有这些工具的公共接口——这一篇练好了，换什么工具都受益。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：RAG 个人知识库</title><link>https://www.anexns.cloudns.org/posts/ai-rag-knowledge-base/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-rag-knowledge-base/</guid><description>从原理到落地讲透 RAG：文档切分、向量嵌入、向量库、检索与提示词拼装五步流水线逐段拆解，用 AnythingLLM 完整搭一个能问答的个人知识库，并给出检索调优、局限说明与排障方法。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：你的文档，大模型一无所知&lt;/h2&gt;
&lt;p&gt;攒了几年的文档躺在硬盘里：产品手册、合同模板、会议纪要、读书笔记、自己写过的运维文档。想查点什么，只能靠文件名和全文搜索硬翻。把问题丢给大模型也没用——它训练时没见过你的私有文档，问它只会一本正经地编。&lt;/p&gt;
&lt;p&gt;另一条看似省事的路，是把整篇文档复制进对话框，让模型「读完再答」。文档一长，这条路立刻露馅：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;塞不下&lt;/strong&gt;：几十页的 PDF 动不动几万字，超过上下文窗口就直接截断，模型只看到前半截。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;塞得下也贵&lt;/strong&gt;：每问一个问题都要把全文重新发一遍，按 Token 计费的 API 账单涨得飞快，本地模型则要先花几十秒「读」一遍才开口。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;注意力被稀释&lt;/strong&gt;：上下文越长，模型越容易忽略中间段落的关键信息，业内把这叫 Lost in the Middle——答案明明在文档里，它就是视而不见。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;RAG（Retrieval-Augmented Generation，检索增强生成）换了个思路：&lt;strong&gt;不让模型背下你的文档，而是先从文档里检索出相关的几段，再让它照着这几段回答&lt;/strong&gt;。相当于把开卷考试的书提前做成了带索引的卡片，答题时只翻相关的那几张。这一篇就把这套流水线拆开讲透，再动手搭一个真正能用的个人知识库。&lt;/p&gt;
&lt;h2&gt;RAG 是什么：先检索，再回答&lt;/h2&gt;
&lt;p&gt;一次完整的 RAG 问答分两个阶段。建库阶段是离线做的：把文档切成小段，每段用 Embedding 模型转成一串数字（向量），存进向量库。提问阶段是实时做的：把用户的问题也转成向量，去库里找最相似的几段，连同问题一起拼进提示词，交给 LLM 生成回答。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;文档 ──→ 切分 Chunk ──→ Embedding 模型 ──→ 向量库（建库，离线一次）
                                              ↑
问题 ──→ Embedding 模型 ──→ 向量检索 Top-K ───┘
                                              ↓
                        拼提示词（上下文＋问题）──→ LLM ──→ 带出处回答
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;和另外两种让模型「学会」私有数据的办法比，RAG 的定位非常清楚：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方案&lt;/th&gt;
&lt;th&gt;做法&lt;/th&gt;
&lt;th&gt;更新文档&lt;/th&gt;
&lt;th&gt;成本&lt;/th&gt;
&lt;th&gt;出处可追溯&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;RAG&lt;/td&gt;
&lt;td&gt;检索相关片段再回答&lt;/td&gt;
&lt;td&gt;改文档重建索引即可，分钟级&lt;/td&gt;
&lt;td&gt;低，主要是嵌入与少量生成 Token&lt;/td&gt;
&lt;td&gt;能，能标出引用的原文段落&lt;/td&gt;
&lt;td&gt;文档问答、客服知识库、企业内搜&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;长上下文直塞&lt;/td&gt;
&lt;td&gt;整篇文档放进提示词&lt;/td&gt;
&lt;td&gt;每次提问都要重发全文&lt;/td&gt;
&lt;td&gt;高，长文档反复计费&lt;/td&gt;
&lt;td&gt;勉强，模型自己未必说得清&lt;/td&gt;
&lt;td&gt;一次性分析单篇短文档&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;微调（Fine-tuning）&lt;/td&gt;
&lt;td&gt;用文档继续训练模型&lt;/td&gt;
&lt;td&gt;重新训练，天级起步&lt;/td&gt;
&lt;td&gt;高，要 GPU 和数据工程&lt;/td&gt;
&lt;td&gt;不能，知识揉进参数里&lt;/td&gt;
&lt;td&gt;改变说话风格、固定输出格式&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;结论先放这里：**个人知识库九成场景选 RAG 就对了——它不训练模型，只给模型配了一个随时可更新的外置索引。**微调解决的是「怎么说」，RAG 解决的是「说什么」，两者不是替代关系。&lt;/p&gt;
&lt;h2&gt;五步流水线：把 RAG 拆开看&lt;/h2&gt;
&lt;p&gt;流水线的每一段都有自己的关键参数，任何一段拉胯，最终答案都会跟着歪。逐段拆：&lt;/p&gt;
&lt;h3&gt;第一步：文档切分（Chunk）&lt;/h3&gt;
&lt;p&gt;文档不能整篇存进向量库，必须先切成几百字的小段。原因很实际：检索的粒度就是切分的粒度，整篇存进去，命中一篇等于把整篇塞回提示词，又回到长上下文的老问题。&lt;/p&gt;
&lt;p&gt;切分有三种常见策略：按固定长度切（简单粗暴，可能拦腰截断一句话）；按段落和标题切（保住语义边界，长段落再二次切分）；按 Markdown 标题层级切（结构化文档效果最好）。实际经验值：中文文档每段 300～600 字、重叠保留上一段的 10%～20% 作为 overlap，是个稳妥的起点。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;分段过大，检索回来的全是无关上下文；分段过小，一句完整的话被切成两半，答案支离破碎。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h3&gt;第二步：嵌入向量（Embedding）&lt;/h3&gt;
&lt;p&gt;Embedding 模型负责把每段文字转成向量（一串几百到几千维的浮点数）。它的本事是「语义近，向量就近」：「怎么重置密码」和「找回登录口令」字面没几个字相同，向量距离却很近——这是关键词搜索做不到的。&lt;/p&gt;
&lt;p&gt;选嵌入模型只看三件事：中文效果、向量维度、跑得快不快。本地路线的常见选择有 bge-m3（多语言，中文表现好，1024 维）、nomic-embed-text（轻量，768 维，英文为主）、mxbai-embed-large 等。用 Ollama 拉取只要一行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ollama pull bge-m3
ollama pull nomic-embed-text
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
建库和提问必须用&lt;strong&gt;同一个&lt;/strong&gt;嵌入模型：问题向量和文档向量不在同一个坐标系里，距离就算不出来。更要命的是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;嵌入模型一旦中途更换，库里存量文档的向量全部作废，必须全量重建索引&amp;lt;/span&amp;gt;，所以选型要在导入大批文档之前定死，别导了一半才换。
:::&lt;/p&gt;
&lt;h3&gt;第三步：向量库（Vector Store）&lt;/h3&gt;
&lt;p&gt;向量库就是存向量并支持「按相似度快速找 Top-K」的数据库。小规模个人知识库（几万段以内）根本不用上重型装备：AnythingLLM 内置的 LanceDB、单文件的 Chroma 本地模式都够用；文档量再大，或者想让多个应用共用，再考虑 Qdrant、pgvector（PostgreSQL 插件）、Milvus 这类独立服务。个人场景的选型原则是能内嵌就内嵌，少一个常驻服务少一份维护。&lt;/p&gt;
&lt;h3&gt;第四步：检索（Retrieval）&lt;/h3&gt;
&lt;p&gt;提问时，问题先经同一个嵌入模型转成向量，在向量库里按余弦相似度（或欧氏距离）取出最相近的 K 段，这就是 Top-K，个人知识库一般取 3～6。进阶玩法有三个：&lt;strong&gt;混合检索&lt;/strong&gt;（向量检索加关键词 BM25 检索合并结果，专治人名、编号、术语这类必须字面命中的查询）、&lt;strong&gt;重排序&lt;/strong&gt;（先粗召回 20 段，再用 Reranker 模型精排取前 4 段）、&lt;strong&gt;查询改写&lt;/strong&gt;（先让 LLM 把口语化的问题改写成检索友好的表述）。这三个是后面调优章节的主角，这里先混个脸熟。&lt;/p&gt;
&lt;h3&gt;第五步：拼提示词（Prompt 组装）&lt;/h3&gt;
&lt;p&gt;检索到的段落不是直接丢给模型，而是套进一个带约束的模板：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;你是知识库问答助手。仅根据下面提供的上下文回答问题；
上下文里没有的信息，明确回答「资料中没有提到」，不要编造。
回答时标注依据来自哪一段上下文。

上下文：
{context}

问题：{question}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这一步看着不起眼，却决定了模型是「照着资料答」还是「自由发挥」。约束句、引用要求、拒答规则都写在这里，想深挖提示词写法的可以看本系列的&lt;a href=&quot;/posts/ai-prompt-engineering/&quot;&gt;提示词工程实战&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;五段的参数取舍，汇总成一张表：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;环节&lt;/th&gt;
&lt;th&gt;关键参数&lt;/th&gt;
&lt;th&gt;调大/调强的效果&lt;/th&gt;
&lt;th&gt;调小/调弱的代价&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;切分&lt;/td&gt;
&lt;td&gt;分段长度&lt;/td&gt;
&lt;td&gt;上下文完整，但检索粒度粗、噪声多&lt;/td&gt;
&lt;td&gt;命中精准，但语义容易被截断&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;切分&lt;/td&gt;
&lt;td&gt;重叠（Overlap）&lt;/td&gt;
&lt;td&gt;跨段信息不易丢&lt;/td&gt;
&lt;td&gt;索引体积和重复内容变多&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;嵌入&lt;/td&gt;
&lt;td&gt;模型与维度&lt;/td&gt;
&lt;td&gt;语义表达更细，召回质量上限更高&lt;/td&gt;
&lt;td&gt;建库和查询更慢、更吃内存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;检索&lt;/td&gt;
&lt;td&gt;Top-K&lt;/td&gt;
&lt;td&gt;召回更全&lt;/td&gt;
&lt;td&gt;无关段落挤进提示词，干扰回答&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;检索&lt;/td&gt;
&lt;td&gt;相似度阈值&lt;/td&gt;
&lt;td&gt;只放高相关段落进来，宁缺毋滥&lt;/td&gt;
&lt;td&gt;阈值过高会把正确答案也挡在门外&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;拼装&lt;/td&gt;
&lt;td&gt;提示词约束&lt;/td&gt;
&lt;td&gt;拒答和引用更规范&lt;/td&gt;
&lt;td&gt;模板太死板会误杀本可回答的问题&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;三条搭建路线：工具、平台、代码&lt;/h2&gt;
&lt;p&gt;原理清楚了，落地有三条路线，先对号入座：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;路线&lt;/th&gt;
&lt;th&gt;代表&lt;/th&gt;
&lt;th&gt;上手门槛&lt;/th&gt;
&lt;th&gt;可控程度&lt;/th&gt;
&lt;th&gt;适合谁&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;现成工具型&lt;/td&gt;
&lt;td&gt;AnythingLLM（桌面版/自托管）&lt;/td&gt;
&lt;td&gt;低，装好就能导文档&lt;/td&gt;
&lt;td&gt;中，关键参数都有界面可调&lt;/td&gt;
&lt;td&gt;只想把个人文档变成能问答的知识库，不想写代码&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;平台型&lt;/td&gt;
&lt;td&gt;Dify 知识库&lt;/td&gt;
&lt;td&gt;中，要先部署平台&lt;/td&gt;
&lt;td&gt;高，分段、检索、重排序都是独立模块&lt;/td&gt;
&lt;td&gt;已经在用 Dify 做应用，想把知识库接进工作流&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;代码型&lt;/td&gt;
&lt;td&gt;LangChain / LlamaIndex&lt;/td&gt;
&lt;td&gt;高，要写代码调参数&lt;/td&gt;
&lt;td&gt;最高，每一段都能换实现&lt;/td&gt;
&lt;td&gt;开发者，要把 RAG 嵌进自己的产品或做深度定制&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;平台型的 Dify 知识库和上一篇是同一个生态，部署细节在&lt;a href=&quot;/posts/ai-dify-workflow/&quot;&gt;Dify 工作流应用搭建&lt;/a&gt;里有完整流程，这里不重复。代码型先建立概念即可：以 LlamaIndex 为例，整条流水线压缩到几行——&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

documents = SimpleDirectoryReader(&quot;docs&quot;).load_data()      # 读文档
index = VectorStoreIndex.from_documents(documents)          # 切分＋嵌入＋入库
query_engine = index.as_query_engine(similarity_top_k=4)    # 检索 Top-K＝4
print(query_engine.query(&quot;年假有几天？&quot;))                    # 拼提示词＋生成
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;四行背后正是前面拆的五步。先用工具型把感觉跑通，再看代码型不会抽象。下面就用工具型路线完整搭一个。&lt;/p&gt;
&lt;h2&gt;实战：用 AnythingLLM 搭一个完整的个人知识库&lt;/h2&gt;
&lt;p&gt;AnythingLLM 是开源的知识库问答应用，支持本地部署、内置向量库、能接本地和云端各类模型，正好把五步流水线全包了（本节用的 AnythingLLM 项目地址：https://github.com/Mintplex-Labs/anything-llm ）。自托管用 Docker 一条命令（本地模型部署还没弄好的，先看本系列的&lt;a href=&quot;/posts/ai-ollama-local-llm/&quot;&gt;Ollama 部署本地大模型&lt;/a&gt;把模型一侧备齐）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d --name anythingllm \
  -p 3001:3001 \
  --cap-add SYS_ADMIN \
  -v anythingllm_storage:/app/server/storage \
  -e STORAGE_DIR=&quot;/app/server/storage&quot; \
  mintplexlabs/anythingllm:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;http://localhost:3001&lt;/code&gt; 完成初始化，然后按顺序做四件事：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步，选 LLM。&lt;/strong&gt; 在设置里把对话模型指向本地 Ollama（地址填宿主机 IP 加 11434 端口，容器里别写 localhost），选一个中文能力过关的对话模型。想全本地、零外发，这一步和下一步都走本地是关键。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二步，选嵌入模型。&lt;/strong&gt; 在 Embedding 设置里同样选 Ollama，模型填前面拉好的 &lt;code&gt;bge-m3&lt;/code&gt;。呼应前面的警告：这一步定下来就别再改，改了要重建全部索引。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三步，建工作区导文档。&lt;/strong&gt; 新建一个 Workspace（工作区就是一个独立知识库），把 PDF、Markdown、Word、TXT 拖进去，点 Move to Workspace 再保存，系统会自动完成切分和嵌入，在文档列表里能看到每篇被切成了多少段。先导三五篇你最熟的文档，方便验证答案对错。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第四步，问答实测。&lt;/strong&gt; 在工作区里直接提问。测的时候专挑三种问题：文档里有明确答案的（验准确）、文档里没有的（验它会不会老实说不知道）、需要跨段落拼凑的（验检索召回）。每条回答下面都会带引用来源，点开能看到命中的原文段落——这是判断问题出在检索还是生成环节的第一手证据。&lt;/p&gt;
&lt;p&gt;跑通之后，去工作区设置里把两个参数按自己的文档调一遍：文本分段长度（技术文档可以给到 800～1000，笔记类 400～600 更合适）和向量相似度阈值（默认宽松，噪声多就往上收）。改完分段参数记得对文档重新处理一次才生效。&lt;/p&gt;
&lt;h2&gt;效果调优：答得准不准，主要看检索&lt;/h2&gt;
&lt;p&gt;知识库答歪了，十有八九不是模型的锅。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;RAG 的答题质量，七分靠检索、三分靠模型&amp;lt;/span&amp;gt;：检索没把正确段落捞回来，再强的模型也只能对着无关上下文编。调优按这个顺序来：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;先看引用，再改参数&lt;/strong&gt;：每次答错，先点开引用看命中的段落对不对。没命中正确段落，是检索问题；命中了却答错，才是模型或提示词问题。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;分段与重叠&lt;/strong&gt;：答案总差半句话，多半是切分把关键句拦腰截断，加大 overlap 到 20% 再重建；命中的段落总带着大段无关内容，就把分段长度调小。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Top-K 与阈值&lt;/strong&gt;：问题涉及面广（需要综合多处）就调大 Top-K 到 6～8；简单事实问答保持 3～4 并提高相似度阈值，提示词更干净。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;上重排序&lt;/strong&gt;：粗召回的顺序不可靠时，加 Reranker（如 bge-reranker 系列）对召回的 20 段精排，再取前 4 段进提示词，对「相关段落排在第 8 位被 Top-K 截掉」这类问题立竿见影。Dify 等平台把重排序做成了知识库的可选开关，工具型应用则看是否支持外接。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;混合检索救专有名词&lt;/strong&gt;：产品型号、工单编号、人名这类必须字面命中的查询，纯向量检索经常翻车，开启向量＋关键词的混合检索能明显改善。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;引用溯源常开&lt;/strong&gt;：让回答强制标注来源段落，既方便人工核对，也能在答错时一眼定位是哪段资料的问题。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;反过来，检索确认无误、引用段落完全正确，模型还是答歪，那才轮到换更大的对话模型或改提示词模板。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;调优顺序永远是先检索、后模型，顺序反了只会越调越贵。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;RAG 的局限：它不是万能的&lt;/h2&gt;
&lt;p&gt;把丑话说在前面，免得搭完才发现不对路：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;表格是老大难&lt;/strong&gt;：PDF 里的表格抽出来经常行列错位，合并单元格更是重灾区。问「第三季度华东区销售额」这类查表问题，命中率明显低于正文问答，重要表格建议单独整理成 Markdown 再入库。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;扫描件等于白导&lt;/strong&gt;：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;扫描版 PDF 里是图片不是文字，不先做 OCR，导进去就是一堆空壳，检索永远命不中。&amp;lt;/span&amp;gt;先用 OCR 工具转成可检索文本再入库。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;跨文档推理弱&lt;/strong&gt;：RAG 擅长「答案在某一段里」的查找型问题；「对比 A 方案和 B 方案的成本差异」这种要同时召回多篇文档再做推理的问题，召回容易漏、推理容易浅，只能算勉强可用。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;资料本身错了它照答&lt;/strong&gt;：RAG 只负责忠实复述你的文档，文档里的旧数据、过期政策，它会一本正经地引用出来。知识库的保鲜靠人，不靠模型。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;隐私要自己守&lt;/strong&gt;：本地部署加本地模型，数据可以不出内网；但如果图省事用云端知识库服务，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;合同、病历、财务这类敏感文档上传之前，先想清楚对方的留存与合规问题。&amp;lt;/span&amp;gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;问：导进去的文档，提问却说找不到？&lt;/strong&gt;
先查三件事：文档状态是不是处理完成（切分嵌入失败会在文档列表报错）；问题问法和文档用词差太远时，换个说法或加上文档里的关键词再试；相似度阈值是不是设得过高，把勉强相关的段落全挡了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;问：回答全是套话，明显没用到文档内容？&lt;/strong&gt;
多半是 LLM 没接对或工作区没挂文档。确认当前工作区里文档已保存生效，再看回答下方的引用：没有引用，说明这一轮根本没走检索，或者命中的段落被阈值过滤光了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;问：命中的段落是对的，回答却驴唇不对马嘴？&lt;/strong&gt;
这是生成环节的问题：换中文能力更强的对话模型，或者把提示词模板里的约束写得更明确（要求逐条引用、禁止使用上下文之外的知识）。别一上来就动检索参数。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;问：换了嵌入模型之后，旧文档全部搜不到？&lt;/strong&gt;
正是前面警告过的情况：新旧向量不在同一坐标系。把嵌入模型切回去，或者对全部文档重新处理一遍重建索引，没有第三条路。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;问：文档更新了，答案还是旧的？&lt;/strong&gt;
向量库里存的是旧版本切的段。把新版文档重新上传并处理，旧版本记得删掉，否则新旧段落会同时被检索到，模型可能引用过期的那一份。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;问：几百篇文档导进去，建库慢得离谱？&lt;/strong&gt;
瓶颈通常在嵌入这一步：本地嵌入模型跑在 CPU 上逐段算向量就是慢。对策是换 GPU 跑嵌入、换更轻量的嵌入模型，或者分批导入。建库是一次性成本，提问时的检索反而很快，别为建库速度牺牲长期效果。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;问：中英文混排文档效果差？&lt;/strong&gt;
嵌入模型的多语言能力是关键，中文场景优先选 bge-m3 这类多语言模型；纯英文模型处理中文文档，语义向量质量会明显打折。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;RAG 的本质，是给大模型配了一个&lt;strong&gt;可检索、可更新、可溯源&lt;/strong&gt;的外置记忆：文档切分决定粒度，嵌入模型决定语义坐标，向量库决定存取效率，检索决定喂什么，提示词决定怎么答。个人知识库用 AnythingLLM 这类工具半小时就能跑通，真正的功夫在后面的调优——记住先检索、后模型的顺序，盯着引用溯源一段段抠，效果比盲目换大模型实在得多。下一篇我们换个赛道，看看 Dify 怎么把知识库接进可视化工作流里。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：Skill Seekers 把文档变成 AI 技能</title><link>https://www.anexns.cloudns.org/posts/ai-skill-seekers/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-skill-seekers/</guid><description>用 Skill Seekers 把文档站、GitHub 仓库、PDF 等 18 种来源一次性炼成结构化的 Claude 技能包：三条命令上手、GitHub 仓库 AST 深挖、AI 增强、多目标导出与 MCP 集成全流程。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：每换一个框架，就要重新喂一遍文档&lt;/h2&gt;
&lt;p&gt;用 AI 编程助手写代码的人都遇到过这种场面：接手一个没用过的框架，先把官方文档一页页贴进对话，贴到上下文快塞爆，助手还是把 API 名字记串、把旧版本的参数安到新版本头上。换个新会话，一切从头再来。&lt;/p&gt;
&lt;p&gt;问题不在模型笨，在于喂法不对：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;文档是写给人读的网页，结构散、噪音多，整页灌进去，一大半 Token 耗在导航栏和页脚上。&lt;/li&gt;
&lt;li&gt;上下文窗口再大也是临时的，这次会话喂进去的，下次会话一概不认。&lt;/li&gt;
&lt;li&gt;同一个问题反复问、反复贴、反复等，时间和 Token 都在重复劳动里烧掉。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Skill Seekers 的思路是换个环节解决问题：&lt;strong&gt;不要每次用的时候现喂，而是提前把文档炼成一份结构化的技能包&lt;/strong&gt;——一个主文件 &lt;code&gt;SKILL.md&lt;/code&gt; 加一组按主题拆好的参考文件，助手需要哪部分就翻哪部分，像查手册一样随用随查。&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;三条命令跑通第一个技能 → 看清 18 种来源 → GitHub 仓库深挖 → AI 增强提质 → 一次准备多处导出 → MCP 集成与项目扫描&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/yusufkaraaslan/Skill_Seekers&lt;/p&gt;
&lt;h2&gt;它是什么：给 AI 系统准备的数据层&lt;/h2&gt;
&lt;p&gt;Skill Seekers 自我定位是「AI 系统的数据层」（The data layer for AI systems）。它做的事可以拆成一条流水线：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;抓取&lt;/strong&gt;：从来源把内容抽出来。抓文档站时先检查站点有没有 &lt;code&gt;llms.txt&lt;/code&gt;，有的话直接走这条快线，速度能快一个数量级；遇到 JavaScript 单页应用，还有 sitemap、llms.txt、无头浏览器渲染三层发现机制兜底。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;分类&lt;/strong&gt;：把内容按主题整理成 API、指南、教程之类的类目，而不是一坨平铺的网页合集。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;增强&lt;/strong&gt;：用 AI 把主文件 &lt;code&gt;SKILL.md&lt;/code&gt; 写成带示例、带用法的完整技能说明，官方口径是 500 行以上，不是简单的目录拼接。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;打包&lt;/strong&gt;：按目标平台的格式打成成品包。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;上传/安装&lt;/strong&gt;：推到对应平台，或者直接装进本地的编程助手。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;还有一个容易被忽略的能力：&lt;strong&gt;自动冲突检测&lt;/strong&gt;。同一个技能可以由多个来源合并生成——比如官方文档站加 GitHub 仓库加一份 PDF 手册——不同来源说法不一致时，它会做冲突检测和两两合成（pairwise synthesis），而不是把互相打架的内容原样堆在一起让助手自己猜。&lt;/p&gt;
&lt;p&gt;生成的技能还能可选地内置一个搜索索引：加上 &lt;code&gt;--index&lt;/code&gt; 参数后，技能包里会多一个基于 SQLite FTS5 的全文索引和查询脚本，助手可以先定位到 &lt;code&gt;文件#锚点&lt;/code&gt; 再去读对应的段落，不用把几千行的大文件整个吞下去。&lt;/p&gt;
&lt;h2&gt;快速上手：三条命令&lt;/h2&gt;
&lt;p&gt;前置条件只有两个：Python 3.10 以上和 Git。安装和生成都在命令行里完成：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 安装
pip install skill-seekers

# 2. 从文档站生成技能（以 Django 文档为例）
skill-seekers create https://docs.djangoproject.com/

# 3. 打包成 Claude 技能
skill-seekers package output/django --target claude
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第三条命令跑完，&lt;code&gt;output/&lt;/code&gt; 目录里就躺着 &lt;code&gt;django-claude.zip&lt;/code&gt;，可以直接上传到 Claude 的技能库使用。不想用 API 自动上传的话，把 ZIP 拿到手手动上传也完全可以。&lt;/p&gt;
&lt;p&gt;正式开抓之前，建议先用 &lt;code&gt;detect&lt;/code&gt; 探一下路：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 只预览来源会被识别成什么类型，不生成任何东西
skill-seekers detect https://docs.djangoproject.com/ --json
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Skill Seekers 按来源类型和目标平台拆了可选依赖，装的时候按需选：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;安装命令&lt;/th&gt;
&lt;th&gt;额外获得&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;pip install skill-seekers&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;核心功能：抓取、GitHub 分析、PDF、打包&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;pip install skill-seekers[mcp]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;MCP 服务器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;pip install skill-seekers[video]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;视频转写与元数据提取&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;pip install skill-seekers[jupyter]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Jupyter Notebook 支持&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;pip install skill-seekers[notion]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Notion 页面支持&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;pip install skill-seekers[confluence]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Confluence 支持&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;pip install skill-seekers[all-llms]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;全部大模型平台&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;pip install skill-seekers[all]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;全部功能&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;拿不准装哪个，还有个向导命令 &lt;code&gt;skill-seekers-setup&lt;/code&gt; 可以交互式帮你选。&lt;/p&gt;
&lt;p&gt;:::warning
第一次跑先拿一个中小型文档站练手，别上来就对着上万页的大站全量抓取。官方给的参考耗时是：100 页以内约 5–10 分钟，100–500 页约 15–30 分钟，500–2000 页要 30–60 分钟；上万页的巨型文档集应该走流式摄入（stream）而不是普通 create。
:::&lt;/p&gt;
&lt;h2&gt;18 种来源：一张表看全&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;create&lt;/code&gt; 后面跟什么，基本就决定了它按哪条管线处理。官方支持 18 种来源，主要的列在这里：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;来源类型&lt;/th&gt;
&lt;th&gt;喂给它的东西&lt;/th&gt;
&lt;th&gt;典型命令&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;文档网站&lt;/td&gt;
&lt;td&gt;文档站 URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create https://docs.djangoproject.com/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GitHub 仓库&lt;/td&gt;
&lt;td&gt;仓库简写或 URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create facebook/react&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本地代码库&lt;/td&gt;
&lt;td&gt;本地目录路径&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create ./my-project&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;PDF&lt;/td&gt;
&lt;td&gt;PDF 文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create manual.pdf&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Word&lt;/td&gt;
&lt;td&gt;.docx 文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create report.docx&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;EPUB&lt;/td&gt;
&lt;td&gt;电子书文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create book.epub&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;PowerPoint&lt;/td&gt;
&lt;td&gt;.pptx 文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create presentation.pptx&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Jupyter&lt;/td&gt;
&lt;td&gt;.ipynb 笔记本&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create notebook.ipynb&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;OpenAPI&lt;/td&gt;
&lt;td&gt;Swagger/OpenAPI 规格文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create openapi.yaml&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本地 HTML&lt;/td&gt;
&lt;td&gt;HTML 文件或整个目录&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create page.html&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;AsciiDoc&lt;/td&gt;
&lt;td&gt;.adoc 文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create guide.adoc&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;RSS/Atom&lt;/td&gt;
&lt;td&gt;订阅源文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create feed.rss&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Man 手册页&lt;/td&gt;
&lt;td&gt;man page 文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create curl.1&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;视频&lt;/td&gt;
&lt;td&gt;YouTube、Vimeo 链接或本地文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create --video-url &amp;lt;链接&amp;gt; --name mytutorial&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Confluence&lt;/td&gt;
&lt;td&gt;空间 Key&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create --space-key TEAM --name wiki&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Notion&lt;/td&gt;
&lt;td&gt;数据库 ID&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create --database-id ... --name docs&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;聊天导出&lt;/td&gt;
&lt;td&gt;Slack/Discord 导出目录&lt;/td&gt;
&lt;td&gt;&lt;code&gt;skill-seekers create --chat-export-path ./slack-export --name team-chat&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个细节值得一提：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;视频来源有三级转写兜底：字幕 → YouTube 转写 API → 本地 Whisper；装了完整视频依赖后，还能抽帧对屏幕上的代码做 OCR，把教程视频里的代码也收进技能。&lt;/li&gt;
&lt;li&gt;多来源可以写进同一份配置合并生成一个技能，文档站、仓库、PDF、视频混着来都行，冲突检测就是为这种场景准备的。&lt;/li&gt;
&lt;li&gt;抓取结果不是一次性用品：它带文档变更检测，可以定时重新抓取并只做增量更新，文档站改版了技能不会长期停留在旧版本。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;GitHub 仓库深挖：不只是抓 README&lt;/h2&gt;
&lt;p&gt;对 GitHub 仓库和本地代码库，Skill Seekers 走的是一条单独的深度分析管线（官方称 C3.x），分三股流：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;代码流&lt;/strong&gt;：对源码做 AST 解析，识别类、函数和调用结构；内置 10 个 GoF 设计模式检测器，覆盖 9 种语言，能把仓库里实际用了哪些设计模式标出来；还会从测试代码里提炼真实用法示例——测试怎么写，示例就怎么来，比凭文档臆想的示例可靠得多。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;文档流&lt;/strong&gt;：README、&lt;code&gt;docs/&lt;/code&gt; 目录、Wiki 一并纳入。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;社区流&lt;/strong&gt;：Issue、PR 和仓库元数据（默认不再打包完整的已关闭 Issue 历史，省 Token）。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;分析深度用预设档位控制：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;预设&lt;/th&gt;
&lt;th&gt;耗时参考&lt;/th&gt;
&lt;th&gt;深度&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;quick&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;1–2 分钟&lt;/td&gt;
&lt;td&gt;表层扫一遍&lt;/td&gt;
&lt;td&gt;先快速摸个底&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;standard&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;适中&lt;/td&gt;
&lt;td&gt;均衡（默认）&lt;/td&gt;
&lt;td&gt;日常生成技能&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;comprehensive&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;最久&lt;/td&gt;
&lt;td&gt;深度穷尽&lt;/td&gt;
&lt;td&gt;长期要用的核心框架&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;pre&gt;&lt;code&gt;skill-seekers create ./my-project --preset quick          # 快速表层
skill-seekers create ./my-project --preset standard       # 默认均衡
skill-seekers create ./my-project --preset comprehensive  # 深度穷尽
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;管线还会顺带产出 AI 撰写的 how-to 指南、配置文件要点提取和架构总览。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;对仓库来说，它的价值不在于把代码复制进技能，而在于把「这个库实际怎么用、惯用什么模式」提炼成助手能直接引用的知识。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;AI 增强：给技能提质的两种通道&lt;/h2&gt;
&lt;p&gt;抓取和分类解决的是「全不全」，增强解决的是「好不好用」。所有 AI 调用都走同一条传输层，分两种模式：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;API 模式&lt;/strong&gt;：调用 Anthropic、Google Gemini、OpenAI、Moonshot/Kimi、MiniMax 等平台的 API，按量付费。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;本地模式（LOCAL）&lt;/strong&gt;：调用本机已装好的编程助手来干活，比如 Claude Code、Kimi Code、Codex、Copilot、OpenCode，甚至可以用 &lt;code&gt;--agent-cmd&lt;/code&gt; 接任意自定义命令——不花 API 的钱，用的是你现成的订阅额度。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;深度用 &lt;code&gt;--enhance-level 0-3&lt;/code&gt; 控制，0 是不增强、纯结构化整理，往上逐级加深改写和补例的力度；用哪个模型或助手则用 &lt;code&gt;--agent&lt;/code&gt; 指定：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 用 Kimi 作为增强引擎
skill-seekers create https://docs.djangoproject.com/ --agent kimi

# 用一条自定义命令作为增强引擎
skill-seekers create https://docs.djangoproject.com/ --agent-cmd &quot;my-custom-agent run&quot;

# 控制增强深度
skill-seekers create facebook/react --enhance-level 2
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;注意 API 模式下密钥的管理：密钥只放环境变量或本地配置，千万别写进要提交到仓库的配置文件里随代码一起推上去。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;一次准备，多处导出：22 个目标&lt;/h2&gt;
&lt;p&gt;抓好、增强完的技能放在 &lt;code&gt;output/&amp;lt;名字&amp;gt;&lt;/code&gt; 目录里，之后换平台只是换一条打包命令的事，不用重新抓取。这就是它说的「Prepare once, export to 22 targets」：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类别&lt;/th&gt;
&lt;th&gt;目标&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;大模型技能平台（12）&lt;/td&gt;
&lt;td&gt;Claude、Gemini、OpenAI、MiniMax、OpenCode、Kimi、DeepSeek、Qwen、OpenRouter、Together、Fireworks、Markdown&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;RAG 与向量库（8）&lt;/td&gt;
&lt;td&gt;LangChain、LlamaIndex、Haystack、Chroma、FAISS、Weaviate、Qdrant、Pinecone&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;其他（2）&lt;/td&gt;
&lt;td&gt;Atlas、IBM Bob&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;pre&gt;&lt;code&gt;skill-seekers package output/react --target claude       # Claude 技能（ZIP + YAML）
skill-seekers package output/react --target langchain    # LangChain Documents
skill-seekers package output/react --target llama-index  # LlamaIndex TextNodes
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;其中 RAG 那一列的产物是带丰富元数据的切块文档，可以直接喂给现成的检索管线——如果你已经在用 &lt;a href=&quot;/posts/ai-rag-knowledge-base/&quot;&gt;RAG 个人知识库&lt;/a&gt; 那套玩法，这就是给它批量备料的上游工具，两者是上下游关系而不是替代关系。&lt;/p&gt;
&lt;p&gt;打包之外还有两条分发路径：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 打包并直接上传到 Claude（需要 ANTHROPIC_API_KEY）
skill-seekers package output/react/ --upload

# 把技能直接装进本地的编程助手，可识别 19 种
skill-seekers install-agent output/react/ --agent cursor
skill-seekers install-agent output/react/ --agent all          # 装进所有检测到的助手
skill-seekers install-agent output/react/ --agent cursor --dry-run  # 先预演，不真装
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;像本系列前面介绍过的 &lt;a href=&quot;/posts/ai-creator-generalist/&quot;&gt;creator-generalist&lt;/a&gt; 那类现成技能包是「别人写好的手艺」，Skill Seekers 则是「自己造技能的机器」：前者解决某个具体创作领域，后者把你天天要查的任意文档变成同等形态的技能。&lt;/p&gt;
&lt;h2&gt;MCP 集成：在助手里直接造技能&lt;/h2&gt;
&lt;p&gt;装了 &lt;code&gt;[mcp]&lt;/code&gt; 依赖后，Skill Seekers 自带一个 MCP 服务器，共 40 个工具。接好之后，你不用切到终端敲命令，直接在对话里跟助手说「把 React 的技能打包并上传」就行，剩下的步骤由它调用工具完成。&lt;/p&gt;
&lt;p&gt;两种传输模式：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# stdio 模式（Claude Code、VS Code + Cline 等）
python -m skill_seekers.mcp.server_fastmcp

# HTTP 模式（Cursor、Windsurf、IntelliJ 等）
python -m skill_seekers.mcp.server_fastmcp --transport http --port 8765
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;支持的客户端包括 Claude Code、Cursor、Windsurf、VS Code + Cline 和 IntelliJ IDEA。关于 MCP 在命令行助手里的整体玩法，可以配合本系列的 &lt;a href=&quot;/posts/ai-cli-assistants/&quot;&gt;命令行里的 AI 助手&lt;/a&gt; 一起看：一个负责「助手怎么调工具」，一个负责「工具本身能造什么」。&lt;/p&gt;
&lt;h2&gt;scan：扫一个项目，配置自动生成&lt;/h2&gt;
&lt;p&gt;还有一个很对工程胃口的命令：&lt;code&gt;scan&lt;/code&gt;。把一个现有项目目录丢给它，AI 会读项目的清单文件、README、Dockerfile、CI 配置和抽样源码里的 import，然后&lt;strong&gt;按检测到的框架各生成一份配置&lt;/strong&gt;，外加一份你自己代码库的配置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;skill-seekers scan ./my-react-app --out ./configs/scanned/
# → react.json、vite.json、tailwind.json、jest.json、my-react-app-codebase.json

# 拿着生成的配置逐个生成技能
skill-seekers create ./configs/scanned/react.json
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果检测到的东西没有现成预设，它会现场生成一份新配置；退出时还可以选择把配置发布回社区注册表，给后来人复用。对于刚接手陌生项目的人，这等于先让工具把「这项目用了哪些框架」列清楚，再顺手把每个框架的文档技能都备好。&lt;/p&gt;
&lt;h2&gt;适合谁&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;重度使用 AI 编程助手的人&lt;/strong&gt;：主力框架就那么几个，一次把文档炼成技能，之后每次会话都受益，省下的是长期重复劳动。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;经常查框架文档的人&lt;/strong&gt;：与其每次开浏览器翻文档站，不如让助手在本地技能里定位到具体锚点再回答，答案还带出处。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;维护内部技术文档的团队&lt;/strong&gt;：把内部 Wiki、接口文档炼成技能，新人和助手的上下文同时解决了——但务必先确认这些文档的授权范围，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;内部文档生成的技能包不要随手对外分发&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;做 RAG 的人&lt;/strong&gt;：把它当备料机，18 种来源进、带元数据的切块出，比自己写一堆格式转换脚本省事得多。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;反过来，如果你只是偶尔问某个冷门库一两个问题，现问现查就够了，专门炼一份技能属于杀鸡用牛刀。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：create 跑到一半失败，或者抓下来的内容是空的？&lt;/strong&gt;
先跑一遍官方自检：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;skill-seekers doctor          # 诊断安装与环境
skill-seekers doctor --json   # 机器可读的诊断结果，方便贴给助手分析
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;抓空多半出在目标站本身：纯前端渲染的单页应用要靠它的三层发现机制兜底，遇到严重变形的 HTML 它有宽容解析回退；如果站点有登录墙或明确禁止抓取，那就不是工具的问题了，换官方提供的离线文档包当来源更稳妥。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：不确定一个地址会被识别成什么来源？&lt;/strong&gt;
用 &lt;code&gt;skill-seekers detect &amp;lt;地址&amp;gt; --json&lt;/code&gt; 先预览识别结果，不产生任何文件，确认无误再 create。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：文档站特别大，抓一次要等很久怎么办？&lt;/strong&gt;
先看规模：几百页以内按上面的参考耗时预留时间即可；上万页的巨型文档集改用流式摄入（stream）方式，并开启增量更新，后续文档改版只补差异，不用全量重抓。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：多来源合并时提示有冲突，该怎么处理？&lt;/strong&gt;
不要无视。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;冲突意味着不同来源对同一件事的说法不一致，直接打包等于把矛盾原样交给助手，它答错时你都不知道该信哪份。&amp;lt;/span&amp;gt;先看冲突报告，确认哪个来源是权威版本（一般以官方文档站为准、仓库代码次之），调整来源优先级或剔除过期来源后重新生成。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：生成的技能质量不满意，怎么量化判断？&lt;/strong&gt;
它自带质量评分命令，可以给技能打分并设及格线：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;skill-seekers quality output/react/ --threshold 7   # 低于阈值会明确报出来
skill-seekers quality output/react/ --json          # JSON 形式输出分数
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;分数低通常是来源本身内容稀薄或增强等级太低：换更完整的来源，或者把 &lt;code&gt;--enhance-level&lt;/code&gt; 往上调一级再生成一次对比。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：视频来源转写不准或者没字幕？&lt;/strong&gt;
转写是三级兜底：字幕、平台转写 API、本地 Whisper。装 &lt;code&gt;skill-seekers[video-full]&lt;/code&gt; 后再跑一次 &lt;code&gt;skill-seekers create --setup&lt;/code&gt;，它会按你的 GPU 自动装匹配的依赖，Whisper 这条兜底线才真正可用。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：装进助手的技能没生效？&lt;/strong&gt;
先用 &lt;code&gt;install-agent ... --dry-run&lt;/code&gt; 看它打算把文件放到哪个目录，再核对那个目录是不是当前助手实际加载技能的位置；不同助手的技能目录不同（有的是全局目录、有的是项目目录），放错层级是最常见的原因。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：配置文件改完好像没生效？&lt;/strong&gt;
跑 &lt;code&gt;skill-seekers sync-config&lt;/code&gt; 检查配置漂移，它专门用来发现配置文件和实际状态对不上的情况。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Skill Seekers 解决的是 AI 使用里最不起眼、但天天在烧钱的一个环节：&lt;strong&gt;文档喂养&lt;/strong&gt;。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;把文档站、GitHub 仓库、PDF、视频等 18 种来源，一次性炼成 &lt;code&gt;SKILL.md&lt;/code&gt; 加参考文件的结构化技能包，带冲突检测和可选的全文索引。&lt;/li&gt;
&lt;li&gt;GitHub 仓库走 AST 加设计模式检测加测试示例提炼的深挖管线，三档预设控制深度。&lt;/li&gt;
&lt;li&gt;增强可以用 API，也可以用本机现成的编程助手，不额外花钱；成品一次准备，能导出到 22 个目标。&lt;/li&gt;
&lt;li&gt;MCP 的 40 个工具让它能被助手直接调用，&lt;code&gt;scan&lt;/code&gt; 则能对着一个项目自动把所需配置全生成出来。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;一句话收尾：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;现查文档是按次付费的体力活，把文档炼成技能是一次性的投资——你查得越勤，这笔投资回本得越快。&amp;lt;/span&amp;gt;&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：AI 工具全景图与选型指南</title><link>https://www.anexns.cloudns.org/posts/ai-tools-overview/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-tools-overview/</guid><description>按对话、编程、绘图、视频、语音五大场景盘点主流 AI 工具，对比云端与本地两条路线的成本、隐私与上限，再按小白、开发者、隐私敏感、重度用户四类需求给出可直接照抄的选型路径与省钱思路。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：工具太多，到底该用哪个&lt;/h2&gt;
&lt;p&gt;这两年 AI 工具的增长速度堪比当年的手机应用：每隔几周就有一个新产品刷屏，个个都说自己最强。真到了自己掏钱、自己花时间上手的时候，问题就来了——同一个需求往往有十几个工具可选，参数表看着都差不多，试错一圈下来，订阅开了好几个，真正用顺手的没留下。&lt;/p&gt;
&lt;p&gt;选工具这件事，难点不在「哪个最强」，而在「哪个最适合你手头这件事」。聊天机器人写周报很顺手，拿去改代码就处处别扭；本地跑的小模型能力不如云端旗舰，但它不要钱、不联网、不把你的文档发给任何人。这篇是本系列的第 1 篇，不做部署、不敲命令，先把地图摊开：&lt;strong&gt;按五大场景盘点主流工具 → 对比云端与本地两条路线 → 按四类人群给选型路径 → 聊聊订阅和 API 的省钱思路 → 交代本系列后续篇目怎么读&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;先把结论放在前面：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;没有全能工具，只有场景匹配；先定场景，再定路线（云端还是本地），最后才轮到挑具体产品。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;五大场景：每个场景的主流工具长什么样&lt;/h2&gt;
&lt;h3&gt;场景一：对话聊天与写作&lt;/h3&gt;
&lt;p&gt;这是大多数人接触 AI 的入口：问答、写文案、翻译、总结长文档、头脑风暴。形态以网页和官方应用为主，背后是大语言模型（LLM）。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;ChatGPT（OpenAI）&lt;/strong&gt;：生态最全的一个，对话、联网搜索、文件分析、图像生成都集成在一个入口里，适合当「什么都先问它」的默认选项。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Claude（Anthropic）&lt;/strong&gt;：长文写作和代码解释口碑好，处理长文档、保持文风一致性是它的强项。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Gemini（Google）&lt;/strong&gt;：和 Google 自家服务结合紧，多模态能力强，适合已经在用 Google 生态的人。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;DeepSeek、Kimi 等国产模型&lt;/strong&gt;：中文语境理解好，访问门槛低，API 价格普遍比海外旗舰便宜一个量级，是很多国内开发者的默认选择。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;本地对话界面&lt;/strong&gt;：比如自建的 Open WebUI 接本地模型，界面和 ChatGPT 类似，但数据不出本机，本站自建系列里有完整部署篇：&lt;a href=&quot;/posts/selfhost-open-webui/&quot;&gt;自建 Open WebUI&lt;/a&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这一类的共同点是：&lt;strong&gt;免费档足够体验，付费档拼的是模型上限、上下文长度和高峰期稳定性&lt;/strong&gt;。日常问答和写作，任何一家的免费档都不会让你觉得「不能用」。&lt;/p&gt;
&lt;h3&gt;场景二：编程&lt;/h3&gt;
&lt;p&gt;AI 编程工具分三种形态，选错形态比选错品牌更难受：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;编辑器内置型&lt;/strong&gt;：Cursor、Windsurf 这类把 AI 做进编辑器的产品，补全、改代码、跨文件重构都在一个界面里完成，上手最快。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;编辑器插件型&lt;/strong&gt;：GitHub Copilot、&lt;a href=&quot;https://github.com/continuedev/continue&quot;&gt;Continue&lt;/a&gt; 等，装在 VS Code 里，不换工具链就能用；其中 Continue 可以接本地模型，适合想把代码留在内网的人。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;命令行型&lt;/strong&gt;：Claude Code、Aider、各类 CLI 助手，在终端里读仓库、改文件、跑测试，适合习惯命令行的开发者和自动化脚本场景。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;编程场景的选型要点不是模型榜单，而是&lt;strong&gt;它能不能看见你的整个项目&lt;/strong&gt;：只支持单文件粘贴的工具，写算法题没问题，改真实项目就抓瞎。本系列后面有专门的编程助手实战篇：&lt;a href=&quot;/posts/ai-coding-assistants/&quot;&gt;AI 编程助手实战&lt;/a&gt;。&lt;/p&gt;
&lt;h3&gt;场景三：绘图&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;云端生成&lt;/strong&gt;：Midjourney 以出图质感著称，各大聊天机器人内置的图像生成胜在方便，适合偶尔配图、不折腾参数的人。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;本地生成&lt;/strong&gt;：Stable Diffusion 生态（WebUI、ComfyUI）是本地绘图的主流，模型、插件、工作流全在自己手里，上限高，但需要一块像样的显卡，学习曲线也是五类场景里最陡的。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;绘图是「本地路线」性价比最明显的场景之一：云端按张或按月收费，本地只要显卡到位，出图边际成本几乎为零。&lt;/p&gt;
&lt;h3&gt;场景四：视频&lt;/h3&gt;
&lt;p&gt;视频生成目前是五类里最「贵」也最不稳定的一类：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;云端文生视频/图生视频&lt;/strong&gt;：各家都在快速迭代，效果惊艳的演示很多，但生成时长短、排队久、按次计费贵，适合做短素材和创意验证。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;本地路线&lt;/strong&gt;：开源视频模型对显存的要求非常苛刻，消费级显卡跑起来吃力，现阶段更适合尝鲜，不适合当生产力。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这一类的务实建议是：先用云端免费额度验证创意和分镜，确认值得投入了再考虑付费档，不要一上来就为视频工具开年费。&lt;/p&gt;
&lt;h3&gt;场景五：语音&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;语音转文字（ASR）&lt;/strong&gt;：OpenAI 的 Whisper 是开源路线的代表，本地可跑、语种多、准确率高，会议记录、字幕生成这类活儿它基本是默认答案。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;文字转语音（TTS）&lt;/strong&gt;：云端服务的音色和自然度更好，本地开源方案胜在免费和可批量，适合给视频配音、做有声内容。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;实时语音对话&lt;/strong&gt;：各家旗舰应用都在做，体验拼的是延迟，现阶段以云端为主。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;全景对比表&lt;/h3&gt;
&lt;p&gt;把五类场景的主流选择拉到一张表上，先有个整体印象：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;代表工具&lt;/th&gt;
&lt;th&gt;形态&lt;/th&gt;
&lt;th&gt;收费方式&lt;/th&gt;
&lt;th&gt;更适合谁&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;对话聊天&lt;/td&gt;
&lt;td&gt;ChatGPT / Claude / Gemini / DeepSeek&lt;/td&gt;
&lt;td&gt;云端为主&lt;/td&gt;
&lt;td&gt;免费档＋订阅制&lt;/td&gt;
&lt;td&gt;所有人，先从这里入门&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;对话聊天（本地）&lt;/td&gt;
&lt;td&gt;Open WebUI＋Ollama&lt;/td&gt;
&lt;td&gt;本地自建&lt;/td&gt;
&lt;td&gt;免费（吃硬件）&lt;/td&gt;
&lt;td&gt;隐私敏感、爱折腾的人&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;编程&lt;/td&gt;
&lt;td&gt;Cursor / Copilot / Claude Code&lt;/td&gt;
&lt;td&gt;云端模型＋本地客户端&lt;/td&gt;
&lt;td&gt;订阅制为主&lt;/td&gt;
&lt;td&gt;职业开发者&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;编程（私有化）&lt;/td&gt;
&lt;td&gt;Continue＋本地模型&lt;/td&gt;
&lt;td&gt;本地&lt;/td&gt;
&lt;td&gt;免费（吃硬件）&lt;/td&gt;
&lt;td&gt;代码不能出内网的人&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;绘图&lt;/td&gt;
&lt;td&gt;Midjourney / 各家内置生成&lt;/td&gt;
&lt;td&gt;云端&lt;/td&gt;
&lt;td&gt;订阅或按量&lt;/td&gt;
&lt;td&gt;偶尔配图的设计与运营&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;绘图（本地）&lt;/td&gt;
&lt;td&gt;Stable Diffusion / ComfyUI&lt;/td&gt;
&lt;td&gt;本地&lt;/td&gt;
&lt;td&gt;免费（吃显卡）&lt;/td&gt;
&lt;td&gt;高频出图、要可控工作流的人&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;视频&lt;/td&gt;
&lt;td&gt;各家文生视频服务&lt;/td&gt;
&lt;td&gt;云端&lt;/td&gt;
&lt;td&gt;按次/订阅，单价最高&lt;/td&gt;
&lt;td&gt;做短视频素材的创作者&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;语音转写&lt;/td&gt;
&lt;td&gt;Whisper&lt;/td&gt;
&lt;td&gt;本地/云端均可&lt;/td&gt;
&lt;td&gt;本地免费&lt;/td&gt;
&lt;td&gt;会议、字幕、播客处理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;语音合成&lt;/td&gt;
&lt;td&gt;各家 TTS 服务 / 本地开源 TTS&lt;/td&gt;
&lt;td&gt;云端为主&lt;/td&gt;
&lt;td&gt;按量或订阅&lt;/td&gt;
&lt;td&gt;配音、有声内容生产者&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;两条路线：云端 vs 本地&lt;/h2&gt;
&lt;p&gt;选完场景，第二个决策是路线。云端和本地不是谁取代谁，而是两种完全不同的成本结构。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;云端服务&lt;/th&gt;
&lt;th&gt;本地部署&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;上手门槛&lt;/td&gt;
&lt;td&gt;注册即用，零配置&lt;/td&gt;
&lt;td&gt;要装环境、配显卡、调参数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;模型上限&lt;/td&gt;
&lt;td&gt;旗舰模型，能力天花板最高&lt;/td&gt;
&lt;td&gt;受硬件限制，多为中小参数开源模型&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;成本结构&lt;/td&gt;
&lt;td&gt;订阅或按量付费，长期是持续支出&lt;/td&gt;
&lt;td&gt;一次性硬件投入，之后边际成本近零&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;隐私&lt;/td&gt;
&lt;td&gt;数据要发到服务商&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;数据全程不出本机&amp;lt;/span&amp;gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;稳定性&lt;/td&gt;
&lt;td&gt;高峰期可能排队、限流&lt;/td&gt;
&lt;td&gt;只取决于自己的机器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;可控性&lt;/td&gt;
&lt;td&gt;模型版本、规则由服务商定&lt;/td&gt;
&lt;td&gt;模型、参数、工作流全在自己手里&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;有两条经验值得单独说：&lt;/p&gt;
&lt;p&gt;第一，&lt;strong&gt;云端旗舰的能力上限是真实存在的&lt;/strong&gt;。复杂推理、超长文档、最新多模态能力，本地能跑的开源模型和云端旗舰之间确实有差距，别被「本地完全平替」的说法带偏。&lt;/p&gt;
&lt;p&gt;第二，&lt;strong&gt;本地路线的价值不在「更强」，在「更稳、更私密、更便宜」&lt;/strong&gt;。批量处理、敏感文档、离线环境、长期高频使用，这四种情况本地路线的优势会被放大。想上手本地路线，从 &lt;a href=&quot;https://github.com/ollama/ollama&quot;&gt;Ollama&lt;/a&gt; 开始是最平滑的一条路，本系列下一篇就是它：&lt;a href=&quot;/posts/ai-ollama-local-llm/&quot;&gt;Ollama 部署本地大模型&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;:::warning
本地部署最常见的误判是高估自己的显卡。下载模型之前先查清楚：模型参数量 × 量化精度决定显存占用，显存不够时要么跑不动，要么被迫退回 CPU 推理慢到没法用。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要先下几十 GB 的模型再回头发现显卡带不动&amp;lt;/span&amp;gt;，本系列的模型选型篇会把显存账算清楚。
:::&lt;/p&gt;
&lt;h2&gt;按人群给四条选型路径&lt;/h2&gt;
&lt;p&gt;道理说完，给可以直接照抄的四条路线：&lt;/p&gt;
&lt;h3&gt;路径一：小白尝鲜型&lt;/h3&gt;
&lt;p&gt;需求特征：偶尔问问题、写写文案、生成几张配图，不想折腾任何配置。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;对话：任选一家的免费档当主力，顺手哪个用哪个，不必纠结排名。&lt;/li&gt;
&lt;li&gt;绘图：用聊天机器人内置的图像生成，够用为止。&lt;/li&gt;
&lt;li&gt;编程、视频、语音：暂时不碰，等真有需求了再回来查这张地图。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这条路线的关键是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要在尝鲜期开任何年费订阅&amp;lt;/span&amp;gt;。先用免费档把需求摸清楚：你到底高频用哪个场景、免费档卡在哪里，答案清楚了再花钱。&lt;/p&gt;
&lt;h3&gt;路径二：开发者型&lt;/h3&gt;
&lt;p&gt;需求特征：写代码是主业，可能还要调 API 做自己的小工具。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;编程：编辑器内置型或 Copilot 类插件选一个当主力，命令行型作补充。&lt;/li&gt;
&lt;li&gt;对话：保留一个旗舰订阅处理复杂问题即可，不必家家都开。&lt;/li&gt;
&lt;li&gt;API：优先选文档齐全、SDK 成熟的服务商；国产模型的 API 在价格上优势明显，适合跑量。&lt;/li&gt;
&lt;li&gt;有内网要求时，走 Continue＋本地模型的私有化路线。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;路径三：隐私敏感型&lt;/h3&gt;
&lt;p&gt;需求特征：处理工作文档、客户资料、未公开的代码，数据出本机就是事故。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;对话与编程：本地路线为主，Open WebUI＋Ollama 起步，编程用 Continue 接本地模型。&lt;/li&gt;
&lt;li&gt;语音转写：Whisper 本地跑，录音文件不上传。&lt;/li&gt;
&lt;li&gt;必须用云端时，只发脱敏后的内容，并且&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把公司内部资料、密钥、未公开代码粘贴进任何云端对话框&amp;lt;/span&amp;gt;，这类泄露在真实世界里已经出过不止一次事故。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;路径四：重度用户型&lt;/h3&gt;
&lt;p&gt;需求特征：每天高频使用，或者要批量处理（批量转写、批量生成、批量调用 API）。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;算一笔总账：把订阅费、API 按量费和本地硬件的折旧放一起比，高频场景下本地路线的回本周期往往比想象中短。&lt;/li&gt;
&lt;li&gt;混合架构是常态：日常量走本地，难题和高峰走云端旗舰，两条路线互为备份。&lt;/li&gt;
&lt;li&gt;API 调用要上量之前，先把限流、重试和成本监控做起来，下一节细说。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;订阅与 API：省钱思路&lt;/h2&gt;
&lt;p&gt;AI 工具的付费分两种：&lt;strong&gt;订阅制&lt;/strong&gt;（包月，拼的是额度上限和使用体验）和 &lt;strong&gt;API 按量计费&lt;/strong&gt;（按 Token 用量付费，拼的是单价和稳定性）。两者的省钱逻辑完全不同。&lt;/p&gt;
&lt;p&gt;订阅制的要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;先月付后年付。年费折扣看着诱人，但工具迭代太快，这个月的主力下个月可能就被替代，年费锁死的是一整年的选择权。&lt;/li&gt;
&lt;li&gt;一家主力＋按需短订。复杂任务集中在哪家，就常驻哪家；别家只在有具体项目时开一个月。&lt;/li&gt;
&lt;li&gt;免费档之间也有差异，同一问题多问两家不花钱，还能交叉验证答案质量。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;API 按量的要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;分级用模型。摘要、分类、格式整理这类简单任务用小模型足够，复杂推理才上旗舰模型，成本能差一个数量级。&lt;/li&gt;
&lt;li&gt;控制上下文。每次请求把整本手册塞进去是最常见的浪费，检索后只喂相关片段。&lt;/li&gt;
&lt;li&gt;给自动化任务设预算上限。一个没设上限的循环脚本，能在一夜之间烧掉你一个月的预算，这类事故在开发者社区里屡见不鲜。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;一个简单的分级调用示意（以兼容 OpenAI 接口格式的服务为例）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ[&quot;AI_BASE_URL&quot;],   # 云端服务或本地网关的地址
    api_key=os.environ[&quot;AI_API_KEY&quot;],
)

def ask(prompt: str, hard: bool = False) -&amp;gt; str:
    # 简单任务用便宜的小模型，难题才升级到旗舰模型
    model = &quot;flagship-model&quot; if hard else &quot;small-model&quot;
    resp = client.chat.completions.create(
        model=model,
        messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: prompt}],
        temperature=0.3,
    )
    return resp.choices[0].message.content
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这套「一个接口、按难度切模型」的写法，也是后面 LiteLLM、CLIProxyAPI 两篇的出发点：工具越用越多，越需要一个统一入口来管模型和账单。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：免费档到底够不够用？&lt;/strong&gt;
对绝大多数轻量需求够用。免费档真正的限制通常是高峰期限流、上下文长度和高级功能（联网、文件分析、最新模型），而不是「不能问」。先免费跑两周，你自然知道自己卡在哪。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：开了订阅还是觉得模型变笨了，是错觉吗？&lt;/strong&gt;
不完全是错觉。服务商会调整模型版本、限流策略和系统提示词，同一款产品不同时期的手感确实会变。这也是不建议年费锁死的原因之一。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：本地模型回答质量明显不如云端，正常吗？&lt;/strong&gt;
正常。消费级显卡能流畅跑的多是中小参数模型，和云端旗舰比复杂推理、长文一致性有客观差距。本地模型的正确打开方式是处理批量、简单、隐私敏感的任务，难题留给云端。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：公司电脑上装本地模型要注意什么？&lt;/strong&gt;
先确认公司政策是否允许在办公设备上部署未经批准的软件；另外本地模型同样会把你输入的内容写进本地日志和对话记录，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;敏感数据不是「本地」就等于「合规」&amp;lt;/span&amp;gt;，该脱敏的还是要脱敏。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：API 调用偶尔超时或报错，怎么处理？&lt;/strong&gt;
按顺序查：网络连通性 → 密钥和额度是否正常 → 是否触发限流（降低并发、加指数退避重试）→ 服务商状态页。自动化脚本里务必加重试和超时，不要让单次失败拖死整个任务。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：工具更新太快，学不过来怎么办？&lt;/strong&gt;
抓不变的东西：提示词怎么写、上下文怎么组织、工作流怎么拆，这些能力在哪个工具上都通用。具体产品的操作细节，用到时再查文档，不要追着每个新版本跑。&lt;/p&gt;
&lt;h2&gt;本系列后续篇目导读&lt;/h2&gt;
&lt;p&gt;这篇是地图，后面每一篇都是落到某个具体工具或场景的实战：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;本地大模型线&lt;/strong&gt;：&lt;a href=&quot;/posts/ai-ollama-local-llm/&quot;&gt;Ollama 部署本地大模型&lt;/a&gt;、开源模型选型与显存估算、LM Studio 等桌面方案。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;编程线&lt;/strong&gt;：&lt;a href=&quot;/posts/ai-coding-assistants/&quot;&gt;AI 编程助手实战&lt;/a&gt;、Continue＋本地模型的私有化编程助手、命令行 AI 助手。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;应用线&lt;/strong&gt;：RAG 个人知识库、Dify 工作流、提示词工程实战。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;进阶线&lt;/strong&gt;：ComfyUI 绘图、Whisper＋TTS 语音实战、LiteLLM 统一网关、CLIProxyAPI 订阅转 API。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;建议的阅读顺序：先按这篇的地图确认自己的场景和路线，再跳到对应篇目动手，不必从头通读。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;选型顺序是&lt;strong&gt;场景 → 路线 → 产品&lt;/strong&gt;，反过来挑产品是大多数人踩坑的原因。&lt;/li&gt;
&lt;li&gt;五大场景里，对话和编程的生态最成熟，视频最贵也最不稳定，语音转写是本地路线最划算的场景之一。&lt;/li&gt;
&lt;li&gt;云端拼上限，本地拼隐私、稳定和长期成本，混合使用是重度用户的常态。&lt;/li&gt;
&lt;li&gt;订阅先月付、API 先分级，钱要花在已经验证过的需求上。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;下一篇进入动手环节：用 Ollama 在自己电脑上把第一个本地大模型跑起来。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：Toonflow 开源 AI 短剧漫剧创作平台</title><link>https://www.anexns.cloudns.org/posts/ai-toonflow/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-toonflow/</guid><description>用开源的 Toonflow 在一张无限画布上做 AI 短剧与漫剧：剧本与分镜编写、角色场景资产管理、图片与视频逐镜生成，桌面客户端、Docker 与服务器三种部署，模型自由接入与安全访问配置全解。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：做一条短剧，要在多少个工具之间倒素材&lt;/h2&gt;
&lt;p&gt;AI 短剧、漫剧这两年很热，但真动手做过一集的人都知道，难的往往不是某一次生成，而是&lt;strong&gt;整条流水线的衔接&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;剧本在聊天窗口里跟语言模型来回改，改完复制到文档里存着；&lt;/li&gt;
&lt;li&gt;分镜表单独躺在一个表格文件里，镜头编号和剧本段落靠人脑对齐；&lt;/li&gt;
&lt;li&gt;角色图在出图工具里生成，场景图在另一个平台生成，下载回来堆在本地文件夹里，文件名全是随机字符串；&lt;/li&gt;
&lt;li&gt;视频片段在一个个视频平台网页上逐条提交、逐条下载，等拼到一起才发现第三镜的角色脸和第一镜对不上，只能回头重抽。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;每倒一次手，资产就散落一层；项目做到一半想回头改一个镜头，先要花十分钟找素材。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Toonflow 的核心思路就一句话：把剧本、资产与视频片段全部收进同一张无限画布，让一条短剧从文字到成片不出一个工作台。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;认识 Toonflow 是什么 → 走完四步核心工作流 → 看懂画布与资产管理 → 模型怎么接 → 三种部署方式逐个装一遍 → 把服务器访问的安全口子堵上 → 对照官方成本案例估算自己的账&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/HBAI-Ltd/Toonflow-app&lt;/p&gt;
&lt;h2&gt;它是什么&lt;/h2&gt;
&lt;p&gt;Toonflow 是面向短剧、漫剧和短视频创作者的&lt;strong&gt;开源 AI 创作平台&lt;/strong&gt;，采用 MIT 许可证，可以自由部署和使用。它把剧本创作、智能分镜、角色与场景资产管理、图像生成和视频生成整合进同一张无限画布，再配上 AI Agent、可视化工作流、MCP 与插件扩展，形态上接近 LibTV、TapNow 这类画布式创作工具，但完全开源、本地部署、模型自选。&lt;/p&gt;
&lt;p&gt;几个关键信息先对齐：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;开源与许可&lt;/strong&gt;：MIT 许可证，代码托管在 GitHub（HBAI-Ltd/Toonflow-app），可以自己部署、自己改。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;多语言&lt;/strong&gt;：界面支持 21 种语言，包括简体中文、繁體中文、English、日本語等，国内创作者上手没有语言门槛。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;部署形态齐全&lt;/strong&gt;：Windows、macOS、Linux、Android 都有客户端安装包，也支持 Docker 部署和服务器裸装，项目与素材保存在自己的设备或服务器上。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;模型不绑死&lt;/strong&gt;：平台本身不生产画面，语言、图片、视频能力都来自你配置的模型——第三方 API 可以，本地 ComfyUI 和本地 LLM 也可以。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;需要先说清的一条边界：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Toonflow 是工作台，不是模型本身；成片质量的上限，取决于你接的语言、图片和视频模型。&amp;lt;/span&amp;gt;平台负责的是把流程、资产和上下文组织好，让模型每次生成时都站在同一套设定上。&lt;/p&gt;
&lt;h2&gt;核心工作流：四步走完一条短剧&lt;/h2&gt;
&lt;p&gt;官方给出的标准制作流程是四步，全部在画布上完成。&lt;/p&gt;
&lt;h3&gt;第一步：在文本节点里写剧本与分镜&lt;/h3&gt;
&lt;p&gt;新建项目后，在画布上放文本节点，把故事梗概、人物设定和镜头描述写进去。文本节点可以连接语言模型辅助创作：让模型扩写剧情、拆分集数、把一段小说改写成分镜脚本，生成结果直接落在节点里，你再逐段审阅、修改、定稿。&lt;/p&gt;
&lt;p&gt;这一步的价值在于&lt;strong&gt;分镜不再是独立文档&lt;/strong&gt;：每个镜头的文字描述就是一个节点，后面连图片、连视频都以它为源头，改剧本等于改下游所有素材的出发点，不用再回表格里对行号。&lt;/p&gt;
&lt;h3&gt;第二步：备齐角色与场景素材&lt;/h3&gt;
&lt;p&gt;素材有两条来源：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;导入参考图&lt;/strong&gt;：已有的角色设定图、场景概念图直接导入画布，作为后续生成的参考。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;图片节点生成&lt;/strong&gt;：用图片生成节点现做角色、场景和分镜图。角色建议先生成&lt;strong&gt;三视图&lt;/strong&gt;（正面、侧面、背面同框），把发型、服装、体型一次性定死，后续每个镜头都拿三视图当参考，角色才不会一集换一张脸。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;本系列里专门讲本地出图的 &lt;a href=&quot;/posts/ai-comfyui-beginner/&quot;&gt;ComfyUI 入门篇&lt;/a&gt; 可以和这里衔接：Toonflow 能直接接本地 ComfyUI 当图片后端，工作流在 ComfyUI 里调，调用在画布上点。&lt;/p&gt;
&lt;h3&gt;第三步：连参考、选模型，逐镜生成视频&lt;/h3&gt;
&lt;p&gt;把文本节点（镜头描述）和图片节点（角色、场景、分镜图）连到视频生成节点上，选好视频模型和生成模式，按镜头逐个生成片段。多参考素材一起喂给模型，是这类平台保角色一致性的主要手段：模型每一镜都看着同一组角色图和场景图在生成，而不是凭一句文字描述自由发挥。&lt;/p&gt;
&lt;p&gt;和本系列 &lt;a href=&quot;/posts/ai-muse-animated-film/&quot;&gt;Muse 动画短片流水线&lt;/a&gt; 那种「脚本分阶段跑批」的路线相比，Toonflow 是交互式的：哪一镜不满意，就在画布上单独重跑哪一镜，邻居镜头不受影响。&lt;/p&gt;
&lt;h3&gt;第四步：预览、整理、下载&lt;/h3&gt;
&lt;p&gt;生成的图片和视频片段都回到画布上，按镜头顺序排开预览。满意的片段下载到本地，再进剪辑软件拼接、配音、加字幕做后期；不满意的回到第三步重抽。画布本身就是这一集的「工程文件」，下次打开，剧本、资产、片段的对应关系原样还在。&lt;/p&gt;
&lt;h2&gt;画布与资产管理&lt;/h2&gt;
&lt;p&gt;短剧是连载生意，资产管理跟不上，第二集就开始还第一集的债。Toonflow 在画布之外给了专门的资产视图：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;资产画布&lt;/strong&gt;：角色、场景、道具集中管理，一部剧的所有设定图沉淀在一处，跨集复用，不用每集重新生成主角。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;3D 导演台&lt;/strong&gt;：生成之前先在 3D 导演台里摆机位、看构图，做镜头预演。先预演再生成，能省掉大量「抽出来才发现机位不对」的无效重试——视频生成是最贵的一环，预演省的都是真金白银。时间线与运镜怎么编排，可以配合 &lt;a href=&quot;/posts/ai-minimax-director/&quot;&gt;ComfyUI MiniMax 导演节点篇&lt;/a&gt; 的思路一起看。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;节点分组&lt;/strong&gt;：画布上的节点可以分组操作，一集一个组、一场戏一个组，画布再大也不至于乱成毛线团。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;扩展性：Agent、MCP 与插件市场&lt;/h2&gt;
&lt;p&gt;Toonflow 不只是一个固定流水线，它给自动化和二次扩展留了三层口子：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;开放的 AI Agent&lt;/strong&gt;：Agent 的提示词与工具对外开放，可以自定义 Agent 的行为，让它按你的习惯拆剧本、排分镜；同时支持 A2A 协作，外部 Agent 能和平台内的 Agent 配合干活。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;MCP 连接&lt;/strong&gt;：通过 MCP 协议连接外部工具与服务，把你已有的工具链挂进画布，而不是让平台大包大揽。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;插件市场&lt;/strong&gt;：官方提供插件市场，可以扩展新的节点类型、工具与创作能力；首次启动时平台会初始化内置插件，后续按需再装。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这三层决定了它的定位不只是「短剧生成器」，而是一个可以长出自己工作流的创作底座。&lt;/p&gt;
&lt;h2&gt;模型怎么接&lt;/h2&gt;
&lt;p&gt;模型配置在页面内完成，分三类分别接：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;语言模型&lt;/strong&gt;：负责剧本扩写、分镜拆解和 Agent 对话，接第三方 API 即可；也可以接本地 LLM，剧本不出本机。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;图片模型&lt;/strong&gt;：负责角色、场景、分镜图，第三方 API 与本地 ComfyUI 工作流都支持，通过自定义供应商适配接入已有工作流。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;视频模型&lt;/strong&gt;：负责逐镜生成片段，支持的参考素材类型、时长、分辨率和音频能力，取决于所选模型与供应商——选模型时先看清这四项再充值。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;API Key 在页面内配置，保存在本地数据目录里，不要截图外发，也不要把配置文件提交到公开仓库。&lt;/p&gt;
&lt;h2&gt;部署方式一：桌面客户端&lt;/h2&gt;
&lt;p&gt;只想在自己电脑（或手机）上用，客户端是最省事的路线，四个平台都有包，去仓库的 Releases 发布页下载对应版本：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;平台&lt;/th&gt;
&lt;th&gt;安装包&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Windows x64&lt;/td&gt;
&lt;td&gt;EXE 安装包（Setup）&lt;/td&gt;
&lt;td&gt;安装器自动检测并安装 WebView2&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Windows ARM64&lt;/td&gt;
&lt;td&gt;EXE 安装包（win-arm64）&lt;/td&gt;
&lt;td&gt;需要 .NET Framework 4.8.1，新款 Windows 11 已内置&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;macOS Apple Silicon&lt;/td&gt;
&lt;td&gt;DMG 安装包（macos-arm64）&lt;/td&gt;
&lt;td&gt;最低 macOS 14，已签名并完成 Apple 公证&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;macOS Intel&lt;/td&gt;
&lt;td&gt;DMG 安装包（macos-x64）&lt;/td&gt;
&lt;td&gt;最低 macOS 14；旧版迁移须下完整 DMG 覆盖安装&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Linux x64 / ARM64&lt;/td&gt;
&lt;td&gt;DEB 安装包&lt;/td&gt;
&lt;td&gt;Debian / Ubuntu 系，安装命令见下&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Android ARM64&lt;/td&gt;
&lt;td&gt;APK 安装包&lt;/td&gt;
&lt;td&gt;手机内置本地后端可独立运行，也可连接电脑或远程后端&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;Linux 下装 DEB 包：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd ~/Downloads
sudo apt install ./toonflow-版本号-linux-x64.deb
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;安装过程需要联网，apt 会准备 FFmpeg、curl、unzip、CA 证书等依赖，脚本还会下载固定版本的 Bun 并校验大小与 SHA-256，校验不过会直接中止，不会装一半。&lt;/p&gt;
&lt;p&gt;macOS 打开 DMG 把 &lt;code&gt;toonflow.app&lt;/code&gt; 拖进「应用程序」即可。若提示「无法验证开发者」，先去「系统设置 → 隐私与安全性」里点「仍要打开」；仍被隔离拦截时再执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo xattr -rd com.apple.quarantine /Applications/toonflow.app
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Windows 装完闪退，多半是 WebView2 运行时没装好，去微软官网手动装一遍运行时再启动。&lt;/p&gt;
&lt;h2&gt;部署方式二：Docker 一行起服务&lt;/h2&gt;
&lt;p&gt;想放到服务器上长期跑、或者多设备共用一个后端，用 Docker 最稳。仓库自带 Dockerfile 与 Compose 配置，基于 Bun 1.4.3 构建，镜像内包含 FFmpeg：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git clone https://github.com/HBAI-Ltd/Toonflow-app.git
cd Toonflow-app
docker compose up -d --build
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;首次构建会安装依赖并编译内置节点、工具、Web 与 Server，完成后访问 &lt;code&gt;http://127.0.0.1:3000&lt;/code&gt;，首次启动会初始化内置插件，并提供一个 &lt;code&gt;myProject&lt;/code&gt; 工作目录。日常运维命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose logs -f toonflow   # 看日志
docker compose stop               # 停止服务
docker compose start              # 再次启动
docker compose down               # 删除容器（保留数据卷）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;数据存放在 Docker 命名卷 &lt;code&gt;toonflowData&lt;/code&gt; 中，挂载到容器的 &lt;code&gt;/app/data/&lt;/code&gt;，配置、插件和项目文件都在里面。备份要先停服务再整体复制：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose stop
docker compose cp toonflow:/app/data ./toonflowBackup
docker compose start
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不要用 &lt;code&gt;docker compose down -v&lt;/code&gt; 停服务&amp;lt;/span&amp;gt;：&lt;code&gt;-v&lt;/code&gt; 会连命名卷一起删除，角色资产、项目文件和全部配置一并清零，且不可恢复。日常停服用 &lt;code&gt;docker compose down&lt;/code&gt;（不带 &lt;code&gt;-v&lt;/code&gt;）或 &lt;code&gt;docker compose stop&lt;/code&gt;。
:::&lt;/p&gt;
&lt;h2&gt;部署方式三：服务器裸装&lt;/h2&gt;
&lt;p&gt;不想用 Docker、直接在 Linux 服务器上跑也行，运行时是 Bun，版本按项目指定的 1.4.3 来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo apt-get update
sudo apt-get install -y git curl unzip ffmpeg

curl -fsSL https://bun.com/install | bash -s &quot;bun-v1.4.3&quot;
export PATH=&quot;$HOME/.bun/bin:$PATH&quot;
bun --version
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拉代码、装依赖、构建并启动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git clone https://github.com/HBAI-Ltd/Toonflow-app.git
cd Toonflow-app
bun install --frozen-lockfile
bun run build:server
mkdir -p data/workspaces/myProject
bun run start:server
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;看到「服务启动成功」后，服务器本机访问 &lt;code&gt;http://127.0.0.1:3000&lt;/code&gt; 即可。裸装时配置、插件与工作区默认保存在仓库的 &lt;code&gt;data/&lt;/code&gt; 目录，迁移备份时整个目录打包带走。上面的启动命令是前台运行，关终端就停；要长期运行，用 systemd 托管：工作目录设为仓库目录，启动命令写 Bun 的绝对路径加 &lt;code&gt;run start:server&lt;/code&gt;，运行用户要有该目录的读写权限。&lt;/p&gt;
&lt;h2&gt;安全：3000 端口不要裸奔公网&lt;/h2&gt;
&lt;p&gt;这一节必须单独强调。Toonflow 当前使用固定端口 &lt;code&gt;3000&lt;/code&gt;，&lt;strong&gt;业务页面与 API 没有独立登录鉴权&lt;/strong&gt;——也就是说，谁能打开这个页面，谁就能用你的项目、你的素材，以及你配置在里面的模型 API Key 额度。&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;服务器部署时，千万不要把 3000 端口直接对公网开放&amp;lt;/span&amp;gt;：无鉴权页面裸奔公网，等于把创作工作台和 API 额度一起送人。三种访问方式任选其一：防火墙或安全组只放行自己的 IP；前面套一层带认证的反向代理再对外；或者干脆不开公网端口，走 SSH 隧道本地访问。
:::&lt;/p&gt;
&lt;p&gt;个人远程使用，SSH 隧道是最省事的，在自己电脑上执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh -N -L 3000:127.0.0.1:3000 用户名@服务器地址
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;保持这条连接，浏览器打开 &lt;code&gt;http://127.0.0.1:3000&lt;/code&gt;，流量全程走加密隧道，服务器的 3000 端口完全不用对公网开放。团队共用或需要固定域名时，再上带认证的反向代理（在代理层做账号密码或单点登录），不要指望应用层帮你挡人。&lt;/p&gt;
&lt;h2&gt;成本参考：官方案例的账怎么读&lt;/h2&gt;
&lt;p&gt;官方给了一个完整作品案例，可以当估算锚点：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;项目&lt;/th&gt;
&lt;th&gt;案例记录&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;制作周期&lt;/td&gt;
&lt;td&gt;约 2 小时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;成片时长&lt;/td&gt;
&lt;td&gt;约 2 分钟&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;视频模型&lt;/td&gt;
&lt;td&gt;Seedance 2.0&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;图片模型&lt;/td&gt;
&lt;td&gt;GPT Image 2&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;语言模型&lt;/td&gt;
&lt;td&gt;Claude Opus 4.6&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;模型调用总费用&lt;/td&gt;
&lt;td&gt;约 130 元&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;其中视频&lt;/td&gt;
&lt;td&gt;约 120 元&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;其中语言&lt;/td&gt;
&lt;td&gt;约 10 元&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;其中图片&lt;/td&gt;
&lt;td&gt;不足 1 元&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这笔账有三个读法：第一，&lt;strong&gt;视频生成占了总成本的九成以上&lt;/strong&gt;，控成本就是控视频的生成次数与时长，前面说的 3D 导演台预演、逐镜小样确认再放大，都是在省这一项；第二，图片几乎不要钱，角色三视图这类资产图该多抽几张选最好的，别在这上面省；第三，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;这 130 元只是该案例在该组模型下的一次记录，不是固定价格&amp;lt;/span&amp;gt;，换模型、换分辨率、重试次数不同，账会差出几倍，自己的项目先小规模跑一集摸清单价，再决定要不要连载。&lt;/p&gt;
&lt;h2&gt;对比：画布一体化 vs 单点工具拼凑&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;Toonflow（画布式一体化平台）&lt;/th&gt;
&lt;th&gt;单点工具拼凑（聊天写剧本＋单独出图＋单独出视频网站）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;资产管理&lt;/td&gt;
&lt;td&gt;角色、场景、道具沉淀在资产画布，跨集复用&lt;/td&gt;
&lt;td&gt;文件散落在各平台下载目录与本地文件夹，靠人工归档&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;角色一致性靠什么&lt;/td&gt;
&lt;td&gt;三视图与参考图作为节点连进每个镜头，模型每镜都看着同一组参考生成&lt;/td&gt;
&lt;td&gt;靠每镜手动上传参考图或反复写描述词，漏一次就换脸&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;流程连贯度&lt;/td&gt;
&lt;td&gt;剧本节点即分镜源头，改剧本直接影响下游生成&lt;/td&gt;
&lt;td&gt;剧本、分镜表、素材三份文档人工对齐，改一处要同步三处&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;上手门槛&lt;/td&gt;
&lt;td&gt;装好平台、配好模型即可按四步流程走&lt;/td&gt;
&lt;td&gt;每个工具都要单独学，流程靠自己设计和维护&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;部署与数据&lt;/td&gt;
&lt;td&gt;开源自部署，项目、素材、API Key 都在自己设备或服务器&lt;/td&gt;
&lt;td&gt;数据分散在各平台账号里，平台关停或封号即丢失&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;成本结构&lt;/td&gt;
&lt;td&gt;平台免费，钱只花在模型调用上，模型可换可比价&lt;/td&gt;
&lt;td&gt;各平台分别订阅或充值，沉没成本分散难比较&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：Toonflow 本身收费吗？&lt;/strong&gt;
不收费。MIT 开源许可，自行部署免费使用；花钱的是你配置的第三方模型 API 调用。用本地 ComfyUI 和本地 LLM 时，成本就是自己的电费与硬件。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：Windows 客户端装完打开闪退？&lt;/strong&gt;
多半是 WebView2 运行时缺失或损坏。安装器本应自动检测安装，闪退时去微软官网手动下载 WebView2 运行时装一遍，再启动客户端。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：macOS 提示「无法验证开发者」打不开？&lt;/strong&gt;
先到「系统设置 → 隐私与安全性」找到被阻止的提示，点「仍要打开」；还不行就对放在「应用程序」里的 &lt;code&gt;toonflow.app&lt;/code&gt; 执行文中给出的 &lt;code&gt;xattr&lt;/code&gt; 命令移除隔离属性。&lt;code&gt;spctl --master-disable&lt;/code&gt; 这类全局放行是最后手段，会放宽全系统所有 App 的限制，用完记得改回。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：Docker 部署后页面打不开？&lt;/strong&gt;
先看日志定位：&lt;code&gt;docker compose logs -f toonflow&lt;/code&gt;。首次构建未完成时服务不会起，构建报错多为网络拉取依赖失败，重跑 &lt;code&gt;docker compose up -d --build&lt;/code&gt;；构建完成仍连不上，检查 3000 端口是否被其他程序占用。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：项目和素材到底存在哪，换电脑怎么搬？&lt;/strong&gt;
桌面客户端存在本地数据目录；Docker 部署在命名卷 &lt;code&gt;toonflowData&lt;/code&gt;（容器内 &lt;code&gt;/app/data/&lt;/code&gt;），按文中的备份命令整体复制；服务器裸装在仓库 &lt;code&gt;data/&lt;/code&gt; 目录，整目录打包迁移。搬完在页面里选择对应工作区即可继续。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：生成出来的视频时长、分辨率和别的案例不一样？&lt;/strong&gt;
这是模型决定的，不是平台的限制。支持的参考素材类型、时长、分辨率、音频能力都取决于所选视频模型与供应商，换模型前先看清这四项规格，再决定生成参数。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：能不能接自己已经在跑的 ComfyUI 工作流？&lt;/strong&gt;
可以。通过自定义供应商适配，把已有的 ComfyUI 工作流接成图片（或媒体）后端，画布上调用、本机出图，具体字段映射按工作流的 API 格式配置。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：Android 版能独立干活吗？&lt;/strong&gt;
可以。Android 版内置本地 Bun 后端，能独立运行；也可以从首页「设备互联」扫码或手动连接已开启共享的电脑或远程后端，在手机上操作家里电脑的项目。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Toonflow 解决的不是「能不能生成」，而是「生成出来的东西怎么组织成一部剧」：剧本、分镜、角色、场景、片段全部收进一张无限画布，资产跨集沉淀，镜头逐个可控；Agent、MCP 与插件市场让它能接进已有的工具链；桌面、Docker、服务器三种部署覆盖了从个人电脑到自有服务器的全部场景，模型自选，数据在自己手里。&lt;/p&gt;
&lt;p&gt;上手建议：先用桌面客户端或 Docker 在本地跑通四步流程，用一集短内容摸清你选的那组模型的单价与出片率；真要放到服务器上长期跑，先把访问控制做好——无鉴权的 3000 端口只走防火墙白名单、带认证的反向代理或 SSH 隧道，这一步做完，再谈连载。&lt;/p&gt;
</content:encoded></item><item><title>AI 工具应用：AI 语音实战（Whisper 转写 ＋ TTS 合成）</title><link>https://www.anexns.cloudns.org/posts/ai-voice-whisper-tts/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/ai-voice-whisper-tts/</guid><description>语音处理拆成两件事：用 Whisper 在本地把录音转成文字与字幕，再用 TTS 把文字合成回语音；含模型五档选型、faster-whisper 提速、字幕加工流水线与录音转播报的完整命令串。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先分清：语音 AI 其实是两件事&lt;/h2&gt;
&lt;p&gt;和语音打交道的 AI 工具，归根到底只做两件事。第一件是&lt;strong&gt;听懂&lt;/strong&gt;：把人说的话变成文字，业内叫 ASR（自动语音识别），会议记录、视频字幕、录音整理都是这一类。第二件是&lt;strong&gt;开口&lt;/strong&gt;：把文字读出来，叫 TTS（文本转语音），有声书、播报音频、视频配音都是这一类。这两件事技术路线完全不同，工具也基本不通用，先分清自己要的是哪一件，能少走很多弯路。&lt;/p&gt;
&lt;p&gt;这一篇的主线就是把两件事各跑通一遍，再串成一条流水线：前半篇用 OpenAI 开源的 Whisper 在本地做转写——录音不出本机、不用按分钟付费；中间讲转写稿怎么加工成字幕和摘要；后半篇讲 TTS 的几条合成路线怎么选；最后用一组命令把「一段录音 → 转写 → 摘要 → 合成播报音频」完整走一遍。本地跑模型的基本功（模型从哪来、显存怎么算）可以先看本系列的 &lt;a href=&quot;/posts/ai-ollama-local-llm/&quot;&gt;Ollama 部署本地大模型&lt;/a&gt;，语音这边是同一套思路的延续。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/openai/whisper&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;语音流水线的价值不在单点工具，而在串联：转写解决「内容从哪来」，合成解决「内容怎么回去」，中间的文本加工才是你真正能积累的部分。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;Whisper：本地转写的事实标准&lt;/h2&gt;
&lt;p&gt;Whisper 是 OpenAI 在 2022 年开源的语音识别模型，用 68 万小时带标注的音频训练，支持 99 种语言的转写，还能把任意语言直接翻译成英文。它最大的好处是&lt;strong&gt;完全离线&lt;/strong&gt;：模型下载到本地之后，录音文件不需要上传任何服务器，涉密会议、未发布的访谈素材都可以放心处理。官方仓库提供命令行工具和 Python 库两种用法，命令行开箱即用。&lt;/p&gt;
&lt;p&gt;先装好运行环境。它依赖 Python 和 FFmpeg（负责解码各种音频格式）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# Ubuntu / Debian
sudo apt update &amp;amp;&amp;amp; sudo apt install -y ffmpeg python3-pip

# 安装 Whisper 本体
pip install -U openai-whisper

# 验证安装
whisper --help
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果机器上有 NVIDIA 显卡，再装带 CUDA 的 PyTorch，转写速度能差出一个数量级：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pip install torch --index-url https://download.pytorch.org/whl/cu121
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;模型五档：体积、速度、精度怎么选&lt;/h3&gt;
&lt;p&gt;Whisper 有五个尺寸，从 tiny 到 large 不等。选型的核心就一句话：&lt;strong&gt;用你的硬件能轻松跑动的最大那一档&lt;/strong&gt;。小模型快但错字多，后期校对的时间往往比省下的转写时间还长。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;模型&lt;/th&gt;
&lt;th&gt;参数量&lt;/th&gt;
&lt;th&gt;模型体积&lt;/th&gt;
&lt;th&gt;显存需求（约）&lt;/th&gt;
&lt;th&gt;相对速度&lt;/th&gt;
&lt;th&gt;精度与适用场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;tiny&lt;/td&gt;
&lt;td&gt;39 M&lt;/td&gt;
&lt;td&gt;75 MB&lt;/td&gt;
&lt;td&gt;1 GB&lt;/td&gt;
&lt;td&gt;最快（约 32 倍速）&lt;/td&gt;
&lt;td&gt;只适合试玩，中文错字率明显偏高&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;base&lt;/td&gt;
&lt;td&gt;74 M&lt;/td&gt;
&lt;td&gt;142 MB&lt;/td&gt;
&lt;td&gt;1 GB&lt;/td&gt;
&lt;td&gt;约 16 倍速&lt;/td&gt;
&lt;td&gt;简单英文短句，中文勉强可用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;small&lt;/td&gt;
&lt;td&gt;244 M&lt;/td&gt;
&lt;td&gt;466 MB&lt;/td&gt;
&lt;td&gt;2 GB&lt;/td&gt;
&lt;td&gt;约 6 倍速&lt;/td&gt;
&lt;td&gt;中文日常对话可用，性价比起点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;medium&lt;/td&gt;
&lt;td&gt;769 M&lt;/td&gt;
&lt;td&gt;1.5 GB&lt;/td&gt;
&lt;td&gt;5 GB&lt;/td&gt;
&lt;td&gt;约 2 倍速&lt;/td&gt;
&lt;td&gt;中文准确率明显跃升，推荐主力&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;large-v3&lt;/td&gt;
&lt;td&gt;1550 M&lt;/td&gt;
&lt;td&gt;3.1 GB&lt;/td&gt;
&lt;td&gt;10 GB&lt;/td&gt;
&lt;td&gt;1 倍速（基准）&lt;/td&gt;
&lt;td&gt;精度最高，专有名词与口音处理最好&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
large-v3 精度最高，但对硬件的要求也是实打实的：没有独显、只靠 CPU 硬跑，一小时录音可能要转上几个小时。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要在低配机器上无脑上 large 档&amp;lt;/span&amp;gt;，先拿一小段真实录音分别用 medium 和 large 试转，对比错字率再定档——很多场景 medium 已经够用。
:::&lt;/p&gt;
&lt;h3&gt;命令行转写：一次跑通&lt;/h3&gt;
&lt;p&gt;最基础的用法只有一行。第一次运行时会自动下载对应模型到 &lt;code&gt;~/.cache/whisper&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 转写一段中文录音，指定模型与语言
whisper meeting.mp3 --model medium --language Chinese --output_format all --output_dir ./out
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个关键参数：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;--model&lt;/code&gt;：模型档位，默认是 turbo 以外的 small，不指定容易精度不够，建议显式写。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--language&lt;/code&gt;：指定语言能显著提升准确率并加快速度；不指定时它会拿前 30 秒音频自动猜，猜错整段全歪。中文写 &lt;code&gt;Chinese&lt;/code&gt;，英文写 &lt;code&gt;English&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--output_format&lt;/code&gt;：输出格式，可选 txt（纯文本）、srt（字幕）、vtt（网页字幕）、json（带逐词时间戳的完整结果）、tsv。可以写 &lt;code&gt;all&lt;/code&gt; 一次全出。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--task translate&lt;/code&gt;：翻译模式，把任意语言的音频&lt;strong&gt;直接转写成英文文本&lt;/strong&gt;。注意它只往英文翻，不能反向，也不能翻成中文。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;转写视频文件也一样，FFmpeg 会自动抽音轨：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;whisper lecture.mp4 --model medium --language Chinese --output_format srt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;产物 &lt;code&gt;lecture.srt&lt;/code&gt; 就是可以直接压进播放器或上传视频平台的字幕文件。&lt;/p&gt;
&lt;h3&gt;faster-whisper：同样的模型，快四倍&lt;/h3&gt;
&lt;p&gt;官方实现基于 PyTorch，够用但不算快。社区项目 faster-whisper 用 CTranslate2 引擎重新实现了推理，同等精度下速度最高约 4 倍、显存占用更低，还支持 int8 量化让 CPU 也能跑大模型。已经有大量转写任务要处理时，值得换过去：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pip install faster-whisper
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;from faster_whisper import WhisperModel

# device 与 compute_type 按硬件选：有独显用 cuda + float16，
# 纯 CPU 用 cpu + int8
model = WhisperModel(&quot;medium&quot;, device=&quot;cuda&quot;, compute_type=&quot;float16&quot;)

segments, info = model.transcribe(
    &quot;meeting.mp3&quot;,
    language=&quot;zh&quot;,
    beam_size=5,
    vad_filter=True,          # 过滤静音段，减少幻觉与空转
)

print(f&quot;检测语言：{info.language}，置信度：{info.language_probability:.2f}&quot;)
for seg in segments:
    print(f&quot;[{seg.start:&amp;gt;7.2f} -&amp;gt; {seg.end:&amp;gt;7.2f}] {seg.text}&quot;)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;其中 &lt;code&gt;vad_filter&lt;/code&gt; 很实用：录音里的长静音段是 Whisper 产生「幻觉」（凭空编句子）的主要来源，先用语音活动检测把静音切掉，转写质量和速度都会变好。&lt;/p&gt;
&lt;h2&gt;转写只是第一步：文本加工流水线&lt;/h2&gt;
&lt;p&gt;原始转写稿通常不能直接用：没有标点分段（Whisper 中文标点时有时无）、没有说话人区分、口语重复多。常见的加工有三步：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;字幕校对&lt;/strong&gt;：把 SRT 导入剪映、Aegisub 这类字幕工具，重点修三类错——人名与专有名词、同音字、断句位置。专有名词可以在转写时就用 &lt;code&gt;--initial_prompt&lt;/code&gt; 给模型递小抄，比如 &lt;code&gt;whisper a.mp3 --initial_prompt &quot;本期嘉宾：张工，讨论 Kubernetes 与 etcd&quot;&lt;/code&gt;，模型会倾向于输出这些词的正确写法。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;内容摘要&lt;/strong&gt;：把纯文本稿丢给大模型做摘要、提要点、列待办。提示词怎么写才稳定，见本系列的 &lt;a href=&quot;/posts/ai-prompt-engineering/&quot;&gt;提示词工程实战&lt;/a&gt;，会议纪要场景直接套「结论先行＋分议题＋待办带负责人」的结构即可。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;双语字幕&lt;/strong&gt;：先转写出原文字幕，再逐行翻译成目标语言，最后把两份 SRT 按时间轴合并。翻译这一步务必以行为单位、保留时间轴不动，只换文本，否则字幕会越对越错位。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把转写稿不经校对就直接当正式字幕发布&amp;lt;/span&amp;gt;。Whisper 在静音、背景音乐、多人抢话的片段上会自信地编造内容，这类「幻觉字幕」混在正常文本里极难肉眼排查，发布前至少把无声段和音乐段对应的字幕人工扫一遍。
:::&lt;/p&gt;
&lt;h2&gt;TTS 合成：把文字读出来&lt;/h2&gt;
&lt;p&gt;转写是把声音变文字，TTS 是反过来。选型时先分清三条路线：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;路线&lt;/th&gt;
&lt;th&gt;代表&lt;/th&gt;
&lt;th&gt;音质&lt;/th&gt;
&lt;th&gt;成本&lt;/th&gt;
&lt;th&gt;隐私&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;云端商业 API&lt;/td&gt;
&lt;td&gt;各大云厂商语音服务&lt;/td&gt;
&lt;td&gt;高，音色库丰富&lt;/td&gt;
&lt;td&gt;按字符付费&lt;/td&gt;
&lt;td&gt;文本要上传&lt;/td&gt;
&lt;td&gt;正式产品、对外播报&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本地开源模型&lt;/td&gt;
&lt;td&gt;ChatTTS、GPT-SoVITS 一类&lt;/td&gt;
&lt;td&gt;中到高，看模型&lt;/td&gt;
&lt;td&gt;免费，吃显存&lt;/td&gt;
&lt;td&gt;完全本地&lt;/td&gt;
&lt;td&gt;批量生成、声音克隆实验&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;轻量在线合成&lt;/td&gt;
&lt;td&gt;edge-tts&lt;/td&gt;
&lt;td&gt;中上，音色自然&lt;/td&gt;
&lt;td&gt;免费&lt;/td&gt;
&lt;td&gt;文本走微软在线接口&lt;/td&gt;
&lt;td&gt;个人播客、视频旁白、临时播报&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;个人使用最顺手的是 edge-tts：它调用微软 Edge 浏览器朗读背后的在线接口，装一个命令行工具就能用，中文音色质量相当能打：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pip install edge-tts

# 查看全部中文音色
edge-tts --list-voices | grep zh-CN

# 合成一段播报：晓晓音色，语速略放慢
edge-tts --voice zh-CN-XiaoxiaoNeural --rate=-10% \
  --text &quot;大家好，这是今天的会议摘要。&quot; --write-media brief.mp3
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;常用中文音色里，&lt;code&gt;zh-CN-XiaoxiaoNeural&lt;/code&gt;（晓晓，女声）适合通用播报，&lt;code&gt;zh-CN-YunyangNeural&lt;/code&gt;（云扬，男声）是新闻主播腔，正式场合更稳。语速用 &lt;code&gt;--rate&lt;/code&gt; 调，音调变化用 &lt;code&gt;--pitch&lt;/code&gt; 调，两个参数都建议小步试听再定。&lt;/p&gt;
&lt;p&gt;如果是给动画短片做旁白，TTS 只是其中一环——从剧本、关键帧到配音、合成的完整链路，见本系列的 &lt;a href=&quot;/posts/ai-muse-animated-film/&quot;&gt;Muse 动画短片工作流&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;选 TTS 路线只看两件事：文本能不能出本机、量有多大。量小又不敏感，轻量在线合成最省事；量大或敏感，要么本地模型，要么签正式的云端 API。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;完整实战：录音 → 转写 → 摘要 → 播报&lt;/h2&gt;
&lt;p&gt;把前面所有环节串起来。目标：一小时的会议录音 &lt;code&gt;meeting.m4a&lt;/code&gt;，最终产出一份文字纪要和一段三分钟的语音播报。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 第 0 步：统一转成 16kHz 单声道 WAV，转写更稳、更快
ffmpeg -i meeting.m4a -ar 16000 -ac 1 meeting.wav

# 第 1 步：转写，纯文本和字幕一起出
whisper meeting.wav --model medium --language Chinese \
  --output_format all --output_dir ./pipeline

# 第 2 步：把转写稿喂给本地大模型做摘要（Ollama 接口为例）
curl -s http://localhost:11434/api/generate -d &apos;{
  &quot;model&quot;: &quot;qwen3:14b&quot;,
  &quot;prompt&quot;: &quot;把下面的会议转写稿整理成纪要：先一句话结论，再按议题列要点，最后列出带负责人的待办事项。\n\n&apos;&quot;$(cat pipeline/meeting.txt)&quot;&apos;&quot;,
  &quot;stream&quot;: false
}&apos; | python3 -c &quot;import sys,json; print(json.load(sys.stdin)[&apos;response&apos;])&quot; &amp;gt; summary.txt

# 第 3 步：摘要合成播报音频
edge-tts --voice zh-CN-YunyangNeural --rate=-5% \
  --file summary.txt --write-media brief.mp3
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;跑完得到三件产物：&lt;code&gt;pipeline/meeting.srt&lt;/code&gt; 是可发布的字幕，&lt;code&gt;summary.txt&lt;/code&gt; 是文字纪要，&lt;code&gt;brief.mp3&lt;/code&gt; 是可以直接发群里、放车上听的语音版。整条流水线除 TTS 那一步调用了在线接口外，其余全部在本地完成，录音和纪要都不出机器。&lt;/p&gt;
&lt;p&gt;:::warning
声音克隆有明确的边界：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;克隆他人的声音必须取得本人同意&amp;lt;/span&amp;gt;，用克隆声音冒充本人发言、打电话、做证明材料，在多数司法辖区已经涉嫌违法，平台侧也普遍封禁。自己录自己的声音做素材、给自己的视频配音，是这类技术正当的用法。
:::&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;转写结果里出现整段重复或凭空编造的句子。&lt;/strong&gt; 这是 Whisper 的幻觉，多发生在静音、纯音乐、多人同时说话的片段。处理顺序：先开 &lt;code&gt;vad_filter&lt;/code&gt;（faster-whisper）或剪掉长静音段；把 &lt;code&gt;--condition_on_previous_text&lt;/code&gt; 关掉避免错误滚雪球；还不行就降一档模型或换 large 档对比。原始命令行版本可以加 &lt;code&gt;--no_speech_threshold 0.6&lt;/code&gt; 提高对无声段的抑制。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;中文转写全是繁体字。&lt;/strong&gt; 模型按语料分布输出，碰到偏港台语料的音频容易出繁体。两个办法：转写后用 OpenCC 一行转换 &lt;code&gt;opencc -i in.txt -o out.txt -c t2s&lt;/code&gt;；或者用 &lt;code&gt;--initial_prompt&lt;/code&gt; 给一段简体中文文本，引导输出风格。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;明明有显卡却跑得像 CPU 一样慢。&lt;/strong&gt; 先确认 PyTorch 装的是 CUDA 版本：&lt;code&gt;python3 -c &quot;import torch; print(torch.cuda.is_available())&quot;&lt;/code&gt; 返回 False 就是装成了 CPU 版，按前文的命令重装对应 CUDA 版本的 torch。另外 Whisper 命令行可以显式加 &lt;code&gt;--device cuda&lt;/code&gt; 与 &lt;code&gt;--fp16 True&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;显存不足（CUDA out of memory）。&lt;/strong&gt; 降一档模型是最直接的；用 faster-whisper 时把 &lt;code&gt;compute_type&lt;/code&gt; 改成 &lt;code&gt;int8_float16&lt;/code&gt; 或纯 &lt;code&gt;int8&lt;/code&gt;，显存能省一半左右，精度损失很小。长音频本身不怎么吃显存，吃显存的是模型档位，别被文件大小误导。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;转写准但标点和断句一塌糊涂。&lt;/strong&gt; 先换大一档模型，标点能力随模型规模明显变好；仍不理想就把纯文本稿交给大模型做「只加标点和分段、不改原文」的后处理，并在提示词里写死不许改词、不许删减，处理完抽查几段对照原文。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;edge-tts 报错或合成中断。&lt;/strong&gt; 它依赖微软的在线接口，网络抖动和接口限流都会导致失败，表现为连接错误或音频不完整。对策：长文本拆成小段逐段合成再用 FFmpeg 拼接；反复失败就换时段重试，或改走本地 TTS 模型，不要在脚本里无限重试把接口打挂。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;多人会议分不清谁在说话。&lt;/strong&gt; Whisper 本身不做说话人分离（Diarization），它只管把声音变文字。要区分发言人，用带分离能力的封装（如 WhisperX 的对齐＋分离流程）做后处理，或者录的时候就分轨——每人一个麦克风，胜过事后任何算法补救。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇把语音的两件事各跑通了一遍：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;转写（ASR）&lt;/strong&gt;：Whisper 本地离线运行，选型口诀是硬件能轻松跑动的最大档，中文主力推荐 medium 起步；量大再上 faster-whisper 提速。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;加工&lt;/strong&gt;：转写稿不是终点，字幕校对、摘要、双语化才是真正的生产力环节，其中&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;幻觉片段必须人工复核&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;合成（TTS）&lt;/strong&gt;：个人场景 edge-tts 免费够用，正式与批量场景再考虑云端 API 或本地模型。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;串联&lt;/strong&gt;：录音 → 转写 → 摘要 → 播报的四步流水线全部可以脚本化，一次搭好，反复使用。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;语音处理跑通之后，本地 AI 的感知（听、说）、思考（大模型）、行动（工具调用）就凑齐了。系列接下来的篇目会把这些能力组合进更完整的应用里。&lt;/p&gt;
</content:encoded></item><item><title>Davflare：把网盘搭在 Cloudflare R2 上，零服务器的私人云盘</title><link>https://www.anexns.cloudns.org/posts/clouddrive-davflare/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/clouddrive-davflare/</guid><description>不用 VPS、不用 Docker，把网盘直接搭在 Cloudflare 上：Davflare 用 Pages 做界面、Pages Functions 跑逻辑、R2 存文件，自带 WebDAV、分块上传、过期分享、回收站与图床，免费额度足够个人使用，附完整部署流程与避坑清单。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说主线：网盘是自建服务里最「贵」的一类，它把服务器省了&lt;/h2&gt;
&lt;p&gt;自建服务大多很轻：一台小 VPS 塞十几个容器毫无压力，唯独网盘是例外——它吃硬盘、吃带宽、吃内存，机器还得 24 小时开着。Davflare 的思路是把网盘彻底拆开：&lt;strong&gt;界面和逻辑跑在 Cloudflare Pages 上，文件本体躺在 R2 对象存储里，你名下不需要有任何一台服务器&lt;/strong&gt;。部署一次，之后没有机器要维护、没有系统要更新、没有硬盘要操心，成本结构就是 Cloudflare 的免费额度：R2 免费 10 GB 存储，Pages Functions 每天 10 万次调用，个人网盘的量级远远够用。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/fanchenggang/Davflare&lt;/p&gt;
&lt;p&gt;它该有的都有：网页文件管理、分块上传、带过期时间和提取码的分享链接、回收站、图片/视频/PDF 缩略图、全文搜索、WebDAV 服务、API Key，甚至还有给 AI 助手用的 MCP 接口。下面从架构讲起，一步步把它部署上线。&lt;/p&gt;
&lt;h2&gt;先看清架构：三块拼图，和两条边界&lt;/h2&gt;
&lt;p&gt;Davflare 没有传统意义上的后端服务器，它的组成是这样的：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;组件&lt;/th&gt;
&lt;th&gt;角色&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Cloudflare Pages&lt;/td&gt;
&lt;td&gt;网页界面&lt;/td&gt;
&lt;td&gt;静态前端部署在 Pages 上，打开域名就是文件管理器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Pages Functions&lt;/td&gt;
&lt;td&gt;接口逻辑&lt;/td&gt;
&lt;td&gt;仓库 &lt;code&gt;functions/&lt;/code&gt; 目录即 Pages 函数，处理上传、分享、WebDAV 等全部 API&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cloudflare R2&lt;/td&gt;
&lt;td&gt;文件存储&lt;/td&gt;
&lt;td&gt;所有文件存进一个 R2 存储桶，通过名为 &lt;code&gt;BUCKET&lt;/code&gt; 的绑定访问&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;R2 内的配置文件&lt;/td&gt;
&lt;td&gt;设置持久化&lt;/td&gt;
&lt;td&gt;五个功能开关等设置存在桶里 &lt;code&gt;_$flaredrive$/config.json&lt;/code&gt;，重新部署不丢失&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;没有数据库，没有常驻进程，这也是它零维护的原因。相应地，要先认清两条边界：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;容量边界&lt;/strong&gt;：R2 免费层是 10 GB。放文档、截图、工作文件中转绰绰有余；想存影音库和全家相册，请看本系列前三篇的 &lt;a href=&quot;/posts/selfhost-cloudreve/&quot;&gt;Cloudreve&lt;/a&gt;、&lt;a href=&quot;/posts/selfhost-alist/&quot;&gt;Alist&lt;/a&gt; 与 &lt;a href=&quot;/posts/selfhost-nextcloud-onlyoffice/&quot;&gt;Nextcloud&lt;/a&gt;，那是自有硬盘的活法。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;单文件边界&lt;/strong&gt;：走 WebDAV 直传时单文件别超过 100 MB，原因和应对在 WebDAV 一节细说。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;一句话定位：Davflare 是用 Cloudflare 的免费额度换掉一台常开的 VPS，换来的代价是容量和单文件大小都有明确上限。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;准备工作：账号、支付方式、一个 R2 存储桶&lt;/h2&gt;
&lt;p&gt;部署之前需要备齐三样东西：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Cloudflare 账号&lt;/strong&gt;，并且账号里要绑一张支付方式。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;R2 的开通前提就是账号有支付方式&amp;lt;/span&amp;gt;，哪怕你只用免费额度，这一步也跳不过去——这是 Cloudflare 的风控要求，不是 Davflare 的限制。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;开通 R2 并建好存储桶&lt;/strong&gt;：在 Cloudflare 控制台进入 R2，按提示开通，然后创建一个存储桶。名字随意，本文用官方 &lt;code&gt;wrangler.toml&lt;/code&gt; 的默认名 &lt;code&gt;webdav&lt;/code&gt;，后面绑定时对得上最省事。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;GitHub 账号&lt;/strong&gt;：部署走 Pages 的 Connect to Git，需要把仓库连接过去。可以直接选官方仓库，也可以先 Fork 一份到自己名下再部署——Fork 的好处是上游更新时你能自己决定何时同步，推荐 Fork。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;域名不是必需的：Pages 会给一个 &lt;code&gt;*.pages.dev&lt;/code&gt; 免费域名先用起来。想绑自己的域名，部署完成后在 Pages 项目里加 Custom domain 即可，本文最后会再提一句。&lt;/p&gt;
&lt;h2&gt;路线一（推荐）：控制台 Connect to Git 部署&lt;/h2&gt;
&lt;p&gt;整个过程不用写一行命令，在 Cloudflare 控制台里点完：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;打开 &lt;strong&gt;Workers &amp;amp; Pages → Create → Pages → Connect to Git&lt;/strong&gt;，选择 &lt;code&gt;fanchenggang/Davflare&lt;/code&gt;（或你 Fork 的那份）。&lt;/li&gt;
&lt;li&gt;构建设置照抄这一组：
&lt;ul&gt;
&lt;li&gt;Framework preset（框架预设）：&lt;strong&gt;None&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;Build command（构建命令）：&lt;code&gt;npm run build&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Build output directory（输出目录）：&lt;code&gt;build&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;点部署，等第一次构建完成。&lt;strong&gt;第一次部署注定是打不开的&lt;/strong&gt;，因为存储桶绑定和账号密码还没配——这是正常流程，不要以为部署失败了。&lt;/li&gt;
&lt;li&gt;进入这个 Pages 项目的 &lt;strong&gt;Settings → Bindings&lt;/strong&gt;，添加 R2 bucket 绑定：变量名必须填 &lt;code&gt;BUCKET&lt;/code&gt;，存储桶选刚建好的那个。&lt;/li&gt;
&lt;li&gt;在 &lt;strong&gt;Settings → Environment variables&lt;/strong&gt; 里添加两个变量（Production 环境）：
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;WEBDAV_USERNAME&lt;/code&gt;：你的登录用户名，自己定&lt;/li&gt;
&lt;li&gt;&lt;code&gt;WEBDAV_PASSWORD&lt;/code&gt;：登录密码，设一个足够强的；网页登录和 WebDAV 共用这一套账号密码&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;回到 &lt;strong&gt;Deployments&lt;/strong&gt; 页，对最新部署点 &lt;strong&gt;Retry deployment&lt;/strong&gt;，让绑定和变量生效。&lt;/li&gt;
&lt;li&gt;部署完成后打开 Pages 域名，用刚设的用户名密码登录，应该能进入文件管理器。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;第 6 步是最容易漏的一步：绑定和环境变量都是在部署之后才配的，配完必须重新部署一次才会生效。&amp;lt;/span&amp;gt;漏掉它，现象通常是页面能开但登录一直失败，或者接口直接报错，很多人会误判成密码记错了。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;strong&gt;这是 Pages 项目，不是 Workers 项目。&lt;/strong&gt; 仓库里没有 Worker 入口文件，只有 Pages 的构建输出配置。千万不要点仓库 README 旁边的「Deploy to Cloudflare Workers」按钮，也不要对它执行 &lt;code&gt;wrangler deploy&lt;/code&gt;——那条路会直接报 &amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;entry point not configured（找不到入口点）&amp;lt;/span&amp;gt;。正确的命令只有 &lt;code&gt;wrangler pages deploy&lt;/code&gt;，下一节会讲。
:::&lt;/p&gt;
&lt;h3&gt;部署后先打开自检页&lt;/h3&gt;
&lt;p&gt;登录后先访问一次 &lt;code&gt;#/setup&lt;/code&gt; 页面（设置里也有入口）。这是 Davflare 自带的体检清单，会逐项检查：R2 读写是否通、WebDAV 的 PROPFIND 是否正常、五个功能开关状态、&lt;code&gt;SITES_HOST&lt;/code&gt; 配置、MCP 的 tools/list 是否可达。全部变绿，说明这套部署是真的通了，而不是「页面能打开就算成功」。&lt;/p&gt;
&lt;h2&gt;路线二：Wrangler 命令行部署&lt;/h2&gt;
&lt;p&gt;习惯命令行的话也可以全程本地操作。先把仓库拉下来，确认 &lt;code&gt;wrangler.toml&lt;/code&gt; 里 R2 绑定的桶名和你建的一致（默认就是 &lt;code&gt;webdav&lt;/code&gt;，不一致就改 &lt;code&gt;bucket_name&lt;/code&gt;）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git clone https://github.com/fanchenggang/Davflare.git
cd Davflare
npm install
npm run build
npx wrangler pages deploy build
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;本地想先预览效果（包含 Pages Functions 的完整预览）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx wrangler pages dev build
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;CLI 部署完成后，绑定与环境变量仍然要去控制台补上（&lt;code&gt;BUCKET&lt;/code&gt;、&lt;code&gt;WEBDAV_USERNAME&lt;/code&gt;、&lt;code&gt;WEBDAV_PASSWORD&lt;/code&gt;），补完同样要重新部署一次才生效。两条路线后半段是汇合的。&lt;/p&gt;
&lt;h2&gt;环境变量速查&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;名称&lt;/th&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;必填&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;BUCKET&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;R2 绑定&lt;/td&gt;
&lt;td&gt;是&lt;/td&gt;
&lt;td&gt;指向你的存储桶，变量名写错一个字母都不行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;WEBDAV_USERNAME&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;环境变量&lt;/td&gt;
&lt;td&gt;是&lt;/td&gt;
&lt;td&gt;网页与 WebDAV 共用的登录用户名&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;WEBDAV_PASSWORD&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;环境变量&lt;/td&gt;
&lt;td&gt;是&lt;/td&gt;
&lt;td&gt;登录密码，按密钥级别对待&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;WEBDAV_PUBLIC_READ&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;环境变量&lt;/td&gt;
&lt;td&gt;否&lt;/td&gt;
&lt;td&gt;设为 &lt;code&gt;1&lt;/code&gt; 开启公开只读访问，不需要就别开&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;TRASH_RETENTION_DAYS&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;环境变量&lt;/td&gt;
&lt;td&gt;否&lt;/td&gt;
&lt;td&gt;回收站保留天数，默认 &lt;code&gt;30&lt;/code&gt;；设 &lt;code&gt;-1&lt;/code&gt; 表示不自动清理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SITES_HOST&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;环境变量&lt;/td&gt;
&lt;td&gt;否&lt;/td&gt;
&lt;td&gt;静态站点与图床的独立域名，形如 &lt;code&gt;sites.你的域名&lt;/code&gt;，需把该域名也绑到同一个 Pages 项目&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;功能导览：日常用得到的都在这儿&lt;/h2&gt;
&lt;p&gt;部署完成只是开始，Davflare 的功能密度比预想的高：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;上传下载&lt;/strong&gt;：网页端分块上传，大文件不怕中途断线；支持拖拽、文件夹管理、按名搜索；图片、视频、PDF 都有缩略图预览，媒体和 PDF 分享页是零 JS 的极简预览页，打开很快。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;分享链接&lt;/strong&gt;：可以设过期时间（或永久）、加提取码，文件夹还能打包成 zip 下载。临时给人传文件，不用再走第三方网盘的限速通道。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;回收站&lt;/strong&gt;：删错文件有后悔药，保留天数由 &lt;code&gt;TRASH_RETENTION_DAYS&lt;/code&gt; 控制。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Quick paste&lt;/strong&gt;：工具栏里粘贴一段文本就生成 &lt;code&gt;.txt&lt;/code&gt; 并给出分享链接，等于顺手自建了一个 Pastebin，传代码片段、日志、笔记很方便。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;图床&lt;/strong&gt;：在文件管理页直接 Ctrl/Cmd+V 粘贴截图就上传，自动把 &lt;code&gt;https://&amp;lt;SITES_HOST&amp;gt;/i/{id}&lt;/code&gt; 形式的直链复制到剪贴板——写博客、发论坛时贴图一步到位（需要先配好 &lt;code&gt;SITES_HOST&lt;/code&gt;）。仓库里还附带了 PicGo 插件 &lt;code&gt;picgo-plugin-davflare&lt;/code&gt;，用 PicGo 管理图床的可以接上。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;发布站点&lt;/strong&gt;：选中一个文件夹可以发布成下载页（带文件名、大小、SHA-256）、PDF 书架页或播客 RSS，内容落在 &lt;code&gt;sites/{slug}/&lt;/code&gt; 下，走 &lt;code&gt;SITES_HOST&lt;/code&gt; 对外。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;五个功能开关&lt;/h3&gt;
&lt;p&gt;设置页（&lt;code&gt;#/settings&lt;/code&gt;）里有五个持久化开关，默认全开，按需关停即可，关掉不会删已存的文件：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;开关&lt;/th&gt;
&lt;th&gt;关掉之后&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;WebDAV&lt;/td&gt;
&lt;td&gt;顶部 WebDAV 入口隐藏，&lt;code&gt;/webdav&lt;/code&gt; 返回 404，客户端无法挂载（网页管理不受影响）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MCP&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/mcp&lt;/code&gt; 返回 404，AI 助手无法接入&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;API Key&lt;/td&gt;
&lt;td&gt;密钥管理隐藏，API Key 调用返回 401；注意 MCP 靠 API Key 鉴权，这个关了 MCP 也会跟着不可用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Sites&lt;/td&gt;
&lt;td&gt;站点页隐藏，&lt;code&gt;SITES_HOST&lt;/code&gt; 下的已发布站点返回 404（文件不删）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Image host&lt;/td&gt;
&lt;td&gt;图床界面隐藏，&lt;code&gt;/i/*&lt;/code&gt; 直链返回 404（图片不删）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;只想当私人网盘用的话，把 Sites 和 Image host 关掉、攻击面立刻小一圈；&lt;code&gt;SITES_HOST&lt;/code&gt; 本身没配的话，这两个功能在基础设施层就是关的。&lt;/p&gt;
&lt;h2&gt;WebDAV 接入：把它挂到电脑和手机上&lt;/h2&gt;
&lt;p&gt;网页端之外，Davflare 的另一半价值在 WebDAV（协议完整度是 Class 1/2，地址固定为）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;https://你的域名/webdav
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;用户名、密码就是部署时设的 &lt;code&gt;WEBDAV_USERNAME&lt;/code&gt; / &lt;code&gt;WEBDAV_PASSWORD&lt;/code&gt;。常见接法：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Windows&lt;/strong&gt;：资源管理器「此电脑」右键 → 添加一个网络位置，填上面的地址和账号密码，即可当网络驱动器用。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;macOS&lt;/strong&gt;：Finder → 前往 → 连接服务器，填地址后按提示登录。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;手机&lt;/strong&gt;：iOS「文件」App 或安卓文件管理器（如质感文件、FE 文件管理器）添加 WebDAV 服务器即可。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Obsidian 同步&lt;/strong&gt;：装社区插件 Remotely Save，远程服务选 Webdav，填地址与账号密码，Auth Type 选 basic，「Depth Header Sent To Servers」保持默认的 &lt;code&gt;only supports depth=&apos;1&apos;&lt;/code&gt;，远程根目录留空（默认用仓库名）。先在一台设备同步成功，再在第二台建同名空仓库拉下来。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
WebDAV 有一条硬限制：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;通过 WebDAV 上传的单文件不要超过 100 MB，超出会被 Cloudflare 以 413 错误拦下。&amp;lt;/span&amp;gt;这是 Cloudflare 边缘对请求体的上限，不是 Davflare 能绕开的。用 Remotely Save 同步时，把它的 Skip Large Files 阈值设到 100 MB 以下；真有大文件要传，走网页端的分块上传。
:::&lt;/p&gt;
&lt;h2&gt;进阶：API Key、定时备份与 MCP&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;脚本化存取&lt;/strong&gt;：在设置里开启 API Key 并创建一把，脚本里带 &lt;code&gt;Authorization: Bearer &amp;lt;key&amp;gt;&lt;/code&gt; 或 &lt;code&gt;X-Api-Key&lt;/code&gt; 就能走开放 API 做上传、下载、同步，适合把日志、构建产物自动归档进来。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;定时备份&lt;/strong&gt;：官方有配套 CLI：&lt;code&gt;npm i -g davflare-cli&lt;/code&gt;，再 &lt;code&gt;davflare login --server https://你的域名&lt;/code&gt; 登录。设置页的「Scheduled backup」卡片会直接给出 push（本地推到网盘）或 pull（从网盘拉回本地）的 crontab 行，复制进 &lt;code&gt;crontab -e&lt;/code&gt; 即可；密钥保存在本机 &lt;code&gt;~/.config/davflare&lt;/code&gt;，不会出现在定时任务命令里。也有现成的 GitHub Actions 示例可以抄。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;给 AI 助手当工作区&lt;/strong&gt;：MCP 接口在同源的 &lt;code&gt;/mcp&lt;/code&gt;，约 25 个工具。Cursor 或 Claude Desktop 填好地址和 API Key 就能让 AI 直接在你的网盘里存文件、建分享、发布站点；设置页能一键复制/下载 &lt;code&gt;mcp.json&lt;/code&gt; 配置。仓库还附了官方 Agent Skill，可以让编程助手更熟练地调用这套接口。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;四款网盘怎么选&lt;/h2&gt;
&lt;p&gt;本系列四篇正好是四种活法，简单对照：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Cloudreve&lt;/th&gt;
&lt;th&gt;Alist&lt;/th&gt;
&lt;th&gt;Nextcloud&lt;/th&gt;
&lt;th&gt;Davflare&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;跑在哪&lt;/td&gt;
&lt;td&gt;自己的 VPS&lt;/td&gt;
&lt;td&gt;自己的 VPS&lt;/td&gt;
&lt;td&gt;自己的 VPS（最重）&lt;/td&gt;
&lt;td&gt;Cloudflare Pages，零服务器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件存哪&lt;/td&gt;
&lt;td&gt;本地盘/对象存储&lt;/td&gt;
&lt;td&gt;聚合各家网盘&lt;/td&gt;
&lt;td&gt;本地盘&lt;/td&gt;
&lt;td&gt;R2（免费 10 GB）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;强项&lt;/td&gt;
&lt;td&gt;分享与存储策略&lt;/td&gt;
&lt;td&gt;把多家网盘收拢成一个站&lt;/td&gt;
&lt;td&gt;同步＋在线文档协作&lt;/td&gt;
&lt;td&gt;零成本、零维护、分享与图床&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;WebDAV&lt;/td&gt;
&lt;td&gt;支持&lt;/td&gt;
&lt;td&gt;支持&lt;/td&gt;
&lt;td&gt;支持&lt;/td&gt;
&lt;td&gt;支持（单文件 ≤100 MB）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合&lt;/td&gt;
&lt;td&gt;长期私人文件库&lt;/td&gt;
&lt;td&gt;网盘太多想统一入口&lt;/td&gt;
&lt;td&gt;团队/家庭办公&lt;/td&gt;
&lt;td&gt;随身中转、截图分享、小文件托管&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选型口诀：文件量大、要长期保存，用自有服务器三件套；只是随身带一份随时能分享的文件，Davflare 的零成本很难被替代。两者也不冲突——很多人是 Nextcloud 管长期档案，Davflare 管临时中转。&lt;/p&gt;
&lt;h2&gt;排障清单&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;部署报 entry point not configured&lt;/strong&gt;：走错 Workers 路线了。删掉重来，用 Pages 的 Connect to Git 或 &lt;code&gt;wrangler pages deploy&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;页面能开但登录失败&lt;/strong&gt;：十有八九是配完变量没重新部署。回 Deployments 对最新部署 Retry deployment；顺带检查 &lt;code&gt;WEBDAV_USERNAME&lt;/code&gt;、&lt;code&gt;WEBDAV_PASSWORD&lt;/code&gt; 有没有填到 Production 环境。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;接口报错或文件列表为空&lt;/strong&gt;：检查 &lt;code&gt;BUCKET&lt;/code&gt; 绑定名是否一字不差、桶是否建在同一个账号下；再去 &lt;code&gt;#/setup&lt;/code&gt; 看 R2 读写检查是否变绿。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;WebDAV 返回 404&lt;/strong&gt;：设置里的 WebDAV 开关被关了，打开即可（开关状态存在 R2 配置里，重新部署不会重置）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;WebDAV 传大文件报 413&lt;/strong&gt;：单文件超 100 MB，改走网页端分块上传，或先压缩拆分。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;图床/站点页面样式错乱&lt;/strong&gt;：&lt;code&gt;SITES_HOST&lt;/code&gt; 所在域名要在 Cloudflare 里把 Caching → Browser Cache TTL 设为 &lt;strong&gt;Respect Existing Headers&lt;/strong&gt;，否则默认 4 小时缓存会改写静态资源的缓存头，页面资源容易串版本。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;R2 开通不了&lt;/strong&gt;：先给账号绑支付方式，并至少手动创建一个存储桶，Pages 绑定时才有桶可选。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Davflare 把「自建网盘」这件事压缩到了极致：一台服务器都不用，十分钟部署，之后只剩使用。它不会取代 Nextcloud 那种全家桶——10 GB 免费容量和 100 MB 的 WebDAV 单文件上限摆在那里——但作为&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;随身的文件中转站、截图图床和分享通道&amp;lt;/span&amp;gt;，它的成本是零，维护也是零。先用 &lt;code&gt;pages.dev&lt;/code&gt; 域名跑起来，觉得顺手再绑自己的域名和 &lt;code&gt;SITES_HOST&lt;/code&gt; 把图床、站点发布一并打开，就是完整的 Davflare 了。&lt;/p&gt;
</content:encoded></item><item><title>Cloudflare Access：给自建服务加登录门</title><link>https://www.anexns.cloudns.org/posts/cloudflare-access-zero-trust/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-access-zero-trust/</guid><description>自建面板别再裸奔公网：用 Zero Trust 的 Access 给后台套一层登录验证——绑域名、选身份提供商、写允许策略，再与 Tunnel 组合成不暴露源站的完整方案。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：你的后台正在被全网扫描&lt;/h2&gt;
&lt;p&gt;只要你自建过服务，下面这个场景多半不陌生：监控面板、管理后台、下载器界面、内部小工具，为了图方便直接绑个子域名挂上公网，套个 HTTPS，再设一个「足够复杂」的账号密码，心里就觉得安全了。&lt;/p&gt;
&lt;p&gt;但现实是，域名和子域名是公开信息，证书透明度日志里能查到你签过的每一个子域名。扫描器不需要知道你的服务是干什么的，它们按字典批量探测常见路径和指纹，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;只要登录页暴露在公网，就等于把大门摆在全网面前任人试钥匙&amp;lt;/span&amp;gt;。密码再复杂，也架不住三个问题：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;风险&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;弱口令与撞库&lt;/td&gt;
&lt;td&gt;很多面板的默认账号、历史弱密码会被字典和泄露库反复尝试&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;程序自身的漏洞&lt;/td&gt;
&lt;td&gt;面板类软件爆出未授权访问、登录绕过漏洞时，暴露在公网的实例首当其冲&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;没有第二道门&lt;/td&gt;
&lt;td&gt;应用的登录是唯一的防线，它一旦失效，攻击者直接面对全部功能和数据&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;传统的补救办法是 IP 白名单或者再套一层 Basic Auth，但白名单对动态 IP 的家庭宽带和手机网络极不友好，Basic Auth 又和应用自己的登录页打架，体验和维护都别扭。&lt;/p&gt;
&lt;p&gt;这一篇要讲的 Cloudflare Access，就是为了解决这个问题：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;在流量到达你的应用之前，先在 Cloudflare 边缘验明访问者的身份，不合格的请求连应用的登录页都看不到&amp;lt;/span&amp;gt;。全文主线是：开通 Zero Trust → 接好身份提供商 → 建一个 Self-hosted 应用 → 写允许策略 → 再和 Tunnel 组合成完整方案 → 最后讲排障。&lt;/p&gt;
&lt;h2&gt;Access 的思路：先验人，再谈应用&lt;/h2&gt;
&lt;p&gt;Access 属于 Cloudflare 的 Zero Trust（零信任）产品线。所谓零信任，落到这个场景里其实就一句话：不再默认「能连上这个地址的人就是可信的」，而是每一次访问都要先证明身份。&lt;/p&gt;
&lt;p&gt;套上 Access 之后，一次访问的流程变成这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;访客浏览器
  → 请求 panel.example.com
  → Cloudflare 边缘节点拦截，先检查有没有合法的 Access 会话
      ├─ 没有 → 跳转到登录页，用邮箱验证码或 Google/GitHub 验证身份
      │         验证通过 → 签发会话 Cookie，放行
      └─ 有且未过期 → 直接放行
  → 流量才被转发给你的应用（源站或 Tunnel）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里有两个关键点值得先想清楚：&lt;/p&gt;
&lt;p&gt;第一，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Access 验证的是「人」，应用验证的是「账号」，两者是两道独立的门&amp;lt;/span&amp;gt;。攻击者连第一道门都过不去，自然摸不到应用的登录接口；你正常使用时，多一次跳转登录，换来的是后台从公网扫描视野里彻底消失。&lt;/p&gt;
&lt;p&gt;第二，Access 本身不要求你的应用有任何改造。它工作在 Cloudflare 边缘层，应用该怎么跑还怎么跑，你甚至可以让应用只监听本机端口、完全没有公网入口——这正是后面要讲的和 Tunnel 的黄金组合。&lt;/p&gt;
&lt;p&gt;Access 能保护的应用类型主要有两种，本篇聚焦第一种：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;保护对象&lt;/th&gt;
&lt;th&gt;典型场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Self-hosted&lt;/td&gt;
&lt;td&gt;你自己服务器上的 Web 应用&lt;/td&gt;
&lt;td&gt;监控面板、管理后台、内部工具&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SaaS&lt;/td&gt;
&lt;td&gt;第三方 SaaS 应用的登录入口&lt;/td&gt;
&lt;td&gt;企业内部统一管控，较少用于个人场景&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;开通 Zero Trust&lt;/h2&gt;
&lt;p&gt;Access 的管理入口不在 Cloudflare 主控制台里，而是一个独立站点：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;https://one.dash.cloudflare.com/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第一次进入的流程如下：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;用你的 Cloudflare 账号登录 Zero Trust 控制台。&lt;/li&gt;
&lt;li&gt;设置一个团队名（Team name）。这个名字会成为你的登录页域名的一部分，形如 &lt;code&gt;你的团队名.cloudflareaccess.com&lt;/code&gt;，以后给应用做登录跳转就走这个地址。名字可以改，但建议一次想好，填一个简短好记的。&lt;/li&gt;
&lt;li&gt;选择计划。Zero Trust 有免费计划，对个人和小团队自建服务这个量级，免费计划的覆盖范围通常足够，具体人数上限和功能边界以官网与控制台显示为准，不要凭旧文章里的数字下结论。&lt;/li&gt;
&lt;li&gt;如果选付费计划会要求绑支付方式；只用免费计划则一般可以直接进入控制台。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;开通后你会看到 Zero Trust 的完整菜单：Access、Gateway、Tunnels 等都在这里。本篇只用到 Access 里的 Applications（应用）和 Access groups/Policies（策略）相关部分，以及 Settings 里的身份提供商配置。&lt;/p&gt;
&lt;p&gt;:::warning
团队名相当于你所有受保护应用共用的登录门牌号。不要用包含个人敏感信息的词，也不要和已有组织重名导致注册不上；先用小写字母和数字组合一次通过，省得后面改名还要重新适应新地址。
:::&lt;/p&gt;
&lt;h2&gt;身份提供商：先决定「拿什么证明你是谁」&lt;/h2&gt;
&lt;p&gt;Access 自己不存账号密码，它把「验证身份」这件事外包给身份提供商（Identity Provider，简称 IdP）。你在策略里写的「允许某个邮箱」，最终就是靠 IdP 来证明「当前浏览器背后的人，确实拥有这个邮箱对应的账号」。&lt;/p&gt;
&lt;p&gt;进入 Zero Trust 控制台的 Settings → Authentication，就能配置登录方式。常用的有三种：&lt;/p&gt;
&lt;h3&gt;一次性 PIN（One-time PIN）&lt;/h3&gt;
&lt;p&gt;这是开箱即用的方式，不需要任何配置：访客在登录页输入邮箱，Cloudflare 发一封带一次性验证码的邮件，输对验证码即完成登录。&lt;/p&gt;
&lt;p&gt;它的特点很明确：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;优点&lt;/th&gt;
&lt;th&gt;缺点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;零配置，立刻能用&lt;/td&gt;
&lt;td&gt;每次登录都要等邮件、输验证码，略繁琐&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;不依赖任何第三方账号&lt;/td&gt;
&lt;td&gt;安全性上限取决于邮箱本身的安全&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合临时给某人开访问权限&lt;/td&gt;
&lt;td&gt;邮箱收不到 Cloudflare 的信就完全登不进去&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;注意一个容易踩的点：一次性 PIN 验证的是「能收到这个邮箱的邮件」，所以策略里写某个邮箱时，用的就是这套逻辑；如果对方邮箱服务把验证邮件拦了，他会卡在登录页，这不是策略配错了。&lt;/p&gt;
&lt;h3&gt;Google 登录&lt;/h3&gt;
&lt;p&gt;在 Authentication 里添加 Google 作为登录方式后，登录页会出现「使用 Google 登录」的按钮。配置要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;一般按控制台给出的引导完成授权关联即可，个人使用通常不需要自己去 Google Cloud 里手工建 OAuth 应用，控制台会标明哪种方式。&lt;/li&gt;
&lt;li&gt;策略里写的邮箱，必须与访客登录的 Google 账号邮箱完全一致，包括是不是同一个域名下的别名地址，都按实际登录的那个主邮箱来算。&lt;/li&gt;
&lt;li&gt;如果你日常用的就是 Gmail，那把允许邮箱写成你的 Gmail 地址是最顺手的组合。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;GitHub 登录&lt;/h3&gt;
&lt;p&gt;同样在 Authentication 里添加 GitHub。配置要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;需要按控制台提示在 GitHub 侧完成 OAuth 应用的创建与回调地址填写，控制台会给出要填的回调 URL，照抄不要改。&lt;/li&gt;
&lt;li&gt;GitHub 账号里设置为公开或主邮箱的地址，才是 Access 这边能识别到的身份邮箱；你在策略里要写的，是 GitHub 账号实际对外确认的那个邮箱。&lt;/li&gt;
&lt;li&gt;适合本来就重度使用 GitHub 的人，登录动作最快。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;三种方式可以同时启用，登录页会把它们并列展示。我的建议是：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;至少保留一次性 PIN 作为兜底通道&amp;lt;/span&amp;gt;，万一某个第三方 IdP 抽风或者账号出问题，你还有一条不依赖它的路能进门——当然，前提是策略里你的邮箱在放行名单内。&lt;/p&gt;
&lt;p&gt;还有一个对应关系必须记牢：&lt;strong&gt;策略里判断的是 IdP 返回的身份信息&lt;/strong&gt;。你用 Google 登录，Access 看到的就是 Google 账号的邮箱；你用 PIN 登录，看到的就是收验证码的那个邮箱。策略里写 A 邮箱、登录时用 B 邮箱的账号，永远匹配不上，这是后面排障里最高频的一类问题。&lt;/p&gt;
&lt;h2&gt;建一个 Self-hosted 应用：全流程&lt;/h2&gt;
&lt;p&gt;身份通道准备好之后，就可以给第一个服务上门了。路径是 Zero Trust 控制台 → Access → Applications → Add an application → 选择 Self-hosted。&lt;/p&gt;
&lt;p&gt;下面以给监控面板 &lt;code&gt;panel.example.com&lt;/code&gt; 上门为例，完整走一遍。&lt;/p&gt;
&lt;h3&gt;第一步：填应用基本信息&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Application name&lt;/strong&gt;：应用名，自己看得懂即可，比如「监控面板」。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Session Duration&lt;/strong&gt;：会话时长，即登录一次之后多久不用重新验证。后面单独讲。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Application domain&lt;/strong&gt;：填你要保护的域名，这是最关键的一项：
&lt;ul&gt;
&lt;li&gt;Subdomain：&lt;code&gt;panel&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Domain：从下拉里选你的域名 &lt;code&gt;example.com&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Path：可以留空，表示保护这个子域名下的全部路径；也可以填具体路径，只保护某个子路径&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;域名这一项有个前提条件：这个域名必须已经接入你的 Cloudflare 账号，并且对应的 DNS 记录要开着橙色云朵（代理）状态，因为 Access 的拦截发生在 Cloudflare 代理链路里。如果走的是 Tunnel 发布，DNS 那边是 Tunnel 自动生成的 CNAME，同样满足条件。&lt;/p&gt;
&lt;p&gt;如果一个应用要保护多个子域名，控制台支持在同一个应用里添加多个域名条目，不必为每个子域名单独建应用。&lt;/p&gt;
&lt;h3&gt;第二步：设置会话时长&lt;/h3&gt;
&lt;p&gt;Session Duration 决定 Access 会话 Cookie 的有效期，常见档位从几分钟到一个月不等（具体以控制台提供的选项为准）。取舍很简单：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;建议&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;只有自己用的高敏感后台&lt;/td&gt;
&lt;td&gt;较短，比如几小时，换设备重登一次不费事&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;天天要开的面板&lt;/td&gt;
&lt;td&gt;一天到一周，减少反复验证的打扰&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;临时给别人开的权限&lt;/td&gt;
&lt;td&gt;配合策略单独处理，不要靠拉长会话图省事&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;注意：会话是签发给浏览器的 Cookie，时长到了就必须重新过一遍 IdP 登录。另外控制台里可以对某个应用执行撤销会话（Revoke tokens 之类的入口），怀疑 Cookie 泄露时用得上，排障一节还会提到。&lt;/p&gt;
&lt;h3&gt;第三步：登录页外观（一句带过）&lt;/h3&gt;
&lt;p&gt;应用配置里有登录页相关的选项，可以设置展示的应用名、Logo、登录页的文字说明等，让跳转过去的登录页看起来是你自己的服务而不是陌生页面。个人使用保持默认也完全没问题，这里不展开。&lt;/p&gt;
&lt;h3&gt;第四步：写策略并保存&lt;/h3&gt;
&lt;p&gt;建应用的向导最后一步就是添加策略（Policy），这也是下一节的主题。先说流程上的结论：至少要有一条 Allow 策略并把你自己加进去，应用保存后立即生效——下一节讲清策略结构，这里先记住生效是即时的，保存前务必核对名单，原因见后面的警告。&lt;/p&gt;
&lt;p&gt;保存之后立刻自测：开一个无痕窗口访问 &lt;code&gt;https://panel.example.com&lt;/code&gt;，如果跳到了 &lt;code&gt;你的团队名.cloudflareaccess.com&lt;/code&gt; 的登录页，说明门已经装上了。&lt;/p&gt;
&lt;h2&gt;策略详解：谁能进、以什么条件进&lt;/h2&gt;
&lt;p&gt;策略（Policy）是 Access 的核心。一条策略由三部分组成：策略名、动作（Action）、规则（Rules）。其中规则又分三种语义，理解这三者的区别，策略就不会写错。&lt;/p&gt;
&lt;h3&gt;动作：Allow 只是其中一种&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;动作&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Allow&lt;/td&gt;
&lt;td&gt;满足规则的人放行进入应用&lt;/td&gt;
&lt;td&gt;绝大多数场景&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Block&lt;/td&gt;
&lt;td&gt;满足规则的人显式拒绝，返回拦截页&lt;/td&gt;
&lt;td&gt;明确封禁某些来源&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Bypass&lt;/td&gt;
&lt;td&gt;满足规则的请求跳过 Access 验证直接通过&lt;/td&gt;
&lt;td&gt;给健康检查、回调接口留通道&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Service Auth&lt;/td&gt;
&lt;td&gt;给机器对机器调用发服务令牌&lt;/td&gt;
&lt;td&gt;API 程序间调用，一句带过即可&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;本节先讲 Allow，Bypass 等在后面单独说。&lt;/p&gt;
&lt;h3&gt;规则的三种语义：Include、Require、Exclude&lt;/h3&gt;
&lt;p&gt;这是整个 Access 里最容易绕晕、也最重要的一组概念：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;规则类型&lt;/th&gt;
&lt;th&gt;语义&lt;/th&gt;
&lt;th&gt;逻辑关系&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Include&lt;/td&gt;
&lt;td&gt;满足任意一条即可初步通过&lt;/td&gt;
&lt;td&gt;多条之间是「或」&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Require&lt;/td&gt;
&lt;td&gt;在 Include 通过的基础上，还必须同时满足&lt;/td&gt;
&lt;td&gt;与 Include 是「且」&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Exclude&lt;/td&gt;
&lt;td&gt;满足任意一条就直接排除&lt;/td&gt;
&lt;td&gt;一票否决&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;举个具体的例子。一条 Allow 策略这样写：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;动作：Allow
Include（满足其一即可）：
  - Emails：alice@example.com
  - Emails：bob@example.com
Require（必须同时满足）：
  - Country：China
Exclude（满足其一即排除）：
  - Emails ending in：@temp-mail.example.com
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它的实际含义是：Alice 或 Bob 可以进，但登录时所在的国家必须是中国，且邮箱不能是以那个临时邮箱域名结尾的——三层叠加起来才是最终判定。&lt;/p&gt;
&lt;h3&gt;Include 里最常用的规则类型&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;规则&lt;/th&gt;
&lt;th&gt;匹配对象&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Emails&lt;/td&gt;
&lt;td&gt;具体邮箱&lt;/td&gt;
&lt;td&gt;最精确，一个邮箱一条&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Emails ending in&lt;/td&gt;
&lt;td&gt;邮箱后缀&lt;/td&gt;
&lt;td&gt;适合放行整个公司/团队域名，如 &lt;code&gt;@example.com&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;IP ranges&lt;/td&gt;
&lt;td&gt;来源 IP 段&lt;/td&gt;
&lt;td&gt;适合固定出口 IP 的办公室、服务器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Country&lt;/td&gt;
&lt;td&gt;国家/地区&lt;/td&gt;
&lt;td&gt;附加限制，单独用意义不大&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Everyone&lt;/td&gt;
&lt;td&gt;所有人&lt;/td&gt;
&lt;td&gt;危险，只在特殊场景配合 Require 用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Login Methods&lt;/td&gt;
&lt;td&gt;使用的登录方式&lt;/td&gt;
&lt;td&gt;可限定必须用某个 IdP 登录&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;个人自建服务的最简策略，就是一条 Allow 加一条 Include → Emails → 你自己的邮箱。用 Google/GitHub 登录时，这个邮箱就是对应账号的邮箱；用 PIN 登录时，就是收验证码的邮箱，三者必须对上，前面已经强调过。&lt;/p&gt;
&lt;h3&gt;多条策略的优先级&lt;/h3&gt;
&lt;p&gt;一个应用可以挂多条策略，它们的判定有明确顺序，记住三条就够了：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;顺序&lt;/th&gt;
&lt;th&gt;规则&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;策略按列表顺序从上到下评估，控制台里可以拖动调整顺序&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;Block 和 Bypass 的优先级高于 Allow：先看有没有被显式拒绝或跳过&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;没有任何一条 Allow 命中，默认拒绝&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;实际配置时的经验法则是：把 Block 规则放前面先排除明确不要的来源，把针对性强的 Allow 放前面、宽泛的 Allow 放后面，避免宽策略把窄策略的意图盖掉。还有一个常见误解要澄清：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;策略之间不是「全部满足才放行」，而是命中任意一条 Allow 且没被 Block 拦截即可&amp;lt;/span&amp;gt;，所以每多加一条 Allow，就等于多开了一扇门，加之前先想清楚这条到底放谁进来。&lt;/p&gt;
&lt;h3&gt;用 Access Groups 复用人群&lt;/h3&gt;
&lt;p&gt;如果受保护的服务有好几个，每次都在策略里重复填同一串邮箱会很痛苦。Zero Trust 里有 Access Groups（访问组）的概念：先把一组邮箱定义成一个组，比如「我自己」「家人」「运维」，策略的 Include 里直接选这个组。以后人员有变动，只改组定义，所有引用它的应用同步生效。服务超过三个之后，强烈建议切到组管理。&lt;/p&gt;
&lt;h2&gt;黄金组合：Tunnel 发布 + Access 把门&lt;/h2&gt;
&lt;p&gt;单用 Access，已经能让公网上的登录页消失。但源站本身如果还开着公网端口、DNS 里还躺着指向源站 IP 的 A 记录，攻击者仍然可以绕过域名直连 IP 打你的服务。这时候就要请出上一篇的主角了。&lt;/p&gt;
&lt;p&gt;在 &lt;a href=&quot;/posts/cloudflare-tunnel/&quot;&gt;Cloudflare Tunnel 篇&lt;/a&gt; 里我们讲过：Tunnel 让源站主动向 Cloudflare 建立出站连接来发布服务，源站不需要开放任何入站端口，DNS 里只有一条指向隧道的 CNAME，源站 IP 根本不出现在解析结果里。&lt;/p&gt;
&lt;p&gt;两者组合之后的完整流量路径是这样的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;访客浏览器
  → panel.example.com（DNS 解析到 Tunnel 的 CNAME）
  → Cloudflare 边缘：Access 先验身份
      ├─ 未通过 → 登录页，连隧道都接触不到
      └─ 通过 → 流量进入 Tunnel
  → cloudflared 在你服务器上建立的出站隧道
  → 本机端口上的应用（只监听 localhost 也可以）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这个组合的完整性在于两头都堵死了：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;攻击面&lt;/th&gt;
&lt;th&gt;单独应对&lt;/th&gt;
&lt;th&gt;组合后的状态&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;登录页被扫描爆破&lt;/td&gt;
&lt;td&gt;Access 挡住未授权访客&lt;/td&gt;
&lt;td&gt;看不到登录页&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;源站 IP 暴露被直连&lt;/td&gt;
&lt;td&gt;Tunnel 不公布 IP、无入站端口&lt;/td&gt;
&lt;td&gt;无从直连&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;应用爆出未授权漏洞&lt;/td&gt;
&lt;td&gt;只能靠打补丁&lt;/td&gt;
&lt;td&gt;攻击者先得过 Access 这一关&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;配置顺序上，先按 Tunnel 篇把服务发布出来并确认能通，再回本篇给它建 Access 应用套上门，最后把源站防火墙上原来为这个服务开的入站规则撤掉，整个迁移就闭环了。注意 Access 应用里填的域名要和 Tunnel 发布的 Public Hostname 保持一致，就是同一个子域名。&lt;/p&gt;
&lt;h2&gt;其他策略动作：Bypass、Block 与 Service Auth&lt;/h2&gt;
&lt;p&gt;Allow 之外，另外三个动作在特定场景下很有用，分别说清。&lt;/p&gt;
&lt;h3&gt;Bypass：给机器留的侧门&lt;/h3&gt;
&lt;p&gt;有些路径天生没法过「人」的登录：监控系统对服务的健康检查、第三方平台的 Webhook 回调、某些 API 的状态探测。这些请求没有浏览器、不会输验证码，如果一刀切全拦，功能就废了。&lt;/p&gt;
&lt;p&gt;解法是为应用再加一条 Bypass 策略，规则里限定路径和来源：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;动作：Bypass
Include：
  - IP ranges：监控服务器的出口 IP
应用路径：panel.example.com/health
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;要点有二：一是 Bypass 的范围必须压到最小，路径和来源 IP 双重限定，不要给整个域名开 Bypass；二是 &amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Bypass 等于这条路径完全没有 Access 保护，它自身的安全只能靠应用或来源限制兜底&amp;lt;/span&amp;gt;，给登录接口、数据接口开 Bypass 是绝对不行的。&lt;/p&gt;
&lt;p&gt;另外提醒一句：很多面板类服务其实并不需要外部健康检查路径，你自己的可用性监控完全可以换到 Tunnel 内侧或本机去做，能不开侧门就不开。&lt;/p&gt;
&lt;h3&gt;Block：显式拒绝&lt;/h3&gt;
&lt;p&gt;Block 策略适合处理明确的恶意或无关来源，比如某个国家/地区从来不会有你的合法用户、某个 IP 段持续在探测。命中 Block 的访客会看到 Cloudflare 的拦截页面，而不是登录页，连「这里有个服务」的确认都尽量少给。Block 记得放在策略列表靠前的位置，让拒绝先行生效。&lt;/p&gt;
&lt;h3&gt;Service Auth：一句带过&lt;/h3&gt;
&lt;p&gt;如果调用方是另一个程序而不是人，Access 提供 Service Token（服务令牌）机制：给程序发一对 Client ID 与 Client Secret，请求时带在请求头里，策略动作选 Service Auth 来校验。本篇面向人的访问，就不展开了，知道有这条路即可。&lt;/p&gt;
&lt;h2&gt;保存策略前，先看完这个警告&lt;/h2&gt;
&lt;p&gt;:::warning
Access 应用保存后立即生效，配错的代价是把自己锁在门外：比如 Include 里邮箱拼错一位、用 A 账号登录却只放行了 B 邮箱、或者把唯一一条 Allow 策略误删。正确姿势是：保存前先把自己的邮箱加进 Include 并逐字核对；保存后立刻开无痕窗口实测一次登录全流程；确认能进，再去动其他设置。万一真把自己锁死了，也不是无解：回到 Zero Trust 控制台修改或暂时删除该应用的策略即可，控制台本身不经过 Access，所以永远留得住这条管理通道——但前提是你的 Cloudflare 账号本身能登录，别把账号也弄丢了。
:::&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;h3&gt;登录后无限重定向&lt;/h3&gt;
&lt;p&gt;表现：在登录页验证成功，却又被弹回登录页，如此循环，进不去应用。&lt;/p&gt;
&lt;p&gt;排查顺序：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Cookie 被拦截&lt;/strong&gt;：Access 靠 Cookie 维持会话。浏览器禁用了第三方 Cookie、装了过于激进的隐私插件、或者应用域名与登录域名之间的 Cookie 在无痕/特殊环境里被清掉，都会导致会话存不住。先换一个干净的浏览器或关掉插件复测，这是成本最低的一步。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;应用域名配置对不上&lt;/strong&gt;：检查 Access 应用里绑定的域名，是否和你实际访问的域名完全一致，包括子域名层级。访问的是 &lt;code&gt;www.panel.example.com&lt;/code&gt;、应用只绑了 &lt;code&gt;panel.example.com&lt;/code&gt;，就属于没命中这个应用。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;源站自己在跳转&lt;/strong&gt;：应用本身如果配了强制跳转（比如把 HTTP 跳 HTTPS、把根路径跳到登录路径），且跳转逻辑和 Access 的回调打架，也会形成循环。用 curl 看一下响应链，确认跳转是谁发起的。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;系统时间严重不准&lt;/strong&gt;：会话令牌带时间校验，本机时间偏差过大时令牌会被判无效，这种冷门情况在虚拟机和双系统机器上偶有发生，顺手核对一次。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;策略没命中，始终被拒绝&lt;/h3&gt;
&lt;p&gt;表现：登录流程能走完，但最后提示没有权限，或者明明把邮箱加了还是进不去。&lt;/p&gt;
&lt;p&gt;逐项对照：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;检查点&lt;/th&gt;
&lt;th&gt;常见错误&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;身份邮箱一致性&lt;/td&gt;
&lt;td&gt;登录用的 IdP 账号邮箱，与策略 Include 里写的不是同一个&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;路径匹配&lt;/td&gt;
&lt;td&gt;应用绑了 Path 时，访问路径大小写或前缀与配置不一致，路径是区分大小写的&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;策略顺序&lt;/td&gt;
&lt;td&gt;宽泛的 Block 排在 Allow 前面，先把人拒了&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;域名代理状态&lt;/td&gt;
&lt;td&gt;DNS 记录是灰色云朵（未代理），流量根本没经过 Cloudflare，Access 无从生效——但这种情况下通常是连登录页都不会出现，可作区分&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;还有个笨但有效的办法：在 Zero Trust 控制台的 Logs → Access 里查这次被拒的记录，里面会写明命中的策略和判定原因，比对着日志改策略，比盲猜快得多。&lt;/p&gt;
&lt;h3&gt;登出了还能进，或者想立刻踢掉某个会话&lt;/h3&gt;
&lt;p&gt;表现：在应用里点了退出登录，刷新一下又进去了；或者怀疑某台设备的会话不安全，想立刻作废。&lt;/p&gt;
&lt;p&gt;原因是两套会话各管各的：应用自己的退出，只清应用的会话；Access 的会话 Cookie 还在有效期内，所以回来时第一道门直接放行，看起来像「没退出」。处理办法：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;想彻底退出：在浏览器里清除该域名下的 Cookie，或者等 Access 会话到期；也可以访问团队登录域名下的登出地址来结束 Access 会话。&lt;/li&gt;
&lt;li&gt;想立刻作废某人/某设备的权限：先去策略或组里把他的邮箱移除，这能阻止他下一次重新登录；对已经签发的会话，去应用配置里执行撤销会话（Revoke），所有现存会话一并失效，合法用户重新登录一次即可。&lt;/li&gt;
&lt;li&gt;长期对策：高敏感后台把 Session Duration 设短一些，会话窗口小，残留风险自然小。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;邮件验证码收不到&lt;/h3&gt;
&lt;p&gt;用一次性 PIN 登录时收不到信，先查垃圾箱，再确认邮箱服务商是否拦截了这类系统邮件；公司邮箱尤其常见。可以换用 Google/GitHub 登录绕过，或者把发信域名加入邮箱白名单。注意这属于 IdP 侧的问题，和策略配置无关，不要去改策略。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇把 Access 从开通到排障完整走了一遍，最后收束成几条可直接执行的结论：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;自建后台的真正风险不是密码不够长，而是登录页本身暴露在公网扫描之下；Access 把验证前置到 Cloudflare 边缘，未授权者连登录页都看不到。&lt;/li&gt;
&lt;li&gt;身份由 IdP 负责：一次性 PIN 零配置适合兜底，Google 与 GitHub 登录更顺手；策略里写的邮箱必须与登录账号的邮箱严格一致。&lt;/li&gt;
&lt;li&gt;策略的语义就三层：Include 是「或」、Require 是「且」、Exclude 是一票否决；多条策略按顺序评估，Block 与 Bypass 优先于 Allow，没命中任何 Allow 默认拒绝。&lt;/li&gt;
&lt;li&gt;Access 与 Tunnel 是黄金组合：Tunnel 让源站 IP 和入站端口消失，Access 让未授权流量到不了应用，两者叠加才是完整的「不暴露源站」方案。&lt;/li&gt;
&lt;li&gt;保存策略前逐字核对自己的邮箱、保存后立刻无痕实测，是避免把自己锁在门外的最后防线；真锁死了，Zero Trust 控制台这条管理通道永远在。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;下一篇我们换个方向，讲讲怎么用 Cloudflare Pages 把静态站点也托管到这条链路上。&lt;/p&gt;
</content:encoded></item><item><title>用 API 管理 DNS 与 DDNS 动态解析</title><link>https://www.anexns.cloudns.org/posts/cloudflare-api-token-ddns/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-api-token-ddns/</guid><description>解析记录也能用脚本管：建一把最小权限的 API Token、用 curl 完成记录的增删改查，再写一个 DDNS 脚本——公网 IP 一变就自动更新记录，配上 cron 就是全自动。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;域名接入 Cloudflare、解析记录也都理顺之后，迟早会遇到一个问题：记录一多，控制台点来点去太慢；有些记录天生就该由程序维护，比如家里宽带的公网 IP 三天两头变，靠人盯着改 A 记录根本不现实。这时候就该请出 Cloudflare 的 API 了。&lt;/p&gt;
&lt;p&gt;这一篇分两条主线。前半段把 API 的基本功打牢：建一把只够用的 API Token，用 curl 把 DNS 记录的增、删、改、查四件套跑通。后半段落到最经典的实战——DDNS 动态解析：写一个 bash 脚本，发现公网 IP 变了就自动更新记录，再挂上 cron，从此不用再管它。上一篇讲记录本身的时候提到的那些字段（&lt;code&gt;proxied&lt;/code&gt;、&lt;code&gt;ttl&lt;/code&gt;、记录类型），在这一篇会全部变成 JSON 里的参数，建议先看过 &lt;a href=&quot;/posts/cloudflare-dns-records/&quot;&gt;DNS 记录详解与常见坑&lt;/a&gt; 再回来，衔接会顺很多。&lt;/p&gt;
&lt;h2&gt;为什么用 API 管 DNS&lt;/h2&gt;
&lt;p&gt;先说清楚边界，免得走偏。API 适合三类事情：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;批量操作&lt;/strong&gt;：几十上百条记录要建、要改、要迁移，控制台一条条点既慢又容易点错，脚本一次跑完，还能先导出备份再动手。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;自动化维护&lt;/strong&gt;：记录的值本身会变，DDNS 是典型；还有证书签发时的 TXT 验证记录、监控探活失败后自动切记录，都属于这类。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;给程序调用&lt;/strong&gt;：你自己的面板、脚本、CI 流程需要读写解析，API 是唯一的正经入口。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;反过来，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;控制台能点完的一次性小事，就别硬上脚本&amp;lt;/span&amp;gt;：临时改一条记录、开个代理状态，鼠标点两下比写命令快得多，还不容易出错。API 的价值在重复和自动，不在炫技。&lt;/p&gt;
&lt;p&gt;本篇用的全部是 Cloudflare API v4，基础地址固定：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;https://api.cloudflare.com/client/v4
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;所有请求都是 HTTPS 加 JSON，认证靠请求头里的令牌。先把认证这件事做对，后面全是套路。&lt;/p&gt;
&lt;h2&gt;先建对令牌：Token 与全局 API Key 的区别&lt;/h2&gt;
&lt;p&gt;Cloudflare 账户里能拿到的凭据不止一种，新手最容易踩的坑就是抓起全局 API Key 就写进脚本。先把几种凭据摆开对比：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;凭据&lt;/th&gt;
&lt;th&gt;权限范围&lt;/th&gt;
&lt;th&gt;能否按域名收敛&lt;/th&gt;
&lt;th&gt;泄露后果&lt;/th&gt;
&lt;th&gt;结论&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;API Token&lt;/td&gt;
&lt;td&gt;创建时逐项勾选，可细到单个域名的单个功能&lt;/td&gt;
&lt;td&gt;可以，只授权指定 Zone&lt;/td&gt;
&lt;td&gt;影响面被锁在授权范围内，可单独吊销&lt;/td&gt;
&lt;td&gt;脚本和程序一律用它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;全局 API Key（Global API Key）&lt;/td&gt;
&lt;td&gt;账户下全部域名、全部功能，等同账户全权&lt;/td&gt;
&lt;td&gt;不可以&lt;/td&gt;
&lt;td&gt;等于账户沦陷，能改所有域名、所有设置&lt;/td&gt;
&lt;td&gt;不要用它写脚本&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Origin CA Key&lt;/td&gt;
&lt;td&gt;只用于签发源站证书&lt;/td&gt;
&lt;td&gt;不涉及 DNS&lt;/td&gt;
&lt;td&gt;影响面小，但也管不了记录&lt;/td&gt;
&lt;td&gt;与本篇无关，别混用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;结论只有一句：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;永远用 API Token，全局 API Key 不进任何脚本&amp;lt;/span&amp;gt;。全局 API Key 在控制台「我的个人资料 → API 令牌」页面下方能看到，它和登录邮箱配对使用，权限等同你本人。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把全局 API Key 写进脚本，等于把整个 Cloudflare 账户的钥匙挂在脚本里&amp;lt;/span&amp;gt;，脚本一旦泄露到公开仓库或日志里，账户下所有域名任人改。Token 则不同：你给它多大权，它就只有多大权，泄露了吊销一把就行，不影响其他服务。&lt;/p&gt;
&lt;h2&gt;建一把最小权限的 API Token&lt;/h2&gt;
&lt;p&gt;目标：一把只允许改某一个域名的 DNS 记录、其他什么都干不了的令牌。步骤如下。&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;登录 Cloudflare 控制台，右上角头像 →「我的个人资料」→「API 令牌」→「创建令牌」。&lt;/li&gt;
&lt;li&gt;模板列表里选 &lt;strong&gt;Edit zone DNS&lt;/strong&gt;（编辑区域 DNS）这个现成模板，它预置了 &lt;code&gt;Zone - DNS - Edit&lt;/code&gt; 和 &lt;code&gt;Zone - Zone - Read&lt;/code&gt; 两项权限，正好是改记录所需，不多不少。&lt;/li&gt;
&lt;li&gt;**Zone Resources（区域资源）**这一项是关键：默认可能是全部域名，把它收敛成「Include → Specific zone → 只选你的目标域名」。这一步决定了这把令牌就算丢了，也只能祸害这一个域名。&lt;/li&gt;
&lt;li&gt;需要更严的话，再给令牌加有效期（Client IP Filtering 也可以把来源 IP 限制到你服务器的出口 IP，家宽 IP 会变就别加这一项，否则 DDNS 脚本自己会被挡在门外）。&lt;/li&gt;
&lt;li&gt;点「继续以显示摘要」→「创建令牌」。令牌字符串&lt;strong&gt;只显示这一次&lt;/strong&gt;，当场复制到安全的地方存好——密码管理器、服务器上权限收紧的配置文件，都行；关掉页面就再也看不到，只能重新生成。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::warning
令牌生成后先想好存放位置再复制。最常见的翻车是随手粘进聊天窗口、笔记软件或者提交进了 Git 仓库。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;令牌一旦进过公开仓库，就按已经泄露处理：立刻吊销重建，不要抱侥幸心理。&amp;lt;/span&amp;gt;
:::&lt;/p&gt;
&lt;h2&gt;准备工作：Zone ID、请求头与令牌验证&lt;/h2&gt;
&lt;p&gt;调用任何接口前，手里要有三样东西。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一样是 Zone ID&lt;/strong&gt;，即域名在 Cloudflare 里的唯一编号。打开控制台进入该域名的概览页，右下角「API」区域里就有 Zone ID，复制下来。也可以用 API 按域名查：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -s &quot;https://api.cloudflare.com/client/v4/zones?name=example.com&quot; \
  -H &quot;Authorization: Bearer YOUR_TOKEN&quot; \
  -H &quot;Content-Type: application/json&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第二样是请求头&lt;/strong&gt;。Token 的认证头写法固定：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Authorization: Bearer YOUR_TOKEN
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意这和全局 API Key 的老式写法（&lt;code&gt;X-Auth-Email&lt;/code&gt; 加 &lt;code&gt;X-Auth-Key&lt;/code&gt; 两个头）完全不同，本篇全程只用 Bearer 这一种。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三样是先验明令牌可用&lt;/strong&gt;。Cloudflare 提供专门的验证接口，新令牌到手先跑一遍：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -s &quot;https://api.cloudflare.com/client/v4/user/tokens/verify&quot; \
  -H &quot;Authorization: Bearer YOUR_TOKEN&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回 JSON 里 &lt;code&gt;success&lt;/code&gt; 为 &lt;code&gt;true&lt;/code&gt;、&lt;code&gt;result.status&lt;/code&gt; 为 &lt;code&gt;active&lt;/code&gt;，说明令牌有效。下面所有命令里，把 &lt;code&gt;YOUR_TOKEN&lt;/code&gt; 换成你的令牌、&lt;code&gt;ZONE_ID&lt;/code&gt; 换成你的 Zone ID。为了后面命令简洁，先在终端里设两个变量：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;export CF_TOKEN=&quot;YOUR_TOKEN&quot;
export CF_ZONE=&quot;ZONE_ID&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;curl 四件套：记录的增删改查&lt;/h2&gt;
&lt;p&gt;DNS 记录的接口路径是 &lt;code&gt;/zones/{zone_id}/dns_records&lt;/code&gt;，单条记录再拼上记录 ID。返回 JSON 的结构统一：&lt;code&gt;success&lt;/code&gt; 表示成败，&lt;code&gt;errors&lt;/code&gt; 数组放错误信息，&lt;code&gt;result&lt;/code&gt; 是数据本体。每条记录的关键字段先认识一下：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;id&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;记录的唯一 ID，改和删都要靠它定位&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;name&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;完整主机名，如 &lt;code&gt;home.example.com&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;type&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;记录类型，如 A、AAAA、CNAME、TXT&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;content&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;记录的值，A 记录就是 IP 地址&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;proxied&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;是否走 Cloudflare 代理（橙云），&lt;code&gt;true&lt;/code&gt; / &lt;code&gt;false&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ttl&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;生存时间，&lt;code&gt;1&lt;/code&gt; 表示自动；开了代理时实际由 Cloudflare 接管&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;comment&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;备注，可选，写给人看的&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;查：列出记录&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;curl -s &quot;https://api.cloudflare.com/client/v4/zones/$CF_ZONE/dns_records&quot; \
  -H &quot;Authorization: Bearer $CF_TOKEN&quot; | jq
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回的 &lt;code&gt;result&lt;/code&gt; 是一个数组，域名下全部记录都在里面。实际用的时候要按条件筛，比如只看某一条 A 记录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -s &quot;https://api.cloudflare.com/client/v4/zones/$CF_ZONE/dns_records?type=A&amp;amp;name=home.example.com&quot; \
  -H &quot;Authorization: Bearer $CF_TOKEN&quot; | jq &apos;.result[0] | {id, name, type, content, proxied, ttl}&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;jq&lt;/code&gt; 在这里是刚需：原始 JSON 又长又挤，提取出 &lt;code&gt;id&lt;/code&gt; 和 &lt;code&gt;content&lt;/code&gt; 才能接着往下用——DDNS 脚本读的正是这两个字段。&lt;/p&gt;
&lt;h3&gt;增：新建记录&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;curl -s -X POST &quot;https://api.cloudflare.com/client/v4/zones/$CF_ZONE/dns_records&quot; \
  -H &quot;Authorization: Bearer $CF_TOKEN&quot; \
  -H &quot;Content-Type: application/json&quot; \
  -d &apos;{
    &quot;type&quot;: &quot;A&quot;,
    &quot;name&quot;: &quot;home&quot;,
    &quot;content&quot;: &quot;203.0.113.10&quot;,
    &quot;ttl&quot;: 1,
    &quot;proxied&quot;: false,
    &quot;comment&quot;: &quot;DDNS 家宽入口&quot;
  }&apos; | jq
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个参数说明：&lt;code&gt;name&lt;/code&gt; 可以只写子域名前缀（&lt;code&gt;home&lt;/code&gt;），也可以写全名，效果一样；&lt;code&gt;ttl&lt;/code&gt; 传 &lt;code&gt;1&lt;/code&gt; 是自动；DDNS 用的记录建议 &lt;code&gt;proxied&lt;/code&gt; 设为 &lt;code&gt;false&lt;/code&gt;（灰云直连），原因后面排障部分会讲——开了代理后，从外面查到的就不是你的真实 IP 了。创建成功后，返回的 &lt;code&gt;result.id&lt;/code&gt; 就是这条记录的 ID，记下来，改和删都用它。&lt;/p&gt;
&lt;h3&gt;改：更新记录&lt;/h3&gt;
&lt;p&gt;全量更新用 PUT，请求体要带上记录的完整定义；只改个别字段用 PATCH。DDNS 只换 IP，用 PATCH 最干净：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -s -X PATCH &quot;https://api.cloudflare.com/client/v4/zones/$CF_ZONE/dns_records/RECORD_ID&quot; \
  -H &quot;Authorization: Bearer $CF_TOKEN&quot; \
  -H &quot;Content-Type: application/json&quot; \
  -d &apos;{&quot;content&quot;: &quot;203.0.113.20&quot;}&apos; | jq
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意一个细节：如果这条记录是经控制台或脚本以 PUT 方式整体维护的，用 PUT 时漏写某个字段，可能把该字段重置成默认值。所以日常脚本里优先 PATCH 做局部修改，PUT 留给「整条记录重新定义」的场景。&lt;/p&gt;
&lt;h3&gt;删：删除记录&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;curl -s -X DELETE &quot;https://api.cloudflare.com/client/v4/zones/$CF_ZONE/dns_records/RECORD_ID&quot; \
  -H &quot;Authorization: Bearer $CF_TOKEN&quot; | jq
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;删除没有二次确认，接口返回成功就是真删了。批量清理前先用 GET 把整域记录导出来存一份 JSON 当备份，这是能后悔的唯一办法。&lt;/p&gt;
&lt;p&gt;四件套到此齐了。把它们串起来，就是 DDNS。&lt;/p&gt;
&lt;h2&gt;DDNS 实战：IP 一变就自动更新&lt;/h2&gt;
&lt;h3&gt;需求与思路&lt;/h3&gt;
&lt;p&gt;家宽、4G 路由、没有固定公网 IP 的小服务器，都有同一个麻烦：运营商隔段时间就换一次公网 IP，&lt;code&gt;home.example.com&lt;/code&gt; 指过去就成了空门牌。DDNS（动态 DNS）干的就是一件事：周期性检查当前公网 IP，发现和解析记录不一致，就把记录改过来。&lt;/p&gt;
&lt;p&gt;脚本逻辑拆成四步，一步都不多余：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;查当前公网 IP（问一个外部服务「我从外面看是哪个 IP」）。&lt;/li&gt;
&lt;li&gt;用 GET 读 Cloudflare 里现有记录的 &lt;code&gt;content&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;两个 IP 相同 → 什么都不做，直接退出。&lt;/li&gt;
&lt;li&gt;不同 → 用 PATCH 更新记录，并把这次变更写进日志。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;第 3 步的「相同就退出」非常重要：没变化就不发更新请求，既省调用次数，也避免日志被无意义的「更新成功」刷满，更避免频繁写操作触发不必要的传播动作。&lt;/p&gt;
&lt;h3&gt;完整脚本&lt;/h3&gt;
&lt;p&gt;在跑脚本的机器上（家里的路由器、旁挂的小主机、NAS 都行，只要能联网、能跑 bash）建一个脚本，比如 &lt;code&gt;/opt/scripts/cf-ddns.sh&lt;/code&gt;。查公网 IP 的服务有好几个，选一个稳定的即可；Cloudflare 自家就提供了一个专门的端点 &lt;code&gt;https://www.cloudflare.com/cdn-cgi/trace&lt;/code&gt;，返回里有一行 &lt;code&gt;ip=&lt;/code&gt;，顺手还能校验出口，本篇就用它：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/usr/bin/env bash
set -euo pipefail

# ===== 配置区 =====
CF_TOKEN_FILE=&quot;/etc/cf-ddns/token&quot;
CF_ZONE=&quot;ZONE_ID&quot;
CF_NAME=&quot;home.example.com&quot;
CF_TYPE=&quot;A&quot;
LOG_FILE=&quot;/var/log/cf-ddns.log&quot;

CF_TOKEN=&quot;$(cat &quot;$CF_TOKEN_FILE&quot;)&quot;
API=&quot;https://api.cloudflare.com/client/v4&quot;

log() { echo &quot;$(date &apos;+%F %T&apos;) $*&quot; &amp;gt;&amp;gt; &quot;$LOG_FILE&quot;; }

# 第一步：查当前公网 IP
CUR_IP=&quot;$(curl -s https://www.cloudflare.com/cdn-cgi/trace | grep -E &apos;^ip=&apos; | cut -d= -f2)&quot;
if [ -z &quot;$CUR_IP&quot; ]; then
  log &quot;ERROR 拿不到当前公网 IP，本轮跳过&quot;
  exit 1
fi

# 第二步：读现有记录
RESP=&quot;$(curl -s &quot;$API/zones/$CF_ZONE/dns_records?type=$CF_TYPE&amp;amp;name=$CF_NAME&quot; \
  -H &quot;Authorization: Bearer $CF_TOKEN&quot;)&quot;
OLD_IP=&quot;$(echo &quot;$RESP&quot; | jq -r &apos;.result[0].content // empty&apos;)&quot;
REC_ID=&quot;$(echo &quot;$RESP&quot; | jq -r &apos;.result[0].id // empty&apos;)&quot;

if [ -z &quot;$REC_ID&quot; ]; then
  log &quot;ERROR 记录 $CF_NAME 不存在，请先在控制台或用 POST 创建&quot;
  exit 1
fi

# 第三步：相同就退出
if [ &quot;$CUR_IP&quot; = &quot;$OLD_IP&quot; ]; then
  exit 0
fi

# 第四步：不同才更新，并记日志
UPD=&quot;$(curl -s -X PATCH &quot;$API/zones/$CF_ZONE/dns_records/$REC_ID&quot; \
  -H &quot;Authorization: Bearer $CF_TOKEN&quot; \
  -H &quot;Content-Type: application/json&quot; \
  -d &quot;{\&quot;content\&quot;: \&quot;$CUR_IP\&quot;}&quot;)&quot;

if [ &quot;$(echo &quot;$UPD&quot; | jq -r &apos;.success&apos;)&quot; = &quot;true&quot; ]; then
  log &quot;OK $CF_NAME: $OLD_IP -&amp;gt; $CUR_IP&quot;
else
  log &quot;ERROR 更新失败: $(echo &quot;$UPD&quot; | jq -c &apos;.errors&apos;)&quot;
  exit 1
fi
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;逐段讲解&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;set -euo pipefail&lt;/code&gt;&lt;/strong&gt;：任何一步命令失败就整体退出，避免拿着空值继续往下跑，把错带进更新请求里。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;令牌从文件读&lt;/strong&gt;：&lt;code&gt;CF_TOKEN_FILE&lt;/code&gt; 指向单独的配置文件，脚本本身可以放心进 Git、放心给人看；令牌文件单独管控权限，下文细说。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;查 IP 用 &lt;code&gt;cdn-cgi/trace&lt;/code&gt;&lt;/strong&gt;：它返回多行键值对，&lt;code&gt;grep &apos;^ip=&apos;&lt;/code&gt; 取出 IP 那一行。也可以换成 &lt;code&gt;https://ifconfig.me/ip&lt;/code&gt;、&lt;code&gt;https://icanhazip.com&lt;/code&gt; 这类纯文本服务，任选其一，别在脚本里堆一串备用源把逻辑搞复杂——真要高可用，cron 下一轮自然会重试。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;拿不到 IP 就退出&lt;/strong&gt;：&lt;code&gt;CUR_IP&lt;/code&gt; 为空说明本机网络都不通，这时候更新记录毫无意义，还可能把空值写进去，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝不能拿空值或异常值去更新记录&amp;lt;/span&amp;gt;，宁可这一轮跳过。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;GET 时带 &lt;code&gt;type&lt;/code&gt; 和 &lt;code&gt;name&lt;/code&gt; 过滤&lt;/strong&gt;：服务端先筛一遍，&lt;code&gt;jq&lt;/code&gt; 再取 &lt;code&gt;.result[0]&lt;/code&gt;，拿到的就是目标记录的现值和 ID。取不到记录说明这条记录还没建过，脚本不负责自动创建——先用上一节的 POST 或在控制台建好，避免脚本行为超出预期。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;比较在本地做&lt;/strong&gt;：先比对、后请求，这是整个脚本的核心纪律。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;更新用 PATCH 只传 &lt;code&gt;content&lt;/code&gt;&lt;/strong&gt;：只改 IP，其他字段（代理状态、TTL、备注）一概不动。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;结果以 &lt;code&gt;success&lt;/code&gt; 字段为准&lt;/strong&gt;：不要只看 curl 的退出码——HTTP 层通了、业务层也可能失败，失败时把返回 JSON 的 &lt;code&gt;errors&lt;/code&gt; 数组原样记进日志，排障时全靠它定位。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;让它自动跑：cron 与权限&lt;/h2&gt;
&lt;p&gt;脚本手动跑通一次后，挂到 cron 里。编辑当前用户的定时任务：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;chmod +x /opt/scripts/cf-ddns.sh
crontab -e
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;加一行，每 5 分钟跑一次：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;*/5 * * * * /opt/scripts/cf-ddns.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;5 分钟是个均衡的选择：IP 变更后最多 5 分钟新记录就位，再叠加 DNS 本身的缓存时间，实际感知到的中断通常在几分钟内。没必要压到每分钟——运营商换 IP 没那么频繁，过密的轮询只会白白消耗调用次数。&lt;/p&gt;
&lt;p&gt;令牌文件单独存放并收紧权限：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo mkdir -p /etc/cf-ddns
echo &quot;YOUR_TOKEN&quot; | sudo tee /etc/cf-ddns/token &amp;gt; /dev/null
sudo chmod 600 /etc/cf-ddns/token
sudo chown root:root /etc/cf-ddns/token
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;chmod 600&lt;/code&gt; 意味着只有 root 能读。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;令牌文件权限放成 644，等于同机任何用户都能读走你的令牌&amp;lt;/span&amp;gt;，这一步偷懒不得。如果脚本以普通用户身份跑，就把文件属主改成那个用户，权限仍然保持 600。&lt;/p&gt;
&lt;p&gt;日志方面，脚本只在 IP 真正变化或出错时才写一行，量很小；系统自带的 logrotate 一般会顺带管 &lt;code&gt;/var/log&lt;/code&gt; 下的文件，不放心的可以在 &lt;code&gt;/etc/logrotate.d/&lt;/code&gt; 里给它单独加一条按周轮转的规则，一行配置的事，不展开。&lt;/p&gt;
&lt;p&gt;:::warning
再强调一遍存放纪律：脚本可以进仓库，令牌不行。提交代码前养成看一眼 &lt;code&gt;git diff&lt;/code&gt; 的习惯；万一令牌已经误提交并推送到了公开仓库，删文件、改历史都不够，唯一有效的补救是去控制台把那把令牌吊销重建。
:::&lt;/p&gt;
&lt;h2&gt;安全纪律清单&lt;/h2&gt;
&lt;p&gt;把前面零散说的收成一张表，贴在手边执行：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;纪律&lt;/th&gt;
&lt;th&gt;做法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;最小权限&lt;/td&gt;
&lt;td&gt;用 Edit zone DNS 模板，只给 DNS 编辑，不给多余权限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;按域名收敛&lt;/td&gt;
&lt;td&gt;Zone Resources 只选目标域名，一把令牌只管一个域&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;独立存放&lt;/td&gt;
&lt;td&gt;令牌放单独配置文件，权限 600，不写死在脚本里&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;不进仓库&lt;/td&gt;
&lt;td&gt;脚本与令牌分离；仓库里只放脚本和示例配置&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;定期轮换&lt;/td&gt;
&lt;td&gt;令牌设有效期，到期前生成新令牌、替换、再吊销旧的&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;出事能止损&lt;/td&gt;
&lt;td&gt;每把令牌用途单一，泄露时吊销它不影响其他服务&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;轮换的正确顺序是「先建新的、换上、验证、再删旧的」，反过来做会让服务先断一阵。给不同用途（DDNS、证书签发、面板集成）各发一把令牌，不要一把令牌走天下——分开之后，哪把出了问题、该吊销哪把，一目了然。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;h3&gt;401 或 403：令牌无效或权限不够&lt;/h3&gt;
&lt;p&gt;先跑一遍验证接口，确认令牌本身活着：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -s &quot;https://api.cloudflare.com/client/v4/user/tokens/verify&quot; \
  -H &quot;Authorization: Bearer $CF_TOKEN&quot; | jq
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;验证通过但具体操作还是报错，就去看失败响应里的 &lt;code&gt;errors&lt;/code&gt; 数组：里面有错误码和一句说明文字，对照着查——是权限不足、Zone ID 写错、还是记录 ID 不存在，基本都能从说明里读出来。最常见的三种情况：建令牌时 Zone Resources 没勾上这个域名；模板选错，只给了 Read 没给 Edit，查得到改不动；复制令牌时多了空格或少了一截。不要只盯着 HTTP 状态码猜，&lt;code&gt;errors&lt;/code&gt; 才是官方给的诊断书。&lt;/p&gt;
&lt;h3&gt;更新成功但解析没变&lt;/h3&gt;
&lt;p&gt;先分清你查的是什么。如果这条记录开了橙云代理（&lt;code&gt;proxied: true&lt;/code&gt;），外部查询到的本来就是 Cloudflare 边缘节点的 IP，而不是你源站的 IP——这是代理的工作方式，不是更新没生效，记录里的 &lt;code&gt;content&lt;/code&gt; 才是源站地址，判断更新成功与否要回 API 里看 &lt;code&gt;content&lt;/code&gt;，别拿 &lt;code&gt;dig&lt;/code&gt; 的结果对。DDNS 场景通常要的是直连，所以前面建记录时建议 &lt;code&gt;proxied: false&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;如果确认是灰云直连、API 里 &lt;code&gt;content&lt;/code&gt; 也已经是新 IP，但解析还是旧的，那就是缓存与 TTL：各级递归解析器会按 TTL 缓存旧答案，没过期之前问谁都是旧值。用 &lt;code&gt;dig home.example.com @1.1.1.1&lt;/code&gt; 和换几个公共解析器交叉验证，确认只是缓存未过期，剩下的只能等。想让以后切换更快，可以把这条记录的 TTL 设短一些（比如 120 秒），代价是查询量略增，家宽场景完全无所谓。关于 TTL 与代理状态对解析的影响，&lt;a href=&quot;/posts/cloudflare-dns-records/&quot;&gt;DNS 记录详解与常见坑&lt;/a&gt; 里有完整的展开。&lt;/p&gt;
&lt;h3&gt;脚本每轮都在「更新」：比较逻辑写错&lt;/h3&gt;
&lt;p&gt;症状是日志里每 5 分钟一条变更记录，IP 看起来还没变过。九成是比较的双方对不上：&lt;code&gt;CUR_IP&lt;/code&gt; 混进了空格、换行或 IPv6 地址（比如查 IP 的服务在双栈环境下返回了 IPv6，而记录是 A 类型），或者 &lt;code&gt;jq&lt;/code&gt; 取值时取到了另一条同名记录。排查方法：临时在脚本里把 &lt;code&gt;CUR_IP&lt;/code&gt; 和 &lt;code&gt;OLD_IP&lt;/code&gt; 都打进日志，跑一轮，眼见为实。修好之后记得把调试输出撤掉。&lt;/p&gt;
&lt;h3&gt;记录莫名其妙被改回去&lt;/h3&gt;
&lt;p&gt;如果发现记录总被「改回」旧 IP，先想想是不是有两台机器、两个脚本在同时维护同一条记录，或者旧路由器上还留着一份 DDNS 配置在跑。两个自动化互相打架时，表现就是记录来回横跳。自动化工具只留一份，这是纪律。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;凭据只用 API Token 并按最小权限、按域名收敛，全局 API Key 永不进脚本。&lt;/li&gt;
&lt;li&gt;接口套路固定：Bearer 认证头、&lt;code&gt;/zones/{id}/dns_records&lt;/code&gt; 路径、GET 查、POST 增、PATCH 局部改、DELETE 删，结果一律看返回 JSON 的 &lt;code&gt;success&lt;/code&gt; 与 &lt;code&gt;errors&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;DDNS 脚本的灵魂是「先比较、无变化就退出」，配合 cron 每 5 分钟一轮，就是零维护的动态解析。&lt;/li&gt;
&lt;li&gt;令牌独立文件存放、权限 600、定期轮换、用途单一，泄露时能一把吊销干净止损。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;到这里，Cloudflare 的「手点控制台」阶段就算毕业了：记录能批量管、能自动维护，后面无论是给面板做集成，还是把解析变更纳入自己的运维流程，地基都是这一篇的 Token 加四件套。&lt;/p&gt;
</content:encoded></item><item><title>CDN 缓存规则实战：Cache Rules</title><link>https://www.anexns.cloudns.org/posts/cloudflare-cache-rules/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-cache-rules/</guid><description>Cloudflare 默认只缓存静态文件，HTML 默认不缓存：Cache Rules 的匹配表达式与缓存动作逐个讲，边缘 TTL、绕过缓存、缓存键与清除缓存，让该快的快、该实时的实时。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;把域名接入 Cloudflare 之后，很多人以为加速已经完成了。其实默认状态下，Cloudflare 只缓存图片、样式表、脚本这类静态文件，你辛辛苦苦写的 HTML 页面默认根本不进缓存，每一次访问都要回源站取。想让 CDN 真正发挥作用，就得自己动手配规则：哪些内容缓存、缓存多久、哪些内容坚决不能缓存、缓存的副本按什么维度区分。&lt;/p&gt;
&lt;p&gt;本篇的主线是这样的：先把 Cloudflare 的默认缓存行为和源站响应头的关系说清，再教你怎么验证一次请求到底命没命中缓存；然后逐个拆 Cache Rules 的匹配表达式和缓存动作；接着给三个可以直接抄的实战规则；最后讲缓存键、清除缓存、分层缓存和排障。配完这一篇，你的站该快的快、该实时的实时，不再靠运气。&lt;/p&gt;
&lt;h2&gt;默认缓存行为：先搞清谁说了算&lt;/h2&gt;
&lt;p&gt;Cloudflare 的缓存不是「什么都存一份」，它有一套默认判断逻辑。理解这套逻辑，是配规则的前提。&lt;/p&gt;
&lt;h3&gt;默认只认文件扩展名&lt;/h3&gt;
&lt;p&gt;在没有任何自定义规则时，Cloudflare 按 URL 的文件扩展名决定要不要缓存。默认会缓存的包括：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;图片类：&lt;code&gt;jpg&lt;/code&gt;、&lt;code&gt;jpeg&lt;/code&gt;、&lt;code&gt;png&lt;/code&gt;、&lt;code&gt;gif&lt;/code&gt;、&lt;code&gt;webp&lt;/code&gt;、&lt;code&gt;svg&lt;/code&gt;、&lt;code&gt;ico&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;样式与脚本：&lt;code&gt;css&lt;/code&gt;、&lt;code&gt;js&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;字体类：&lt;code&gt;woff&lt;/code&gt;、&lt;code&gt;woff2&lt;/code&gt;、&lt;code&gt;ttf&lt;/code&gt;、&lt;code&gt;eot&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;文档与媒体：&lt;code&gt;pdf&lt;/code&gt;、&lt;code&gt;mp4&lt;/code&gt;、&lt;code&gt;mp3&lt;/code&gt; 等&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;而下面这些默认&lt;strong&gt;不缓存&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;HTML 页面（无扩展名路径、&lt;code&gt;/&lt;/code&gt; 结尾的路径、&lt;code&gt;.html&lt;/code&gt; 之外的动态路由）&lt;/li&gt;
&lt;li&gt;带查询字符串的 API 接口（多数情况）&lt;/li&gt;
&lt;li&gt;源站明确要求不缓存的响应&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;也就是说，一个典型的动态站点接上 Cloudflare 之后，静态资源确实被加速了，但页面本体每次都要回源。这就是很多人觉得「上了 CDN 好像没快多少」的原因：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;默认缓存只覆盖静态文件，HTML 和动态内容要不要缓存，必须由你自己用规则明确指定&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h3&gt;源站 Cache-Control 与 Cloudflare 的优先级&lt;/h3&gt;
&lt;p&gt;缓存这件事有两方在说话：源站通过 &lt;code&gt;Cache-Control&lt;/code&gt;、&lt;code&gt;Expires&lt;/code&gt; 响应头表达意愿，Cloudflare 作为中间层做最终决定。两者的关系如下：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;情形&lt;/th&gt;
&lt;th&gt;源站响应头&lt;/th&gt;
&lt;th&gt;Cloudflare 默认行为&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;静态文件，源站无特殊头&lt;/td&gt;
&lt;td&gt;无 &lt;code&gt;Cache-Control&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;按默认 TTL 缓存（按扩展名有默认时长）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;源站要求不缓存&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Cache-Control: no-store&lt;/code&gt; 或 &lt;code&gt;private&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;尊重源站，不缓存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;源站给了 max-age&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Cache-Control: max-age=3600&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;在边缘 TTL 设为「使用源站」时按 3600 秒缓存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;源站给了 no-cache&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Cache-Control: no-cache&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每次回源验证，不直接给缓存副本&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;配了 Cache Rules 强制缓存&lt;/td&gt;
&lt;td&gt;任意&lt;/td&gt;
&lt;td&gt;规则可以覆盖源站意愿（取决于边缘 TTL 模式）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;有几个细节要记牢：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;源站返回 &lt;code&gt;Set-Cookie&lt;/code&gt; 的响应，默认情况下 Cloudflare 不会缓存它，这是防串号的保命设计，后文还会再提。&lt;/li&gt;
&lt;li&gt;源站返回 200 以外的状态码（比如 404），Cloudflare 也可能短暂缓存，具体时长有默认表，别指望它替你兜住所有情况。&lt;/li&gt;
&lt;li&gt;如果你用规则强制缓存，源站的 &lt;code&gt;no-store&lt;/code&gt; 有可能被覆盖。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;源站明确标注 no-store 的内容通常是敏感数据，强制缓存前必须先确认内容性质&amp;lt;/span&amp;gt;，不要为了命中率把保命设置绕过去。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;验证缓存命中：看 cf-cache-status&lt;/h2&gt;
&lt;p&gt;配规则之前，先学会验证。不然规则配了一堆，到底生没生效全靠猜。&lt;/p&gt;
&lt;p&gt;每次经过 Cloudflare 的响应都会带一个响应头 &lt;code&gt;cf-cache-status&lt;/code&gt;，它直接告诉你这次请求在边缘节点经历了什么：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;取值&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;你应该怎么理解&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;HIT&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;命中缓存&lt;/td&gt;
&lt;td&gt;边缘节点直接返回副本，没回源，最理想&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;MISS&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;未命中，已回源&lt;/td&gt;
&lt;td&gt;第一次请求常见，回源取了并存入缓存（如果可缓存）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;DYNAMIC&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不缓存，动态内容&lt;/td&gt;
&lt;td&gt;该 URL 按规则或默认逻辑不进缓存，每次回源&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;EXPIRED&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;缓存已过期&lt;/td&gt;
&lt;td&gt;副本超过 TTL，已回源刷新或正在刷新&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;STALE&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;返回了过期副本&lt;/td&gt;
&lt;td&gt;源站暂时不可达时，边缘先给旧副本顶着&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;BYPASS&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;按规则绕过缓存&lt;/td&gt;
&lt;td&gt;规则里明确设了 Bypass，每次回源&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;REVALIDATED&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;回源验证后副本仍有效&lt;/td&gt;
&lt;td&gt;带着验证条件回源，源站说没变，继续用副本&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;实测方法很简单，用 &lt;code&gt;curl&lt;/code&gt; 看响应头即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 看某个静态资源的缓存状态
curl -sI https://example.com/assets/app.css | grep -i &quot;cf-cache-status&quot;

# 看首页 HTML 的缓存状态
curl -sI https://example.com/ | grep -iE &quot;cf-cache-status|cache-control|age&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;验证时注意三点：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;同一个 URL 第一次请求多半是 &lt;code&gt;MISS&lt;/code&gt;，紧接着再请求一次才应该变 &lt;code&gt;HIT&lt;/code&gt;。只测一次就下结论，是新手最常见的误判。&lt;/li&gt;
&lt;li&gt;响应头里的 &lt;code&gt;age&lt;/code&gt; 表示这份副本已经在边缘存了多少秒，可以用来反推 TTL 还剩多久。&lt;/li&gt;
&lt;li&gt;Cloudflare 在全球有大量边缘节点，你命中是哪个节点、那份副本存不存在，各节点独立。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;在自己电脑上测出 HIT，不等于全世界用户都是 HIT&amp;lt;/span&amp;gt;，尤其低流量页面，偏远节点可能长期是冷的。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;还有一个进阶验证技巧：响应头里的 &lt;code&gt;cf-ray&lt;/code&gt; 末尾带有机场代码（如 &lt;code&gt;NRT&lt;/code&gt;、&lt;code&gt;FRA&lt;/code&gt;、&lt;code&gt;SIN&lt;/code&gt;），它标明处理这次请求的是哪个城市的节点。同一条命令在不同网络环境下多跑几次，对比 &lt;code&gt;cf-ray&lt;/code&gt; 的节点代码和 &lt;code&gt;cf-cache-status&lt;/code&gt;，就能大致摸清各个地区节点的预热情况。如果某个主力访客所在地区的节点长期是 &lt;code&gt;MISS&lt;/code&gt;，通常不是规则的问题，而是那个地区流量太少、副本存不住，这正是后面要讲的分层缓存要解决的问题。&lt;/p&gt;
&lt;h2&gt;Cache Rules 的结构：匹配 + 动作&lt;/h2&gt;
&lt;p&gt;Cache Rules 位于控制台的「缓存」→「Cache Rules」（部分版本在「规则」栏目下）。一条规则由两部分组成：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;匹配条件&lt;/strong&gt;：哪些请求适用这条规则。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;缓存动作&lt;/strong&gt;：对这些请求怎么处理缓存。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;匹配表达式：用字段圈定范围&lt;/h3&gt;
&lt;p&gt;匹配条件既可以用可视化编辑器点选，也可以用表达式编辑器手写。常用字段有：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;匹配对象&lt;/th&gt;
&lt;th&gt;典型用法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;主机名（Hostname）&lt;/td&gt;
&lt;td&gt;请求的域名&lt;/td&gt;
&lt;td&gt;只对某个子域名生效&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;URI 路径（URI Path）&lt;/td&gt;
&lt;td&gt;路径部分，如 &lt;code&gt;/assets/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;按目录划分缓存策略&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;URI 完整（URI Full）&lt;/td&gt;
&lt;td&gt;含查询字符串的完整地址&lt;/td&gt;
&lt;td&gt;精细匹配带参数的地址&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件扩展名（File Extension）&lt;/td&gt;
&lt;td&gt;如 &lt;code&gt;css&lt;/code&gt;、&lt;code&gt;png&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;对某类文件统一策略&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;查询字符串（Query String）&lt;/td&gt;
&lt;td&gt;参数部分&lt;/td&gt;
&lt;td&gt;区分带版本参数的资源&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cookie / 请求头&lt;/td&gt;
&lt;td&gt;请求携带的 Cookie 或 Header&lt;/td&gt;
&lt;td&gt;按登录状态区分（慎用）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;国家/地区&lt;/td&gt;
&lt;td&gt;访客来源地&lt;/td&gt;
&lt;td&gt;分区域策略&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;手写表达式的语法和防火墙规则表达式一致，比如：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;(http.request.uri.path contains &quot;/assets/&quot;)
(http.request.uri.path contains &quot;/wp-admin/&quot;) or (http.request.uri.path contains &quot;/wp-login.php&quot;)
(ends_with(http.request.uri.path, &quot;.html&quot;)) or (http.request.uri.path eq &quot;/&quot;)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;规则是&lt;strong&gt;自上而下&lt;/strong&gt;匹配的：请求命中第一条符合条件的规则后，就按那条规则执行，不再往下走。所以顺序很重要，越具体的规则越要放前面，兜底规则放最后。&lt;/p&gt;
&lt;p&gt;再补两条管理上的经验。第一，给规则起名字要带上意图，比如「静态资源-长缓存-30天」「后台-绕过-防串号」，半年后回来改规则的人还是你自己，名字说不清意图的规则没人敢动，最后越堆越乱。第二，规则总数是有限的（具体条数以控制台和当前套餐为准），不要一条路径建一条规则；同类路径用 &lt;code&gt;or&lt;/code&gt; 合进一条表达式里，把额度留给真正需要单独策略的内容。每次改完规则，别忘了回到上一节的验证方法实测一遍，控制台里显示「已启用」不等于请求真的按你想的走。&lt;/p&gt;
&lt;h3&gt;缓存动作：四个核心设置&lt;/h3&gt;
&lt;p&gt;命中规则后，可以配置这些动作：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;1. 符合缓存条件（Eligible for cache）&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;这是总开关：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;设为「符合缓存条件」：这类请求进入缓存体系，后续 TTL 等设置才有意义。&lt;/li&gt;
&lt;li&gt;设为「绕过缓存（Bypass cache）」：每次都回源，边缘不存副本。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;2. 边缘 TTL（Edge TTL）&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;决定副本在边缘节点存多久，三种模式：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;模式&lt;/th&gt;
&lt;th&gt;行为&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;忽略源站 Cache-Control&lt;/td&gt;
&lt;td&gt;完全按你填的秒数缓存，无视源站头&lt;/td&gt;
&lt;td&gt;静态站、版本化静态资源&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;使用源站 Cache-Control（Use cache-control header if present）&lt;/td&gt;
&lt;td&gt;源站说了算，没给头时用你填的默认值&lt;/td&gt;
&lt;td&gt;源站已经有成熟缓存策略的应用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;尊重源站但设上下限的思路&lt;/td&gt;
&lt;td&gt;通过源站头加规则默认值组合&lt;/td&gt;
&lt;td&gt;混合型站点&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;注意「忽略源站」是个强力选项：它连源站的 &lt;code&gt;no-store&lt;/code&gt; 都可能盖掉。给静态资源用没问题，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;给任何带用户状态的路径用「忽略源站 + 长 TTL」，就是在给串号事故铺路&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 浏览器 TTL（Browser TTL）&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;控制访客浏览器本地缓存多久，和边缘 TTL 是两回事：边缘存 30 天、浏览器只存 1 小时，意味着用户每小时会向边缘发一次请求（大概率 HIT）。一般保持「尊重源站」或按资源类型单独设。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 其他常用项&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;在源站不可用时提供过期内容（Serve stale content）&lt;/strong&gt;：源站挂了时先给旧副本顶着，提高可用性，静态站建议开。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;忽略查询字符串 / 缓存键相关设置&lt;/strong&gt;：在缓存键里细讲。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;实战规则一：静态目录长缓存&lt;/h2&gt;
&lt;p&gt;场景：&lt;code&gt;/assets/&lt;/code&gt;、&lt;code&gt;/static/&lt;/code&gt; 目录下是带构建指纹的 CSS、JS、图片（文件名形如 &lt;code&gt;app.a1b2c3.js&lt;/code&gt;，内容变了文件名就变）。这类资源可以放心长缓存。&lt;/p&gt;
&lt;p&gt;配置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;规则名称：静态资源长缓存
匹配表达式：(http.request.uri.path contains &quot;/assets/&quot;) or (http.request.uri.path contains &quot;/static/&quot;)
符合缓存条件：是
边缘 TTL：忽略源站 Cache-Control，设为 30 天（2592000 秒）
浏览器 TTL：覆盖为 7 天（604800 秒）——可选
提供过期内容：开
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;为什么敢设 30 天：因为文件名带指纹，新版本是新 URL，老副本留在边缘再久也不会被请求到。如果你站里的静态文件是固定文件名覆盖更新（比如永远叫 &lt;code&gt;style.css&lt;/code&gt;），那就别设这么长，或者改用带版本号的引用方式（后文排障里细说）。&lt;/p&gt;
&lt;h2&gt;实战规则二：后台与登录路径绕过缓存&lt;/h2&gt;
&lt;p&gt;场景：任何站点的后台、登录页、用户中心，都不应该被缓存。拿 WordPress 举例，其他 CMS 同理：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;规则名称：后台绕过缓存
匹配表达式：(http.request.uri.path contains &quot;/wp-admin/&quot;) or (http.request.uri.path contains &quot;/wp-login.php&quot;) or (http.request.uri.path contains &quot;/account/&quot;)
符合缓存条件：否（Bypass cache）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这条规则要放在所有「强制缓存」类规则的&lt;strong&gt;前面&lt;/strong&gt;，否则可能被前面的宽泛规则先命中。&lt;/p&gt;
&lt;p&gt;必须讲清 Bypass 的代价：绕过缓存意味着每一个请求都打到源站。后台本身流量小，无所谓；但如果误把高流量路径设成 Bypass，源站会被自己的流量打满。所以 Bypass 只给低流量、高实时性的路径用。判断标准很简单：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Bypass 给「人少但必须实时」的地方，长缓存给「人多且内容不变」的地方，中间地带用短 TTL 加源站头控制&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;另外提醒：登录状态的判断别只靠路径。很多应用登录后访问的还是普通路径，只是多了 Cookie。这类站点要么靠源站响应头（&lt;code&gt;private&lt;/code&gt;、&lt;code&gt;no-store&lt;/code&gt;）让 Cloudflare 自动不缓存，要么在缓存键和规则里考虑 Cookie 字段，绝不能只凭路径就放心。&lt;/p&gt;
&lt;h2&gt;实战规则三：静态站整站 HTML 缓存&lt;/h2&gt;
&lt;p&gt;场景：纯静态站点（博客、文档站、落地页），HTML 本身也是静态文件，可以整站缓存，效果立竿见影——源站哪怕是一台小机器，也能扛住流量高峰，因为绝大多数请求根本到不了源站。&lt;/p&gt;
&lt;p&gt;配置思路：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;规则名称：整站缓存
匹配表达式：(http.host eq &quot;example.com&quot;)   // 对整站生效，排在前两条规则之后
符合缓存条件：是
边缘 TTL：忽略源站，设为 2 小时（7200 秒）起步，稳定后可拉长
提供过期内容：开
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;配套纪律，比规则本身更重要：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;发布更新后必须清缓存&lt;/strong&gt;。部署脚本最后一步调 Cloudflare 的清除接口，或者人工在控制台清一次。忘了清，用户看到的就是旧页面，还会以为部署失败。稍微讲究一点的做法是把清缓存做成自动化：为站点单独建一个只有「清除缓存」权限的 API 令牌，部署流水线在上传文件成功后自动调用清除接口，只清本次变更过的 URL 列表。这样既不用每次人工进控制台，也避免了图省事直接全部清除。令牌权限只给到单个区域的缓存清除，泄露了也伤不到 DNS 和其他设置。&lt;/li&gt;
&lt;li&gt;TTL 别一上来就设一个月。先设 1 到 2 小时，确认更新流程顺畅、清缓存动作稳定执行，再逐步拉长。&lt;/li&gt;
&lt;li&gt;评论、搜索这类动态功能如果靠第三方服务嵌入（不经过源站），不影响整站缓存；如果站内有自己的动态接口，把那些路径单独拎出来 Bypass 或短 TTL。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::warning
整站缓存只适用于内容对所有访客完全一致的站点。只要页面里有「欢迎回来，某某某」这类按用户变化的内容，整站缓存立刻从优化变成事故预告，下一节细说。
:::&lt;/p&gt;
&lt;h2&gt;缓存键：副本按什么维度区分&lt;/h2&gt;
&lt;p&gt;缓存键（Cache Key）决定边缘节点把哪些请求视为「同一个资源」。默认缓存键主要看 URL（含查询字符串）。也就是说：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;/app.css?v=1&lt;/code&gt; 和 &lt;code&gt;/app.css?v=2&lt;/code&gt; 是两份副本（合理，版本不同）。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;/page?utm_source=a&lt;/code&gt; 和 &lt;code&gt;/page?utm_source=b&lt;/code&gt; 也是两份副本（不合理，内容明明一样）。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;第二种情况就是命中率杀手。营销参数、追踪参数让同一个页面裂变成几十份副本，每份都要单独预热，命中率自然惨不忍睹。&lt;/p&gt;
&lt;p&gt;在规则或缓存设置里可以调整缓存键：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;调整项&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;建议&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;忽略查询字符串&lt;/td&gt;
&lt;td&gt;所有带参请求共用一份副本&lt;/td&gt;
&lt;td&gt;仅对确认参数不影响内容的资源用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;只保留指定参数&lt;/td&gt;
&lt;td&gt;只让 &lt;code&gt;v&lt;/code&gt;、&lt;code&gt;lang&lt;/code&gt; 等参数参与区分&lt;/td&gt;
&lt;td&gt;静态资源和多语言页面的常用做法&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;按 Cookie 区分&lt;/td&gt;
&lt;td&gt;不同 Cookie 值存不同副本&lt;/td&gt;
&lt;td&gt;只对确实按 Cookie 变内容的页面开&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;按请求头区分&lt;/td&gt;
&lt;td&gt;如按 &lt;code&gt;Accept-Language&lt;/code&gt; 分语言副本&lt;/td&gt;
&lt;td&gt;多语言站点用，别滥用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;原则：参与区分的维度越少，命中率越高；但少到把本该区分的维度也合并了，就会给用户发错内容。&lt;code&gt;lang&lt;/code&gt; 参数决定页面语言的站，把查询字符串整个忽略，法国用户就会看到中文页。所以调整缓存键之前，先列一张表：这个资源的响应内容到底受哪些因素影响，只保留那些因素。&lt;/p&gt;
&lt;h2&gt;清除缓存：三种粒度和各自的代价&lt;/h2&gt;
&lt;p&gt;更新内容后旧副本还在边缘，就需要清除缓存（Purge）。控制台「缓存」→「配置」里有入口，API 也能调。三种粒度：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方式&lt;/th&gt;
&lt;th&gt;范围&lt;/th&gt;
&lt;th&gt;代价&lt;/th&gt;
&lt;th&gt;适用场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;按 URL 清除&lt;/td&gt;
&lt;td&gt;指定单个或一批 URL&lt;/td&gt;
&lt;td&gt;最小，只影响这些资源&lt;/td&gt;
&lt;td&gt;改了某篇文章、换了某张图&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;按前缀/主机名清除&lt;/td&gt;
&lt;td&gt;某目录或某子域全部&lt;/td&gt;
&lt;td&gt;中等，该范围内要重新预热&lt;/td&gt;
&lt;td&gt;整站改版、目录结构调整&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;全部清除（Purge Everything）&lt;/td&gt;
&lt;td&gt;整个域名所有缓存&lt;/td&gt;
&lt;td&gt;最大，全站回源压力骤增&lt;/td&gt;
&lt;td&gt;极少使用，仅限配置大改后&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;全部清除是最被滥用的一个按钮。点下去的瞬间，全球边缘节点的副本全部作废，接下来的每一波流量都直达源站，小机器源站可能直接被打挂。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;全部清除不是「刷新一下」那么轻松，它等于把 CDN 临时关掉让源站裸奔&amp;lt;/span&amp;gt;，除非确有必要，能按 URL 清就按 URL 清。&lt;/p&gt;
&lt;p&gt;还有一个临时手段：&lt;strong&gt;开发模式（Development Mode）&lt;/strong&gt;。开启后 3 小时内所有请求绕过缓存直达源站，适合调试样式、排查「到底是缓存问题还是源站问题」。调试完记得它会自动关闭，不用手工关，但调试期间站点等于无缓存状态，别在高峰期开着忘了。&lt;/p&gt;
&lt;h2&gt;分层缓存 Tiered Cache：要不要开&lt;/h2&gt;
&lt;p&gt;普通模式下，每个边缘节点各自为战：东京节点缓存了你的首页，不代表法兰克福节点也有，法兰克福的第一个访客还是要回源。分层缓存（Tiered Cache）的做法是在边缘节点之上再设一层「上层缓存节点」：下层节点没命中时，先去上层节点要，上层也没有才回源。&lt;/p&gt;
&lt;p&gt;好处很直接：回源次数大幅减少，偏远地区、长尾页面的命中率明显提升，源站压力更平滑。开启方式在控制台「缓存」→「分层缓存」里，有免费的智能分层选项可直接启用（具体可用范围以控制台为准）。&lt;/p&gt;
&lt;p&gt;打个比方：没有分层时，一百个边缘节点各回源一次，你的源站要扛一百次首访；开了分层后，这一百个节点先汇到少数上层节点，上层节点大多已经有副本，真正落到源站的可能只有几次。对源站是小机器、又怕被流量打满的个人站点，这个开关的性价比极高，基本属于「开了不后悔」的那一类设置。&lt;/p&gt;
&lt;p&gt;建议：只要你的访客分布跨多个地区，或者源站性能一般，就值得开，基本没有副作用。单地区小站收益不明显，但开了也不亏。&lt;/p&gt;
&lt;h2&gt;动态内容长缓存：事故级配置&lt;/h2&gt;
&lt;p&gt;这一节必须单独拿出来说，因为它是缓存领域最经典、后果最严重的一类事故。&lt;/p&gt;
&lt;p&gt;设想：某电商站为了提升速度，给全站配了「忽略源站、边缘 TTL 7 天」的规则。管理员登录后访问订单页，这个页面包含他的姓名、订单、地址。Cloudflare 把这份响应存进边缘。接下来任何一个访客打开同一个 URL，边缘直接把管理员的那份页面发给他——姓名、订单、地址全在里面。这就是&lt;strong&gt;串号&lt;/strong&gt;：A 用户看到了 B 用户的页面。&lt;/p&gt;
&lt;p&gt;出事的根本原因有三个，缺一不可地凑齐了才会爆：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;内容随用户变化（动态页面）；&lt;/li&gt;
&lt;li&gt;被强制缓存（规则覆盖了源站的保护头）；&lt;/li&gt;
&lt;li&gt;缓存键不区分用户（没按 Cookie 等维度拆分）。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Cloudflare 的默认行为其实已经防了一手：带 &lt;code&gt;Set-Cookie&lt;/code&gt; 的响应默认不缓存。但只要你用规则把「忽略源站」打开、再把这类路径圈进去，这道防线就被你亲手拆了。&lt;/p&gt;
&lt;p&gt;:::warning
购物车、用户中心、订单页、个人资料页这类内容随用户变化的页面，绝对不要配长缓存，更不要用「忽略源站 Cache-Control」。真要优化这类页面，方向是优化源站响应速度、缓存页面里的静态片段资源，而不是缓存页面本体。一旦发生串号，漏出去的是别人的隐私数据，这是事故，不是性能问题。
:::&lt;/p&gt;
&lt;p&gt;自查方法：用未登录状态和登录状态分别 &lt;code&gt;curl&lt;/code&gt; 同一个动态 URL，看 &lt;code&gt;cf-cache-status&lt;/code&gt;。登录态的响应如果出现 &lt;code&gt;HIT&lt;/code&gt;，立刻停下来检查规则。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;h3&gt;规则配了不生效&lt;/h3&gt;
&lt;p&gt;按这个顺序查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;顺序&lt;/strong&gt;：规则自上而下命中第一条就停。你的新规则是不是排在了一条更宽泛的规则后面，请求根本轮不到它？&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;表达式没匹配上&lt;/strong&gt;：路径大小写、末尾斜杠、子域名写错，都是常见原因。用表达式编辑器里的测试思路逐段核对字段值，必要时先把条件放宽到只匹配主机名，确认规则能命中，再逐步加细。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;被源站头否决&lt;/strong&gt;：规则设了「符合缓存条件」，但边缘 TTL 用的是「使用源站」，而源站回了 &lt;code&gt;no-store&lt;/code&gt;，照样不缓存。看源站实际响应头再判断。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;规则数量与可用范围&lt;/strong&gt;：不同套餐可建的规则条数不同（以控制台为准），超限的规则建不上去或不生效，别在旧规则上反复改，先确认规则本身处于启用状态。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;更新了文件，访客还是旧的&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;先确认边缘状态：对出问题 URL 执行 &lt;code&gt;curl -sI&lt;/code&gt;，看 &lt;code&gt;cf-cache-status&lt;/code&gt; 和 &lt;code&gt;age&lt;/code&gt;。是 &lt;code&gt;HIT&lt;/code&gt; 且 age 很大，就是副本没清。&lt;/li&gt;
&lt;li&gt;按 URL 清除这一份缓存，再测。还不行，检查浏览器 TTL——可能边缘已经是新的，访客浏览器还在用本地副本。&lt;/li&gt;
&lt;li&gt;治本手法是&lt;strong&gt;版本号&lt;/strong&gt;：静态资源引用带指纹或版本号（&lt;code&gt;app.css?v=20261115&lt;/code&gt;），新版本新 URL，天然绕开旧缓存。这比每次更新后手工清缓存可靠得多。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;命中率低得离谱&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;查询字符串在作怪&lt;/strong&gt;：统计一下访问日志，同一路径带不同参数的占比有多高。营销参数满天飞的站，先在缓存键里把无关参数剔除。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cookie 在作怪&lt;/strong&gt;：某些应用给每个访客都种不同的 Cookie 并让响应带 &lt;code&gt;Set-Cookie&lt;/code&gt;，这类响应默认不缓存。先确认是不是应用行为，能改应用就改应用，不能改就接受这类页面不缓存。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;流量太分散&lt;/strong&gt;：长尾页面每个节点访问量都很低，副本还没预热就过期了。开分层缓存、适当拉长 TTL，是这类问题的正解。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;TTL 太短&lt;/strong&gt;：TTL 设 60 秒的资源，边缘刚存好就过期，命中率必然难看。对照内容更新频率重新评估 TTL，别矫枉过正。&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Cloudflare 默认只缓存静态扩展名资源，HTML 默认不缓存；想加速页面本体，必须自己配 Cache Rules。&lt;/li&gt;
&lt;li&gt;验证先行：&lt;code&gt;cf-cache-status&lt;/code&gt; 是判断缓存行为的唯一可信依据，第一次 MISS、第二次 HIT 才是正常节奏。&lt;/li&gt;
&lt;li&gt;Cache Rules = 匹配表达式 + 缓存动作，规则自上而下命中即停，具体规则在前、兜底规则在后。&lt;/li&gt;
&lt;li&gt;边缘 TTL 三种模式里，「忽略源站」最强也最危险，只给纯静态内容用；Bypass 只给人少且必须实时的路径用。&lt;/li&gt;
&lt;li&gt;缓存键决定副本的拆分维度，无关查询参数是命中率头号杀手，按内容实际影响因素做减法。&lt;/li&gt;
&lt;li&gt;清缓存优先按 URL，全部清除等于让源站裸奔，非必要不用；开发模式只适合短时调试。&lt;/li&gt;
&lt;li&gt;分层缓存能显著减少回源，跨地区站点建议开启。&lt;/li&gt;
&lt;li&gt;动态页面配长缓存会串号，泄露的是用户隐私，这是缓存配置里最不能犯的错。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;把这一篇的规则配好，你的站才算真正把 CDN 用起来了：静态资源长缓存压住源站压力，动态路径干净绕行，更新有清除纪律，命中率有缓存键兜底。&lt;/p&gt;
</content:encoded></item><item><title>D1 数据库实战：给 Worker 一个原生的 SQL 数据库</title><link>https://www.anexns.cloudns.org/posts/cloudflare-d1-database/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-d1-database/</guid><description>给 Worker 存结构化数据别再自建 MySQL：建 D1、写迁移、绑定查询，再给探活 Worker 加历史表，含 Time Travel 恢复、导出与免费额度。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;开头就踩的坑：给 Worker 配一台 MySQL&lt;/h2&gt;
&lt;p&gt;你写好了一个 Worker，想给它存点结构化数据——用户提交的表单、每次任务的运行记录、探活的历史结果。第一反应往往很自然：手头正好有台 VPS，装个 MySQL，把连接串填进 Worker 的环境变量，收工。&lt;/p&gt;
&lt;p&gt;真跑起来才发现处处别扭：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Worker 没有常驻进程，它跑在 Cloudflare 的边缘节点上，每次请求由离访客最近的节点执行，位置天天在变；&lt;/li&gt;
&lt;li&gt;没有常驻进程就没有连接池，每次查询都要重新走一遍 TCP 握手、TLS 协商和数据库鉴权，数据还没查，先花几十上百毫秒在「打招呼」上；&lt;/li&gt;
&lt;li&gt;你的 MySQL 在法兰克福，请求可能从新加坡的节点发起，一来一回的物理延迟谁也救不了；&lt;/li&gt;
&lt;li&gt;数据库还得开着公网端口等连接，防火墙、白名单、弱口令扫描全套伺候，或者再套一层转发，又多一层要维护的东西；&lt;/li&gt;
&lt;li&gt;最后，这台数据库的备份、升级、监控、磁盘，全是你的活。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;说到底，Worker 的运行模型和「长连接连一台固定数据库」这套老范式天生不对付。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Cloudflare 给出的原生答案是 D1：一个和 Worker 同平台的 SQL 数据库，查询不走公网、不建连接，通过绑定直接调用。&amp;lt;/span&amp;gt;本篇就把 D1 从建库、建表、绑定、查询到备份恢复完整走一遍。&lt;/p&gt;
&lt;p&gt;官方文档：https://developers.cloudflare.com/d1/&lt;/p&gt;
&lt;h2&gt;D1 是什么&lt;/h2&gt;
&lt;p&gt;D1 是 Cloudflare 的无服务器 SQL 数据库，底层是大家熟悉的 SQLite：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;语法就是 SQLite&lt;/strong&gt;：建表、索引、JOIN、聚合、事务，写法和你本地玩过的 SQLite 一模一样，从 MySQL 迁移过来主要注意方言差异（排障一节有清单）；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;无服务器&lt;/strong&gt;：没有实例、没有规格选型，不查询时不产生计算费用，建库就是一条命令的事；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;和 Worker 同平台&lt;/strong&gt;：数据库通过「绑定」挂到 Worker 上，代码里拿 &lt;code&gt;env.DB&lt;/code&gt; 直接发查询，中间没有网络连接、没有连接串、没有账号密码；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;不止 Worker 能连&lt;/strong&gt;：Pages Functions、Wrangler 命令行、REST API 都能访问同一个库，本地调试和线上运维用同一套工具；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;边界也要先说清&lt;/strong&gt;：单库容量有限（免费版单库最大 500 MB），写入是 SQLite 的单写者模型，它是给中小规模结构化数据准备的，不是拿来替代大型业务数据库的。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;同样是给 Worker 存数据，D1、自建 MySQL、KV 三条路线的差别一目了然：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;D1&lt;/th&gt;
&lt;th&gt;自建 MySQL&lt;/th&gt;
&lt;th&gt;Workers KV&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;数据模型&lt;/td&gt;
&lt;td&gt;关系型，完整 SQL&lt;/td&gt;
&lt;td&gt;关系型，完整 SQL&lt;/td&gt;
&lt;td&gt;键值对&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;与 Worker 的连接&lt;/td&gt;
&lt;td&gt;绑定注入，无网络连接&lt;/td&gt;
&lt;td&gt;每次请求新建连接或套转发&lt;/td&gt;
&lt;td&gt;绑定注入&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;运维负担&lt;/td&gt;
&lt;td&gt;零运维&lt;/td&gt;
&lt;td&gt;装机、备份、升级、监控全包&lt;/td&gt;
&lt;td&gt;零运维&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;查询能力&lt;/td&gt;
&lt;td&gt;筛选、排序、聚合、JOIN 都行&lt;/td&gt;
&lt;td&gt;最强&lt;/td&gt;
&lt;td&gt;只能按 key 取值&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;一致性&lt;/td&gt;
&lt;td&gt;强一致&lt;/td&gt;
&lt;td&gt;强一致&lt;/td&gt;
&lt;td&gt;最终一致&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合场景&lt;/td&gt;
&lt;td&gt;表单、记录、历史数据等结构化存储&lt;/td&gt;
&lt;td&gt;已有 MySQL 生态、大数据量&lt;/td&gt;
&lt;td&gt;配置、缓存、读多写少的简单状态&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;简单记：要按条件查、要算账，选 D1；只是存个开关、缓存个结果，KV 就够；已经有一整套 MySQL 业务系统，那是另一个话题。&lt;/p&gt;
&lt;h2&gt;用 Wrangler 建库&lt;/h2&gt;
&lt;p&gt;先装好 Wrangler 并登录。本地电脑上跑 &lt;code&gt;wrangler login&lt;/code&gt; 会拉起浏览器授权；在服务器这类无头环境里改用 API Token 登录，Token 的创建方法见 &lt;a href=&quot;/posts/cloudflare-api-token-ddns/&quot;&gt;用 API Token 给域名做 DDNS&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;建库只要一条命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;wrangler d1 create uptime-db
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出里会给出这个库的 &lt;code&gt;database_id&lt;/code&gt;，并附上一段现成的绑定配置供你抄进配置文件。查看和管理已有数据库：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;wrangler d1 list          # 列出账号下所有 D1 数据库
wrangler d1 info uptime-db  # 看单个库的大小、表数量等信息
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把 &lt;code&gt;database_id&lt;/code&gt; 记下来，下一步绑定要用——它长得像一串 UUID，是这个库在 Cloudflare 上的唯一身份证。&lt;/p&gt;
&lt;h2&gt;把数据库绑定到 Worker&lt;/h2&gt;
&lt;p&gt;在 Worker 项目的 &lt;code&gt;wrangler.toml&lt;/code&gt; 里加上绑定段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;name = &quot;uptime-checker&quot;
main = &quot;src/index.js&quot;
compatibility_date = &quot;2026-11-01&quot;

[[d1_databases]]
binding = &quot;DB&quot;
database_name = &quot;uptime-db&quot;
database_id = &quot;xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&quot;
migrations_dir = &quot;migrations&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三个字段各管一件事：&lt;code&gt;binding&lt;/code&gt; 是代码里用的名字，写 &lt;code&gt;DB&lt;/code&gt; 就通过 &lt;code&gt;env.DB&lt;/code&gt; 访问（Worker 的基本结构见 &lt;a href=&quot;/posts/cloudflare-workers-intro/&quot;&gt;Workers 入门&lt;/a&gt;）；&lt;code&gt;database_name&lt;/code&gt; 是建库时的名字；&lt;code&gt;database_id&lt;/code&gt; 是上一步拿到的唯一 ID。&lt;code&gt;migrations_dir&lt;/code&gt; 指定迁移文件放哪个目录，默认就是 &lt;code&gt;migrations&lt;/code&gt;，可以不写。一个 Worker 要用多个库，就写多段 &lt;code&gt;[[d1_databases]]&lt;/code&gt;，靠 &lt;code&gt;binding&lt;/code&gt; 名区分。&lt;/p&gt;
&lt;p&gt;改完配置重新部署（或重启 &lt;code&gt;wrangler dev&lt;/code&gt;），绑定才会生效。&lt;/p&gt;
&lt;h2&gt;建表与迁移：结构变更要版本化&lt;/h2&gt;
&lt;p&gt;表结构不要靠手敲一次性的命令凑，正经做法是「迁移」：每次结构变更生成一个带序号的 SQL 文件，跟着代码一起进版本管理，哪个环境没应用、应用到哪一步，一清二楚。&lt;/p&gt;
&lt;p&gt;先生成一个迁移：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;wrangler d1 migrations create uptime-db create_checks_table
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它会在 &lt;code&gt;migrations/&lt;/code&gt; 目录下生成 &lt;code&gt;0001_create_checks_table.sql&lt;/code&gt;，把建表语句写进去。本篇实战要用的探活结果表长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE TABLE IF NOT EXISTS checks (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  url TEXT NOT NULL,
  ok INTEGER NOT NULL,
  status INTEGER,
  latency_ms INTEGER,
  checked_at TEXT NOT NULL DEFAULT (datetime(&apos;now&apos;))
);

CREATE INDEX idx_checks_url_time ON checks (url, checked_at);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后把迁移应用到目标环境：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;wrangler d1 migrations apply uptime-db --local    # 先应用到本地
wrangler d1 migrations apply uptime-db --remote   # 再应用到远程（线上）
wrangler d1 migrations list uptime-db --remote    # 确认远程的应用状态
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
本地库和远程库是两个完全独立的数据库：&lt;code&gt;wrangler dev&lt;/code&gt; 和带 &lt;code&gt;--local&lt;/code&gt; 的命令操作的是本机模拟环境里的数据，线上 Worker 连的是 &lt;code&gt;--remote&lt;/code&gt; 的生产库。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;迁移只 apply 到本地、忘了 apply 到远程，是新手最常见的翻车点&amp;lt;/span&amp;gt;：本地一切正常，一上线就报 &lt;code&gt;no such table&lt;/code&gt;。养成习惯，所有迁移命令都显式带上 &lt;code&gt;--local&lt;/code&gt; 或 &lt;code&gt;--remote&lt;/code&gt;，不要靠默认值猜。
:::&lt;/p&gt;
&lt;p&gt;临时查个数据、导点测试数据，用 &lt;code&gt;execute&lt;/code&gt; 直接跑 SQL：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;wrangler d1 execute uptime-db --remote --command &quot;SELECT COUNT(*) AS n FROM checks;&quot;
wrangler d1 execute uptime-db --local --file ./seed.sql
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;在 Worker 里查询：prepare、bind 与 batch&lt;/h2&gt;
&lt;p&gt;绑定生效后，Worker 里查询 D1 的 API 非常小，核心就是 &lt;code&gt;prepare()&lt;/code&gt; 准备语句、&lt;code&gt;bind()&lt;/code&gt; 填参数，再选一个执行方法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;// 查多行：all() 返回 { results: [...] }
const { results } = await env.DB
  .prepare(&quot;SELECT * FROM checks WHERE url = ? ORDER BY id DESC LIMIT ?&quot;)
  .bind(url, 20)
  .all();

// 查一行：first() 返回一行对象，查不到返回 null
const latest = await env.DB
  .prepare(&quot;SELECT * FROM checks WHERE url = ? ORDER BY id DESC&quot;)
  .bind(url)
  .first();

// 写入：run() 返回的结果里 meta.changes 是影响行数，meta.last_row_id 是新行 id
const info = await env.DB
  .prepare(&quot;INSERT INTO checks (url, ok, status, latency_ms) VALUES (?, ?, ?, ?)&quot;)
  .bind(url, 1, 200, 123)
  .run();
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;参数一律走 &lt;code&gt;bind()&lt;/code&gt;，占位符用 &lt;code&gt;?&lt;/code&gt;。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把用户输入直接拼进 SQL 字符串，等于把 SQL 注入的大门敞开&amp;lt;/span&amp;gt;，bind 既防注入，又免去手动转义引号的麻烦；&lt;/li&gt;
&lt;li&gt;一次要执行多条语句时用 &lt;code&gt;batch()&lt;/code&gt;：把多个 prepare 好的语句放进数组一次提交，它们在一个事务里执行，要么全成功要么全回滚，省往返又保一致。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;每次查询返回的结果还带一个 &lt;code&gt;meta&lt;/code&gt; 对象，里面有 &lt;code&gt;rows_read&lt;/code&gt;、&lt;code&gt;rows_written&lt;/code&gt; 等计数，排查「哪条查询在烧额度」时就靠它。&lt;/p&gt;
&lt;h2&gt;实战：给探活 Worker 加一张历史表&lt;/h2&gt;
&lt;p&gt;上一篇 &lt;a href=&quot;/posts/cloudflare-workers-cron-kv/&quot;&gt;Workers 进阶：Cron 定时任务与 KV 存储&lt;/a&gt; 里的探活 Worker，把每个站点的最新状态写进 KV，状态页够用了。但 KV 里只有「当前值」，回答不了这类问题：过去 24 小时这个站挂过几次？平均延迟多少？哪几次故障分别发生在几点？&lt;/p&gt;
&lt;p&gt;这些都是典型的历史数据问题，正是 D1 的主场。还是那个 Worker，加上刚才迁移建好的 &lt;code&gt;checks&lt;/code&gt; 表：定时任务每跑一轮，把每个站点的探活结果各写一行；&lt;code&gt;fetch&lt;/code&gt; 处理函数则按条件查历史。完整代码：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;const TARGETS = [&quot;https://example.com&quot;, &quot;https://blog.example.com&quot;];

export default {
  // 定时触发：探活并把结果逐行写入 D1
  async scheduled(event, env, ctx) {
    const stmts = [];
    for (const url of TARGETS) {
      const started = Date.now();
      let ok = 0;
      let status = null;
      try {
        const res = await fetch(url, { redirect: &quot;follow&quot; });
        status = res.status;
        ok = res.ok ? 1 : 0;
      } catch (e) {
        ok = 0; // 网络层失败：连不上、超时、证书错误等
      }
      stmts.push(
        env.DB.prepare(
          &quot;INSERT INTO checks (url, ok, status, latency_ms) VALUES (?, ?, ?, ?)&quot;
        ).bind(url, ok, status, Date.now() - started)
      );
    }
    await env.DB.batch(stmts); // 一轮的结果一次事务写完
  },

  // HTTP 请求：返回最近 50 条探活记录
  async fetch(request, env) {
    const { results } = await env.DB
      .prepare(
        &quot;SELECT url, ok, status, latency_ms, checked_at FROM checks ORDER BY id DESC LIMIT ?&quot;
      )
      .bind(50)
      .all();
    return Response.json(results);
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;历史攒起来之后，可用率这种指标就是一条聚合查询的事：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;// 某个站点最近 24 小时的总次数、成功次数和平均延迟
const row = await env.DB
  .prepare(
    `SELECT COUNT(*) AS total,
            SUM(ok) AS ok_count,
            ROUND(AVG(latency_ms)) AS avg_ms
     FROM checks
     WHERE url = ? AND checked_at &amp;gt; datetime(&apos;now&apos;, &apos;-1 day&apos;)`
  )
  .bind(url)
  .first();
// 可用率 = row.ok_count / row.total
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;KV 存「现在怎么样」，D1 存「一直以来怎么样」，两个绑在同一个 Worker 上配合，这就是上一篇探活方案的完整形态。&lt;/p&gt;
&lt;h2&gt;备份与恢复：Time Travel 与导出&lt;/h2&gt;
&lt;p&gt;数据库最怕的不是慢，是误删。D1 自带 Time Travel：不需要手动开启、不需要排备份计划，它持续记录变更，可以把整个库恢复到过去任意一分钟的状态。保留窗口是付费版 30 天、免费版 7 天。&lt;/p&gt;
&lt;p&gt;先按时间点查出对应的书签（bookmark）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;wrangler d1 time-travel info uptime-db --timestamp=&quot;2026-11-15T09:30:00+08:00&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拿到书签后执行恢复：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;wrangler d1 time-travel restore uptime-db --bookmark=00000085-0000024c-00004c6d-8e61117bf38d7adb71b934ebbf891683
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;restore 会用目标时间点的状态覆盖当前数据库的全部数据&amp;lt;/span&amp;gt;，正在执行的查询会被取消，执行前务必想清楚目标时间点。好的一面是：恢复操作本身会返回一个「恢复前」的书签，万一恢复错了，还能再 restore 回去。误删一行、跑飞一条没带 &lt;code&gt;WHERE&lt;/code&gt; 的 &lt;code&gt;UPDATE&lt;/code&gt;、迁移把表改坏，都靠它兜底——但免费版窗口只有 7 天，过期就真的没了。
:::&lt;/p&gt;
&lt;p&gt;想留一份能长期保存、能脱离 Cloudflare 的备份，用导出：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;wrangler d1 export uptime-db --remote --output ./uptime-db-backup.sql
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;导出的是一份标准 SQL 文件（建表语句加全部数据），随时能导回任何 SQLite 环境。每周导出一份扔进对象存储或自己的备份盘里，Time Travel 的时间窗口之外也有据可查；对象存储怎么用见 &lt;a href=&quot;/posts/cloudflare-r2-storage/&quot;&gt;R2 对象存储&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;免费额度：小项目基本用不完&lt;/h2&gt;
&lt;p&gt;D1 按「读行数、写行数、存储量」计量，免费版（Workers Free）额度如下，数字以官方文档为准：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;项目&lt;/th&gt;
&lt;th&gt;免费版额度&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;读取&lt;/td&gt;
&lt;td&gt;每日 500 万行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;写入&lt;/td&gt;
&lt;td&gt;每日 10 万行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;存储&lt;/td&gt;
&lt;td&gt;账号下所有库总计 5 GB（单库最大 500 MB）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据库个数&lt;/td&gt;
&lt;td&gt;最多 10 个&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;理解额度有两个关键点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;读行数按扫描行数算&lt;/strong&gt;：一张 5000 行的表全表 &lt;code&gt;SELECT&lt;/code&gt; 一次就是 5000 行读取，返回几行不重要。给常查的字段建索引（比如上面给 &lt;code&gt;url, checked_at&lt;/code&gt; 建的联合索引），既提速又省额度；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;每日额度在 UTC 零点重置&lt;/strong&gt;，超限后当天的查询会直接报错，想放开就升到 Workers Paid，额度立刻变成按月计算的大盘子。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;拿探活实战算笔账：5 分钟探一轮、每轮写 2 行，一天写入不到 600 行，离 10 万行的上限差着两个数量级——个人和小团队项目，免费额度通常根本碰不到顶。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;本地查得到数据，线上查不到（或者反过来）。&lt;/strong&gt; 本地和远程是两个独立的库，先确认自己看的是哪一边：&lt;code&gt;wrangler dev&lt;/code&gt; 默认连本地库，线上 Worker 连远程库；用 &lt;code&gt;d1 execute&lt;/code&gt; 时显式带 &lt;code&gt;--local&lt;/code&gt; 或 &lt;code&gt;--remote&lt;/code&gt; 再查一次，多半是看错库了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Worker 报错，说 &lt;code&gt;env.DB&lt;/code&gt; 是 undefined。&lt;/strong&gt; 绑定没对上：检查 &lt;code&gt;wrangler.toml&lt;/code&gt; 里 &lt;code&gt;binding&lt;/code&gt; 的值和代码里用的名字是否完全一致（大小写敏感），改完配置有没有重新部署。九成是这两个原因。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;线上查询报 &lt;code&gt;no such table: checks&lt;/code&gt;。&lt;/strong&gt; 表只在本地建了，迁移没应用到远程。跑 &lt;code&gt;wrangler d1 migrations list uptime-db --remote&lt;/code&gt; 看状态，再补一条 &lt;code&gt;wrangler d1 migrations apply uptime-db --remote&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;绑定了却连到空库、或者报数据库不存在。&lt;/strong&gt; &lt;code&gt;database_id&lt;/code&gt; 抄错了，或者抄成了另一个库的 ID。跑 &lt;code&gt;wrangler d1 list&lt;/code&gt;，把输出里的 ID 和配置文件逐字对一遍。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;从 MySQL 搬来的 SQL 在 D1 报错。&lt;/strong&gt; D1 是 SQLite 方言，常见差异先过一遍：自增主键写 &lt;code&gt;INTEGER PRIMARY KEY AUTOINCREMENT&lt;/code&gt;，没有 &lt;code&gt;NOW()&lt;/code&gt;、用 &lt;code&gt;datetime(&apos;now&apos;)&lt;/code&gt;，没有 &lt;code&gt;AUTO_INCREMENT&lt;/code&gt; 和反引号那一套，字符串用单引号。逐条改完再跑。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写入报错说超过每日限额。&lt;/strong&gt; 先看是不是有失控的循环在狂写，再对照免费额度一节算总量；确认是正常业务量增长，就升级套餐或给写入加节流。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;给 Worker 配数据库，别再绕远路去自建一台远程库：D1 就在同一个平台上，建库一条命令、绑定三行配置、查询就是 &lt;code&gt;prepare&lt;/code&gt; 加 &lt;code&gt;bind&lt;/code&gt;，本地与远程两套环境靠迁移保持一致，误删数据还有 Time Travel 和 SQL 导出两层兜底。免费额度对个人项目相当宽裕。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;能用 SQL 表达的结构化数据，就放进 D1；只存当前状态的小东西，留给 KV。&amp;lt;/span&amp;gt;两件工具都绑在同一个 Worker 上，轻量后端需要的数据层就齐了。
&amp;lt;/span&amp;gt;&lt;/p&gt;
</content:encoded></item><item><title>DNS 记录详解与常见坑</title><link>https://www.anexns.cloudns.org/posts/cloudflare-dns-records/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-dns-records/</guid><description>A、AAAA、CNAME、MX、TXT 每种记录到底管什么：根域 CNAME 展平、邮箱三件套 SPF/DKIM/DMARC、代理状态对 TTL 的影响，以及 dig 验证与最常见的五种配错。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;上一篇&lt;a href=&quot;/posts/cloudflare-getting-started/&quot;&gt;《域名接入 Cloudflare》&lt;/a&gt;把域名搬进了 Cloudflare，NS 也切过来了。但接入只是第一步，真正决定网站能不能打开、邮件能不能送达的，是 DNS 记录配得对不对。DNS 记录是全站最不起眼、又最容易配错的一层：一条 CNAME 写错，网站打不开；一条 MX 漏配，公司邮箱集体失联；TXT 记录随手删掉，域名所有权验证失效，服务说停就停。&lt;/p&gt;
&lt;p&gt;这篇把 Cloudflare 里最常用的记录类型一次讲透：每种记录管什么、能不能开代理、名称字段怎么写才不出错、CNAME 的规矩、TTL 的真实作用、邮箱三件套 SPF/DKIM/DMARC 的标准写法，最后给一组 dig 验证命令和五种最常见配错的排障方法。读完这一篇，你应该能对着任何一张 DNS 记录表说出每条记录的用途，也能在出问题时自己先定位到是哪一层错了。&lt;/p&gt;
&lt;h2&gt;记录类型总表：先一张表讲完&lt;/h2&gt;
&lt;p&gt;在 Cloudflare 控制台「DNS → 记录」页面点「添加记录」，类型下拉框里能选的远不止 A 和 CNAME。但日常真正用得到的就下面这几种，先建立全景概念：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;管什么&lt;/th&gt;
&lt;th&gt;典型值&lt;/th&gt;
&lt;th&gt;能否开代理（橙云）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;A&lt;/td&gt;
&lt;td&gt;域名指向一个 IPv4 地址&lt;/td&gt;
&lt;td&gt;&lt;code&gt;203.0.113.10&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;可以&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;AAAA&lt;/td&gt;
&lt;td&gt;域名指向一个 IPv6 地址&lt;/td&gt;
&lt;td&gt;&lt;code&gt;2606:4700::6810:85e5&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;可以&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;CNAME&lt;/td&gt;
&lt;td&gt;域名指向另一个域名（别名）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;example.github.io&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;可以&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MX&lt;/td&gt;
&lt;td&gt;邮件由哪台服务器接收&lt;/td&gt;
&lt;td&gt;&lt;code&gt;mx.example.net&lt;/code&gt;，带优先级&lt;/td&gt;
&lt;td&gt;不能，只能灰云&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TXT&lt;/td&gt;
&lt;td&gt;任意文本：验证、邮箱策略等&lt;/td&gt;
&lt;td&gt;&lt;code&gt;v=spf1 ...&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不能，只能灰云&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;CAA&lt;/td&gt;
&lt;td&gt;只允许哪些 CA 给本域名签证书&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 issue &quot;letsencrypt.org&quot;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不能，只能灰云&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;NS&lt;/td&gt;
&lt;td&gt;把子域名的解析权委托给别的 DNS&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ns1.otherdns.com&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不能，只能灰云&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个要点先记住：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;只有 A、AAAA、CNAME 三种记录能开代理&lt;/strong&gt;。因为代理的本质是 Cloudflare 替你把这条记录的解析结果换成自己的边缘节点地址，只对「指向网站服务器」的记录有意义。MX、TXT 这类记录如果被代理改了值，邮件和验证就直接坏掉，所以 Cloudflare 根本不给开。&lt;/li&gt;
&lt;li&gt;A 和 AAAA 的区别只有地址版本，一个域名可以同时有 A 和 AAAA，访问者网络支持哪个就走哪个。只配 A 不配 AAAA，IPv6 用户会绕一圈或直接连不上；服务器有 IPv6 地址就把 AAAA 一起配上。&lt;/li&gt;
&lt;li&gt;CAA 平时用不到，但配了就有约束力：它声明「只有名单里的 CA 能给我的域名签发证书」。如果以后申请证书总是失败，先回来看看是不是 CAA 把那家 CA 挡在外面了。&lt;/li&gt;
&lt;li&gt;NS 记录出现在主域名上时是 Cloudflare 自动管理的，不要手动改；它真正的用途是&lt;strong&gt;子域名委托&lt;/strong&gt;——比如把 &lt;code&gt;dev.example.com&lt;/code&gt; 的解析整体交给另一家 DNS 服务商管理，就给 &lt;code&gt;dev&lt;/code&gt; 加 NS 记录指向对方的服务器。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;名称字段的写法：@、前缀与双后缀坑&lt;/h2&gt;
&lt;p&gt;每条记录都有「名称」一栏，这是新手翻车率最高的地方。规则其实只有三条：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;@&lt;/code&gt; 代表根域名本身&lt;/strong&gt;。想让 &lt;code&gt;example.com&lt;/code&gt; 能访问，名称就填 &lt;code&gt;@&lt;/code&gt;；控制台列表里通常直接显示为域名本身。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;子域名只写前缀&lt;/strong&gt;。想配 &lt;code&gt;blog.example.com&lt;/code&gt;，名称只填 &lt;code&gt;blog&lt;/code&gt;，不要填全名。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;不要在名称里再写完整域名&lt;/strong&gt;。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;名称填 &lt;code&gt;www.example.com&lt;/code&gt;，实际生效的会是 &lt;code&gt;www.example.com.example.com&lt;/code&gt;&amp;lt;/span&amp;gt;——系统会自动把主域名后缀拼在你填的名称后面。这种「双后缀」记录在列表里乍一看没问题，但解析永远落不到你以为的那个域名上，排障时极难发现。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;举个对照：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;想配的域名&lt;/th&gt;
&lt;th&gt;名称填什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;example.com&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;@&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;www.example.com&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;www&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;api.dev.example.com&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;api.dev&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;还有一个细节：名称支持通配符 &lt;code&gt;*&lt;/code&gt;，比如给 &lt;code&gt;*&lt;/code&gt; 配一条 A 记录，所有未被单独定义的子域名都会走它。它是兜底，不是主力——具体子域名有单独记录时，单独记录优先，这个特性在排障小节还会再遇到。&lt;/p&gt;
&lt;h2&gt;CNAME 的规矩：独占、展平与连锁影响&lt;/h2&gt;
&lt;p&gt;CNAME 是「别名」：它不直接指向 IP，而是指向另一个域名，解析时顺着目标域名再查下去，直到查到 A 或 AAAA 为止。用托管服务时最常见，比如博客托管在 GitHub Pages，就把 &lt;code&gt;blog&lt;/code&gt; 用 CNAME 指向 &lt;code&gt;用户名.github.io&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;规矩一：同名独占，不能与其他记录共存&lt;/h3&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;一个名称一旦有了 CNAME，就不能再有任何其他类型的记录。&amp;lt;/span&amp;gt;这是 DNS 协议层面的硬规定，不是 Cloudflare 的限制。比如 &lt;code&gt;blog&lt;/code&gt; 已经有 CNAME，就不能再给 &lt;code&gt;blog&lt;/code&gt; 加 TXT 做验证，也不能加 MX。控制台在你冲突添加时会直接报错，这类报错在排障部分会讲。&lt;/p&gt;
&lt;p&gt;推论：如果某个子域名既要做网站别名、又要收邮件、又要加验证记录，那就不能用 CNAME，只能用 A/AAAA 直接指向 IP。&lt;/p&gt;
&lt;h3&gt;规矩二：根域名本来不能配 CNAME，Cloudflare 用展平绕过&lt;/h3&gt;
&lt;p&gt;按协议，根域名（&lt;code&gt;@&lt;/code&gt;）必须有 NS 和 SOA 记录，而 CNAME 又要求同名独占，两者冲突，所以传统 DNS 里根域名不能配 CNAME。但现实需求很常见：网站托管在只给域名不给固定 IP 的平台上，根域名也想指过去。&lt;/p&gt;
&lt;p&gt;Cloudflare 的解法叫 &lt;strong&gt;CNAME 展平（CNAME Flattening）&lt;/strong&gt;：你在根域名配一条 CNAME，Cloudflare 在后台实时把目标解析成 IP，再以 A 记录的形式返回给访问者。对外看起来根域名返回的是 IP，协议合规；对内你享受的还是 CNAME 跟随目标变化的便利。Cloudflare 默认对根域名的 CNAME 启用展平，子域名的 CNAME 也可以在设置里选择展平。&lt;/p&gt;
&lt;h3&gt;规矩三：指向别人，就要接受连锁影响&lt;/h3&gt;
&lt;p&gt;CNAME 的便利是「目标变，我自动跟着变」，代价也是这个：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;目标域名解析挂了，你的域名跟着挂，且错误不在你这边；&lt;/li&gt;
&lt;li&gt;目标域名被转手、被停用，你的记录会指向一个已经不属于原主的地址；&lt;/li&gt;
&lt;li&gt;链条不要套太长：CNAME 指向 CNAME 再指向 CNAME，解析要多绕几跳，慢且容易在某一环断掉。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;另外两个硬规矩：&lt;strong&gt;MX 和 NS 记录的目标不能是 CNAME&lt;/strong&gt;，必须是能直接查到 A/AAAA 的主机名；自己给别人当目标时也一样，别让下游拿 CNAME 指你一个本身就是 CNAME 的名字。&lt;/p&gt;
&lt;h2&gt;TTL 详解：什么时候你说了算，什么时候不算&lt;/h2&gt;
&lt;p&gt;TTL（Time to Live）是这条记录能在各级缓存里存活的秒数。TTL 越大，解析越快、改记录生效越慢；TTL 越小，切换越灵活，但解析请求更频繁。&lt;/p&gt;
&lt;p&gt;在 Cloudflare 里，TTL 是否由你说了算，取决于代理状态：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;状态&lt;/th&gt;
&lt;th&gt;TTL 表现&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;灰云（仅 DNS）&lt;/td&gt;
&lt;td&gt;你设多少就是多少&lt;/td&gt;
&lt;td&gt;可选范围以控制台为准，可低至几十秒&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;橙云（已代理）&lt;/td&gt;
&lt;td&gt;固定为「自动」，你改不了&lt;/td&gt;
&lt;td&gt;Cloudflare 要保证随时能调度边缘节点&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;橙云时 TTL 不生效的原因不难理解：访问者查到的根本不是你的源站地址，而是 Cloudflare 边缘节点的地址，这批地址的调度权必须握在 Cloudflare 手里，不可能让某个站长把 TTL 设成一天、把调度锁死。所以代理记录的 TTL 在控制台里是灰色的「自动」，解析出去的值由 Cloudflare 决定。&lt;/p&gt;
&lt;h3&gt;改记录前的标准手法：先调低 TTL&lt;/h3&gt;
&lt;p&gt;这是运维里最实用的一招。计划迁移服务器、换 IP 之前：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;提前至少一个旧 TTL 周期（旧 TTL 是 3600 就提前 1 小时以上，是一天就提前一天），把记录改成灰云或把 TTL 调到 60–300 秒；&lt;/li&gt;
&lt;li&gt;等旧 TTL 在全网缓存里自然过期，所有解析器都开始按新 TTL 缓存；&lt;/li&gt;
&lt;li&gt;正式切换 IP，此时全网最多几分钟就全部指向新地址；&lt;/li&gt;
&lt;li&gt;确认稳定后，再把 TTL 调回正常值。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;跳过这一步直接换 IP，旧缓存会在全球各地继续把流量送往已下线的旧服务器，而且你无能为力，只能等。&amp;lt;/span&amp;gt;这不是 Cloudflare 的问题，是 DNS 缓存机制本身如此。&lt;/p&gt;
&lt;h2&gt;邮箱三件套：MX、SPF、DKIM、DMARC&lt;/h2&gt;
&lt;p&gt;只要你的域名要收发邮件，下面四类记录就是必修课。先强调共同点：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;邮箱相关记录全部保持灰云（仅 DNS），一个都不能开代理。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h3&gt;MX：邮件投递到哪&lt;/h3&gt;
&lt;p&gt;MX 记录告诉全世界「发给 &lt;code&gt;@example.com&lt;/code&gt; 的邮件请投递到这台服务器」。它带一个&lt;strong&gt;优先级&lt;/strong&gt;数字，数字越小优先级越高：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;名称: @
类型: MX
目标: mx1.example.net
优先级: 10

名称: @
类型: MX
目标: mx2.example.net
优先级: 20
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;发件方先投优先级 10 的那台，连不上再投 20 的备用。MX 的目标必须是主机名、不能是 IP，也不能是 CNAME（见上一节）。邮箱服务商（企业邮箱、Google Workspace、Microsoft 365 等）都会给你一组现成的 MX 值，照抄即可，不要自己编。&lt;/p&gt;
&lt;h3&gt;SPF：谁有权用我的域名发信&lt;/h3&gt;
&lt;p&gt;SPF 是一条 TXT 记录，列出「哪些服务器被授权以本域名名义发信」。收件方查到这条记录，就能判断来信的服务器在不在名单里。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;名称: @
类型: TXT
内容: v=spf1 include:_spf.google.com -all
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;读法：&lt;code&gt;v=spf1&lt;/code&gt; 是版本声明，必须打头；&lt;code&gt;include:&lt;/code&gt; 引入服务商的授权名单（用哪家邮箱就抄哪家给的值）；结尾的判定符最关键：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;结尾&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;建议&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-all&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;名单外一律视为伪造（硬失败）&lt;/td&gt;
&lt;td&gt;正式使用推荐&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;~all&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;名单外标记为可疑（软失败）&lt;/td&gt;
&lt;td&gt;调试期临时用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;?all&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不表态&lt;/td&gt;
&lt;td&gt;等于没设，别用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;注意 SPF 有 &lt;strong&gt;10 次 DNS 查询次数上限&lt;/strong&gt;，include 套 include 很容易超限，超限后 SPF 直接失效。发信渠道每加一个就回来数一遍，别无节制地堆。&lt;/p&gt;
&lt;h3&gt;DKIM：给每封信盖防伪签名&lt;/h3&gt;
&lt;p&gt;DKIM 让发信服务器用私钥给邮件签名，收件方用你 DNS 里公布的公钥验签，签名对得上就证明邮件确实出自你的系统、且中途没被改过。它通常是一条带「选择器」前缀的记录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;名称: google._domainkey
类型: CNAME（或 TXT，视服务商而定）
目标: 服务商给出的地址
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;或者直接是 TXT 形式：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;名称: s1._domainkey
类型: TXT
内容: v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;p=&lt;/code&gt; 后面那一长串公钥由邮箱服务商生成，&lt;strong&gt;整段复制，一个字符都不能错&lt;/strong&gt;，也不要自己手敲。DKIM 要先在邮箱后台开启并生成记录，再回 Cloudflare 添加，最后回邮箱后台点验证，三步缺一不可。&lt;/p&gt;
&lt;h3&gt;DMARC：有人冒充我发信时怎么办&lt;/h3&gt;
&lt;p&gt;DMARC 同样是 TXT，挂在 &lt;code&gt;_dmarc&lt;/code&gt; 这个固定名称下，它把 SPF 和 DKIM 的结果汇总成一条处置策略：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;名称: _dmarc
类型: TXT
内容: v=DMARC1; p=none; rua=mailto:dmarc-reports@example.com
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;p=none&lt;/code&gt;：只观察、不拦截，报告发到 &lt;code&gt;rua&lt;/code&gt; 指定的邮箱——这是起步阶段的正确姿势；&lt;/li&gt;
&lt;li&gt;运行几周，确认自己所有发信渠道的 SPF/DKIM 都对齐了，再升级到 &lt;code&gt;p=quarantine&lt;/code&gt;（进垃圾箱）；&lt;/li&gt;
&lt;li&gt;最后升到 &lt;code&gt;p=reject&lt;/code&gt;（直接拒收），冒充你域名的钓鱼邮件才算被真正掐断。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;一上来就写 &lt;code&gt;p=reject&lt;/code&gt; 是常见错误：某个被遗忘的第三方发信渠道（账单系统、营销平台）没配好对齐，会先被你自己的策略误杀。&lt;/p&gt;
&lt;p&gt;:::warning
邮箱四件套有个共同的隐形要求：一个域名只能有一条 SPF 记录、一套 DMARC 记录。换邮箱服务商时要做的是&lt;strong&gt;修改&lt;/strong&gt;现有记录，把新服务商的 include 合并进去，而不是再新增一条。两条 SPF 并存的结果是两条一起失效。
:::&lt;/p&gt;
&lt;h2&gt;验证所有权类 TXT：不起眼，但别乱删&lt;/h2&gt;
&lt;p&gt;DNS 列表里经常躺着一些你不认识的 TXT 记录，名字可能长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;名称: @
类型: TXT
内容: google-site-verification=xxxxxxxxxxxxxxxx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;或者 &lt;code&gt;_vercel&lt;/code&gt;、&lt;code&gt;_github-challenge&lt;/code&gt; 之类带下划线前缀的记录。它们是各家服务验证「这个域名确实归你」的凭证：搜索引擎站长平台、托管平台、证书签发机构都会用这种方式。&lt;/p&gt;
&lt;p&gt;这类记录的共同特点是：&lt;strong&gt;配完之后长期有效，删掉就等于告诉对方「我不再拥有这个域名」&lt;/strong&gt;，轻则站点统计断档，重则托管服务停摆、证书续签失败。清理 DNS 记录时，凡是 TXT 类型又看不懂内容的，先查清楚来源再动，不要按「不认识就删」的原则处理。&lt;/p&gt;
&lt;h2&gt;dig 验证：改完记录自己先查一遍&lt;/h2&gt;
&lt;p&gt;控制台里显示「已保存」不等于全世界已经按新记录解析。养成改完记录用 dig 亲手验一遍的习惯，常用命令就这一组：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 查 A 记录（最常用，+short 只看结果）
dig example.com A +short

# 查 AAAA / CNAME / MX / TXT，把类型换掉即可
dig example.com MX +short
dig _dmarc.example.com TXT +short

# 指定用 Cloudflare 的公共解析器查，排除本地运营商缓存的干扰
dig @1.1.1.1 example.com A

# 看完整应答，包括 TTL 还剩多少秒
dig @1.1.1.1 example.com A
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;没有 dig 的 Windows 环境用 nslookup 代替：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;nslookup example.com 1.1.1.1
nslookup -type=TXT _dmarc.example.com 1.1.1.1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;看结果时重点看两个地方：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;应答里的 IP/目标对不对&lt;/strong&gt;。橙云记录查到的应该是 Cloudflare 的边缘地址而不是源站 IP，这是正常现象；灰云记录查到的必须是你配的源站地址。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;TTL 是否在递减&lt;/strong&gt;。连查两次，TTL 数字变小，说明你命中的是缓存，正在按秒倒计时；等它归零后才会回源拿新记录。刚改完记录查到旧值，先看 TTL 剩多少再决定要不要继续等，而不是立刻怀疑配置错了。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;查 NS 用 &lt;code&gt;dig example.com NS +short&lt;/code&gt;，结果应该是 Cloudflare 分配的那两台服务器。如果查出来还是原注册商的 NS，说明上一篇讲的 NS 切换还没生效，改任何记录都不会起作用，先回去等切换完成。&lt;/p&gt;
&lt;h2&gt;排障：最常见的五种配错&lt;/h2&gt;
&lt;h3&gt;一、记录配了不生效&lt;/h3&gt;
&lt;p&gt;按顺序排查，别乱跳：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;用 dig @1.1.1.1 查，确认是解析层没变还是应用层没变；&lt;/li&gt;
&lt;li&gt;看 TTL 倒计时，判断是不是旧缓存还没过期（等就行）；&lt;/li&gt;
&lt;li&gt;确认改的是正确的那条记录——同域名下 A 和 AAAA 是两条，改了 A 忘了 AAAA，IPv6 访客还在走旧地址；&lt;/li&gt;
&lt;li&gt;确认域名 NS 真的在 Cloudflare（dig NS 验证），在别处托管时这边改什么都没用。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;二、同名记录冲突报错&lt;/h3&gt;
&lt;p&gt;添加记录时提示冲突，几乎都是撞上了 CNAME 独占规则：该名称已有 CNAME，或你正要加的 CNAME 与已有记录打架。解法只有两个：删掉冲突记录，或者放弃 CNAME、改用 A/AAAA 直接指向 IP。邮箱和验证记录多的子域名，优先用后者。&lt;/p&gt;
&lt;h3&gt;三、灰云暴露源站 IP&lt;/h3&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;网站主记录开了橙云，却给同一个源站的其他子域名留了灰云记录，等于把源站 IP 公开写在 DNS 里。&amp;lt;/span&amp;gt;攻击者不需要打你的域名，绕过 Cloudflare 直接打 IP 即可，前面所有防护形同虚设。典型泄漏源：&lt;code&gt;ftp&lt;/code&gt;、&lt;code&gt;mail&lt;/code&gt;、&lt;code&gt;direct&lt;/code&gt;、测试子域名，以及 MX 目标主机名恰好和网站在同一台服务器。自查方法：把域名下所有灰云记录的目标列出来，凡是指向源站 IP 的都要评估——能代理的改橙云，必须灰云的（如邮件）尽量让它落在另一台机器上。&lt;/p&gt;
&lt;h3&gt;四、子域名解析到错误地址&lt;/h3&gt;
&lt;p&gt;某个从没配过的子域名居然能解析，多半是通配符记录 &lt;code&gt;*&lt;/code&gt; 在兜底，它会把所有未定义子域名统一指向同一个地址。反过来，某个子域名「改了不听话」，先检查它是不是被通配符和单独记录的优先级绕晕了：有单独记录时单独记录生效，没有时才轮到通配符。还有一类是子域名被 NS 委托出去了，这时在 Cloudflare 里给它加 A 记录完全无效，要去被委托的那家改。&lt;/p&gt;
&lt;h3&gt;五、邮件进垃圾箱甚至被拒收&lt;/h3&gt;
&lt;p&gt;按这个顺序查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code&gt;dig 域名 MX +short&lt;/code&gt; 确认 MX 在、且是灰云；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;dig 域名 TXT +short&lt;/code&gt; 看 SPF 在不在、是不是不小心存了两条；&lt;/li&gt;
&lt;li&gt;查 DKIM 记录在不在，并回邮箱后台确认 DKIM 状态是「已通过」而不是只生成了记录；&lt;/li&gt;
&lt;li&gt;查 &lt;code&gt;_dmarc&lt;/code&gt; 记录，从 &lt;code&gt;p=none&lt;/code&gt; 的报告里能看到底是哪个渠道在裸奔；&lt;/li&gt;
&lt;li&gt;反查发信 IP 是否进了公开黑名单，这一步和 DNS 配置无关，但症状一模一样，别漏。&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;记录类型里只有 A、AAAA、CNAME 能开代理，邮箱与验证类记录全部灰云；&lt;/li&gt;
&lt;li&gt;名称只写前缀，&lt;code&gt;@&lt;/code&gt; 是根域名，写全域名会拼出双后缀；&lt;/li&gt;
&lt;li&gt;CNAME 同名独占，根域名靠 Cloudflare 的展平功能绕过协议限制；&lt;/li&gt;
&lt;li&gt;橙云时 TTL 由 Cloudflare 接管，灰云时才是你说了算；换 IP 前先把 TTL 调低是标准动作；&lt;/li&gt;
&lt;li&gt;邮箱四件套 MX、SPF、DKIM、DMARC 缺一不可，DMARC 从 &lt;code&gt;p=none&lt;/code&gt; 起步、确认对齐后再逐步收紧；&lt;/li&gt;
&lt;li&gt;看不懂的 TXT 验证记录不要删；&lt;/li&gt;
&lt;li&gt;改完记录用 dig @1.1.1.1 亲手验一遍，看目标对不对、TTL 在不在倒计时。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;下一篇讲 SSL/TLS：解析已经通了，接下来把「访问者到 Cloudflare」和「Cloudflare 到源站」这两段加密都配对，灵活模式那个著名的重定向死循环坑，就在那里等着。&lt;/p&gt;
</content:encoded></item><item><title>Email Routing：免费域名邮箱转发</title><link>https://www.anexns.cloudns.org/posts/cloudflare-email-routing/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-email-routing/</guid><description>有域名就能有自己的域名邮箱：Email Routing 把发到你域名地址的邮件自动转发到常用邮箱，全程讲清开启、规则、Catch-all 与验证，再划清它只能收不能发的边界。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;上一篇把 DNS 记录讲透了，其中 MX、SPF、DKIM、DMARC 这邮箱四件套只是顺带提了一嘴。这一篇把其中最实用的一块单独拎出来做成完整教程：&lt;strong&gt;你有一个域名，就能立刻拥有 &lt;code&gt;xxx@你的域名&lt;/code&gt; 这样的邮箱地址&lt;/strong&gt;，别人发到这个地址的邮件，会被 Cloudflare 自动转发到你天天在用的 Gmail、QQ 邮箱里。不用买企业邮箱，不用租服务器，不用装任何软件，全程在控制台点几下就能开通，而且免费。&lt;/p&gt;
&lt;p&gt;先把主线交代清楚：这一篇先讲域名邮箱为什么值得有、自建邮件服务器为什么不值得碰；再讲 Email Routing 的定位和它那条必须先说清的边界；然后是完整的开启流程——它会自动往你的 DNS 里加哪几条记录、和已有邮箱服务撞车了怎么办；接着是目标地址验证、转发规则、Catch-all 全收这三个核心配置；最后讲使用纪律和排障。看完这一篇，你的域名邮箱就能正式对外用了。&lt;/p&gt;
&lt;h2&gt;一、为什么值得有一个域名邮箱&lt;/h2&gt;
&lt;p&gt;先说价值，再说实现。域名邮箱解决的是三个很实际的问题。&lt;/p&gt;
&lt;p&gt;第一是&lt;strong&gt;对外形象&lt;/strong&gt;。给客户、合作方或者开源社区留联系方式时，&lt;code&gt;contact@anexns.com&lt;/code&gt; 和 &lt;code&gt;anexns1998@qq.com&lt;/code&gt; 给人的感觉完全不同。前者一看就是「这个人有自己的站、是认真在做事」，后者则像个随手注册的账号。简历、名片、博客关于页、GitHub 主页，凡是要对外示人的地方，域名邮箱都是成本最低的专业感来源——因为域名你本来就有，剩下的只是几分钟配置。&lt;/p&gt;
&lt;p&gt;第二是&lt;strong&gt;按用途分地址&lt;/strong&gt;。有了自己的域名，地址前缀想编什么就编什么：注册代码托管用 &lt;code&gt;github@&lt;/code&gt;，网购用 &lt;code&gt;shop@&lt;/code&gt;，订阅资讯用 &lt;code&gt;news@&lt;/code&gt;，对外联系用 &lt;code&gt;hello@&lt;/code&gt;。每个地址对应一类用途，收件箱里一眼就能看出这封邮件是从哪个渠道来的。更关键的是止损：哪个地址开始收到垃圾邮件了，说明它在哪个环节泄露了，单独把那一条转发规则停掉就行，其他地址毫发无损。这一条后面第六节还会展开讲。&lt;/p&gt;
&lt;p&gt;第三是&lt;strong&gt;不暴露真名邮箱&lt;/strong&gt;。你的主邮箱往往绑着银行卡、支付、各种账号的找回通道，是绝不能到处乱填的资产。用域名地址在外面行走，主邮箱藏在转发链的末端不露面，安全边界一下子就清晰了。&lt;/p&gt;
&lt;p&gt;那为什么不干脆自建一台邮件服务器，把收发全捏在自己手里？这里要劝退一下。自建邮件服务器是运维领域公认的深坑：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;发信信誉从零开始&lt;/strong&gt;。新 IP 没有任何历史信誉，各大邮箱厂商默认不信任，辛辛苦苦发出去的信大半进垃圾箱，甚至直接被拒收。养信誉要以月为单位，还得时刻提防 IP 被拉黑。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;配置项又多又碎&lt;/strong&gt;。Postfix、Dovecot、SPF、DKIM、DMARC、PTR 反向解析、TLS 证书，任何一项配错都收发异常，而且很多问题是静默的——信没了，你都不知道。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;维护是持续成本&lt;/strong&gt;。垃圾邮件过滤、队列堵塞、被人当开放中继滥用、系统升级把配置冲掉，每一样都要人盯着。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;结论很简单：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;个人和小团队场景，收信交给转发、发信交给专业服务，自己永远不要碰邮件服务器&amp;lt;/span&amp;gt;。Email Routing 正是这个思路下收信那一半的答案。&lt;/p&gt;
&lt;h2&gt;二、Email Routing 的定位与边界&lt;/h2&gt;
&lt;p&gt;先把丑话说在前面，免得配完之后发现不是自己想要的东西。&lt;/p&gt;
&lt;p&gt;Email Routing 是 Cloudflare 提供的一个&lt;strong&gt;纯转发&lt;/strong&gt;服务：别人给你的域名地址发信，Cloudflare 收到后，按你预设的规则把邮件转投到你的真实邮箱里。它不在自己的服务器上长期保存你的邮件，没有网页版收件箱，没有 App，你最终还是在 Gmail、QQ 邮箱这些原有客户端里读信。它做的事情只有一件，就是「换个地址收信」。&lt;/p&gt;
&lt;p&gt;边界同样只有一条，但必须刻在脑子里：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Email Routing 只能收信，不能发信&amp;lt;/span&amp;gt;。你没法用 &lt;code&gt;hello@你的域名&lt;/code&gt; 作为发件人给别人写信，回复邮件时对方看到的依然是你真实邮箱的地址。需要以域名地址发信的场景——比如给客户回函、发通知邮件——得另外配发送型服务，或者用 Gmail 的「以其他地址发送」这类功能借道，第八节会再点一下这条出路。本篇的定位就是把「收」这件事做到极致，发的部分不在它的能力范围内，期望先对齐。&lt;/p&gt;
&lt;p&gt;它适合的场景和不适合的场景，对照着看最清楚：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;适不适合&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;博客、个人站的联系邮箱&lt;/td&gt;
&lt;td&gt;适合&lt;/td&gt;
&lt;td&gt;收信量小，转发绰绰有余&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;按服务分地址注册账号&lt;/td&gt;
&lt;td&gt;适合&lt;/td&gt;
&lt;td&gt;规则随便加，停用一条就止损&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;团队共用一个对外地址&lt;/td&gt;
&lt;td&gt;适合&lt;/td&gt;
&lt;td&gt;一条规则可转给多个成员&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每天几百封业务往来邮件&lt;/td&gt;
&lt;td&gt;勉强&lt;/td&gt;
&lt;td&gt;能收，但无归档、无管理后台&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;需要以域名地址对外发信&lt;/td&gt;
&lt;td&gt;不适合&lt;/td&gt;
&lt;td&gt;它没有发信能力，得另配服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;需要邮箱别名群发、自动回复&lt;/td&gt;
&lt;td&gt;不适合&lt;/td&gt;
&lt;td&gt;这是完整邮箱产品的功能&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;另外提醒一句前提：Email Routing 要求域名的 DNS 托管在 Cloudflare，也就是你已经完成了本系列第一篇的域名接入。如果域名解析还在别家，要么先迁过来，要么就用不了这个功能。&lt;/p&gt;
&lt;h2&gt;三、开启流程：它往你的 DNS 里加了什么&lt;/h2&gt;
&lt;p&gt;开启入口在 Cloudflare 控制台：选中你的域名，左侧菜单进入「电子邮件 → Email Routing」，点启用。整个过程控制台会带着你走，但每一步在干什么，心里要有数。&lt;/p&gt;
&lt;h3&gt;3.1 自动添加的记录&lt;/h3&gt;
&lt;p&gt;启用时，Cloudflare 会提议往你的域名里添加一组记录，核心是这几条：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;记录类型&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;MX&lt;/td&gt;
&lt;td&gt;告诉全世界「这个域名的信投到 Cloudflare」&lt;/td&gt;
&lt;td&gt;会加多条不同优先级的 MX，指向 Cloudflare 的收信服务器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TXT（SPF）&lt;/td&gt;
&lt;td&gt;声明哪些服务器有权以本域名身份处理邮件&lt;/td&gt;
&lt;td&gt;内容形如 &lt;code&gt;v=spf1 include:_spf.mx.cloudflare.net ~all&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TXT（DKIM 相关）&lt;/td&gt;
&lt;td&gt;给转发出去的邮件做签名背书&lt;/td&gt;
&lt;td&gt;控制台自动生成，不要手改&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这几条记录的通用知识——MX 优先级怎么排、SPF 的 &lt;code&gt;~all&lt;/code&gt; 和 &lt;code&gt;-all&lt;/code&gt; 差在哪——在 &lt;a href=&quot;/posts/cloudflare-dns-records/&quot;&gt;DNS 记录详解与常见坑&lt;/a&gt; 里已经逐条讲过，这里不重复。只强调一个动作：&lt;strong&gt;点确认之前，把控制台列出的待添加记录和你现有的记录对一遍&lt;/strong&gt;，尤其是 MX 那几条。为什么？看下一小节。&lt;/p&gt;
&lt;h3&gt;3.2 与已有邮箱服务冲突怎么办&lt;/h3&gt;
&lt;p&gt;MX 记录决定了全世界往你域名发信时投递到哪套系统，而&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;同一个域名的 MX 只能实质指向一套收信体系&amp;lt;/span&amp;gt;。如果你这个域名之前已经在用别的邮箱服务——比如挂着腾讯企业邮、Google Workspace，或者某个自建邮箱——启用 Email Routing 就会要求你删掉旧的 MX 记录。两套 MX 混在一起的结果不是「双保险」，而是投递按优先级乱走：有的信进了旧邮箱，有的信进了转发链，丢信、漏信全是这么来的，而且排查时极难定位。&lt;/p&gt;
&lt;p&gt;:::warning
启用前先确认：这个域名现在有没有正在用的邮箱服务？有，就先想清楚是整体迁移到转发模式，还是保留原服务放弃 Email Routing——两者只能选一个。旧服务里如果还存着重要邮件，先导出备份再动 MX。
:::&lt;/p&gt;
&lt;p&gt;反过来，如果这个域名从没配过邮箱，DNS 里干干净净，那启用过程就是一路确认，记录自动落地，几分钟后 MX 在全球生效，就可以进下一步了。&lt;/p&gt;
&lt;h2&gt;四、目标地址：先验证，才收得到&lt;/h2&gt;
&lt;p&gt;转发规则是「域名地址 → 目标地址」的映射，而目标地址——也就是你真正读信的那个邮箱——&lt;strong&gt;必须先添加并通过验证，才能被规则引用&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;操作在 Email Routing 设置里的「目标地址（Destination addresses）」中：填入你的常用邮箱，Cloudflare 会往那个邮箱发一封验证邮件，你打开邮件点里面的确认链接，这个目标地址才算激活。&lt;/p&gt;
&lt;p&gt;这里有个高频翻车点：很多人规则配了一大堆，测试时一封都收不到，回头查半天，最后发现&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;目标地址的那封验证邮件躺在垃圾箱里从来没点过&amp;lt;/span&amp;gt;。未验证的目标地址等于不存在，规则指向它就等于指向空气。记住顺序：&lt;strong&gt;先加目标、点验证、再配规则&lt;/strong&gt;，三步别颠倒。验证邮件没收到时，先去垃圾箱和广告邮件分类里翻，再考虑重发。&lt;/p&gt;
&lt;p&gt;一个账号下可以添加多个目标地址，团队场景里每个人的邮箱各加一个，后面配规则时就能灵活组合。&lt;/p&gt;
&lt;h2&gt;五、转发规则：地址与目标的映射&lt;/h2&gt;
&lt;p&gt;目标就绪后，在「路由规则（Routing rules）」里新建规则。每条规则就两个要素：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;自定义地址&lt;/strong&gt;：你对外公布的域名地址，比如 &lt;code&gt;hello@anexns.com&lt;/code&gt;，前缀部分自己填。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;操作与目标&lt;/strong&gt;：选择「发送到电子邮件」，再选一个或多个已验证的目标地址。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;几个实用细节：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;一个地址可以转给多个人。&lt;/strong&gt; 比如 &lt;code&gt;support@&lt;/code&gt; 同时转给两个成员的邮箱，谁有空谁处理，不需要共享账号密码，这是转发模式比真邮箱还方便的地方之一。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;规则可以随时停用。&lt;/strong&gt; 每条规则旁边有启用/停用开关。某个地址暂时不想收了，停用即可，不用删——删了重建还得重填，停用是可逆的。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;规则之外还有默认动作。&lt;/strong&gt; 没被任何规则命中的地址，默认是直接丢弃（拒收）。也就是说你只公布了 &lt;code&gt;hello@&lt;/code&gt;，别人往 &lt;code&gt;abc@你的域名&lt;/code&gt; 发信是投不进来的。这个默认行为是好事，它意味着你的地址体系是白名单制的，自己没建的地址不存在。唯一的例外是下一节的 Catch-all，它会把这个默认行为整个翻过来。&lt;/p&gt;
&lt;p&gt;建好规则后立刻自测：用另一个邮箱（或者让朋友帮忙）往新地址发一封测试信，确认能落进目标邮箱，且发件人、主题、正文都完整。转发链上偶尔会有格式小问题，趁没对外公布先验掉。&lt;/p&gt;
&lt;h2&gt;六、Catch-all：全收的诱惑与代价&lt;/h2&gt;
&lt;p&gt;Catch-all（全收）是 Email Routing 里一个开关型的功能：打开之后，&lt;strong&gt;任意前缀&lt;/strong&gt;的地址都能收信。&lt;code&gt;a@&lt;/code&gt;、&lt;code&gt;xyz123@&lt;/code&gt;、别人随手编的 &lt;code&gt;boss@&lt;/code&gt;，统统按你指定的目标转发进来。&lt;/p&gt;
&lt;p&gt;它的正经用途是防手误和防漏配：有人把你的地址记错了一个字母，信也不至于退回；临时需要一个新地址时，不用回控制台加规则，张口就能报出一个新地址，回来再补规则。&lt;/p&gt;
&lt;p&gt;但代价必须看清：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Catch-all 打开后，你的域名等于向全网垃圾邮件敞开了大门&amp;lt;/span&amp;gt;。发垃圾邮件的人最爱拿字典扫域名前缀，&lt;code&gt;admin@&lt;/code&gt;、&lt;code&gt;info@&lt;/code&gt;、&lt;code&gt;sales@&lt;/code&gt; 这些常见前缀会被逐个试投，你的目标邮箱会被广告、钓鱼、诈骗邮件持续灌入，而且因为前缀是无限的，你没法靠停规则来止损——除非把 Catch-all 整个关掉。&lt;/p&gt;
&lt;p&gt;给个明确建议：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;你的情况&lt;/th&gt;
&lt;th&gt;建议&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;域名新、没什么人知道&lt;/td&gt;
&lt;td&gt;可以开，图省事，量起来了再关&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;域名已公开运营、流量不小&lt;/td&gt;
&lt;td&gt;别开，按需逐条建规则&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;已经被垃圾邮件盯上&lt;/td&gt;
&lt;td&gt;立刻关，改回白名单模式&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;原则就是：Catch-all 是便利和垃圾之间的一笔交易，收信量小的时候便利占上风，域名越出名，这笔交易越亏。&lt;/p&gt;
&lt;h2&gt;七、转发场景下的 SPF 与垃圾箱问题&lt;/h2&gt;
&lt;p&gt;邮件转发有一个天生的身份问题：信原本是发件人的服务器发出的，经 Cloudflare 转手后，收信方看到的是 Cloudflare 的服务器在投递。收信方一查 SPF——发件人域名授权的服务器列表里没有 Cloudflare——就容易判定这封信「来路不正」，轻则进垃圾箱，重则拒收。&lt;/p&gt;
&lt;p&gt;Cloudflare 处理这个问题靠的是两件事。一是启用时自动写入的那条 SPF 记录，把 Cloudflare 的转发服务器加进本域名的授权名单，解决「以你域名为收件域」这一侧的校验。二是转发环节会做 SRS（发件人重写）和 DKIM 签名处理，让转发后的邮件在校验链上尽量自洽。这也是为什么第三节强调那几条自动记录不要手贱去改——改坏一条，转发邮件的送达率立刻受影响。&lt;/p&gt;
&lt;p&gt;DMARC 这一侧只需记住一句：发件人域名的 DMARC 策略越严格，转发链越容易断，因为转发天然会破坏原始的 SPF 对齐。遇到某个固定发件方的邮件总是转不进来，先怀疑这一层，而不是自己的规则配错了。SPF、DKIM、DMARC 三者的完整机制和记录写法，在 &lt;a href=&quot;/posts/cloudflare-dns-records/&quot;&gt;DNS 记录详解与常见坑&lt;/a&gt; 里有系统讲解，这里就不展开了。&lt;/p&gt;
&lt;p&gt;自己能做的送达率优化其实不多，就两条：把 Cloudflare 的转发来源在目标邮箱里加进联系人或白名单，避免目标邮箱自己的过滤器误伤；以及定期去垃圾箱里巡视，把误判的转发邮件标为「非垃圾」，帮过滤器学习。&lt;/p&gt;
&lt;h2&gt;八、使用纪律：把分地址用到极致&lt;/h2&gt;
&lt;p&gt;功能配好只是开始，域名邮箱真正的威力在长期使用习惯里。推荐一套简单可执行的纪律：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;一类用途一个地址。&lt;/strong&gt; 代码托管、云服务、网购、社交、资讯订阅、对外联系，各用各的前缀，并且拿个表格或者笔记把「哪个地址给了哪个服务」记下来。这份清单平时没用，出事时价值连城。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;泄露止损只动一条规则。&lt;/strong&gt; 某个地址开始收垃圾邮件，或者某个服务爆出数据泄露，你的动作是：去那个服务把注册邮箱改成新地址，再回 Cloudflare 把旧规则停掉。整个过程十分钟，且不影响其他任何服务。这就是分地址体系最大的回报——风险被隔离在单个格子里。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;主邮箱永不示人。&lt;/strong&gt; 目标地址只出现在你自己的配置里，不填进任何注册表单、不印在任何地方。外面流传的永远只有域名地址。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;定期巡检规则列表。&lt;/strong&gt; 每隔几个月翻一遍路由规则：不用的删掉，目标地址换人了的及时改。规则列表就是你的地址资产清单，保持它干净，后面排障时能省大量时间。&lt;/p&gt;
&lt;p&gt;最后呼应第二节的边界：如果你确实有「以域名地址发信」的需求，两条常见出路。一是在 Gmail 里用「设置 → 账号和导入 → 以其他地址发送」，把域名地址配成发信别名（需要配合一个可用的 SMTP 通道）；二是订阅专门的发送型邮件服务，用它提供的 SMTP 或 API 发信，收信继续走 Email Routing 转发。收发分开、各用所长，是个人域名邮箱最稳的组合形态。&lt;/p&gt;
&lt;h2&gt;九、排障：收不到信时按这个顺序查&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;启用后一封都收不到。&lt;/strong&gt; 按顺序查四项：一查 MX 是否生效，用 &lt;code&gt;dig&lt;/code&gt; 或在线工具查域名的 MX 记录，确认指向的是 Cloudflare 而不是旧服务残留；二查目标地址验证状态，未验证是最常见的原因；三查规则本身是不是停用状态、地址拼写有没有错；四查目标邮箱的垃圾箱，信可能被目标侧过滤了。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 在本地终端确认 MX 记录已经指向 Cloudflare
dig +short MX anexns.com

# 顺带确认 SPF 记录存在且只有一条
dig +short TXT anexns.com
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 SPF 一个域名下只能有一条，多条并存会让校验直接失败——这也是 &lt;a href=&quot;/posts/cloudflare-dns-records/&quot;&gt;DNS 记录详解&lt;/a&gt; 里反复强调的坑，启用 Email Routing 前如果手工加过 SPF，先合并再说。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;测试邮件被退信。&lt;/strong&gt; 看退信邮件里的状态码和说明：提示目标地址不存在或未验证，回去走第四节的验证流程；提示 MX 找不到，多半是记录还没全球生效，等十几分钟再测；提示被策略拒绝，则大概率是发件方 DMARC 严格策略与转发不兼容，属第七节讲的固有边界，换个发件邮箱测试即可确认。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;和旧邮箱服务互相打架。&lt;/strong&gt; 表现是收信时有时无：同一发件人发的两封信，一封进了旧邮箱，一封进了转发链。根源就是第三节说的 MX 混杂——新旧两套记录都在。解决办法是下决心留一套，把另一套的 MX 删干净，等 DNS 缓存过期后即恢复正常。切记改完 MX 不要立刻下结论，全球缓存刷新需要时间，至少等半小时再复测。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;规则明明开着，某个发件人总是收不到。&lt;/strong&gt; 先让对方确认他那边有没有收到退信、退信写的什么；再检查是不是他的邮件被目标邮箱的过滤器吞进了垃圾箱或广告分类；最后才怀疑转发链本身。这类「单点收不到」十有八九出在两端，中间环节反而是最稳的。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Email Routing 是免费的域名邮箱转发：域名地址收信，自动转投到你的常用邮箱，不存信、无客户端。&lt;/li&gt;
&lt;li&gt;它的边界只有一条但很硬：只能收，不能发；要发信得另配发送服务或借道 Gmail 别名。&lt;/li&gt;
&lt;li&gt;启用时它会自动写入 MX 与 SPF 等记录，确认前先核对——同一域名的 MX 只能指向一套收信体系，与旧邮箱服务必须二选一。&lt;/li&gt;
&lt;li&gt;配置顺序不能乱：先加目标地址并点验证邮件确认，再建转发规则，最后自测一封。&lt;/li&gt;
&lt;li&gt;Catch-all 全收图一时方便，代价是垃圾邮件无限涌入，域名越公开越不建议开。&lt;/li&gt;
&lt;li&gt;长期价值在纪律：一类用途一个地址、泄露时只停一条规则止损、主邮箱永不对外。&lt;/li&gt;
&lt;li&gt;收不到信的排查顺序：MX 生效与否 → 目标验证状态 → 规则拼写与开关 → 目标邮箱垃圾箱 → 退信代码定性。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>免费额度与计费避坑：Cloudflare 哪些功能真免费</title><link>https://www.anexns.cloudns.org/posts/cloudflare-free-tier-billing/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-free-tier-billing/</guid><description>多数人是收到第一封 Cloudflare 账单邮件才开始慌：到底哪些功能在悄悄计费？本文把 Workers、R2、D1 等产品的免费额度、收费触发点和关停方法一次讲清，帮你安心白嫖不踩坑。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;邮箱里躺着一封来自 Cloudflare 的邮件，标题里带着 invoice 这个词。点开之前心跳先漏了半拍：不是说好免费吗，怎么就出账单了？翻完账单才发现，要么是自己手滑点开了某个按量功能，要么是上个月随手绑的信用卡被自动续了一笔小额订阅。Cloudflare 的免费额度其实相当大方，个人站长正常用，一年到头花不到一分钱；真正让人破财的，往往不是流量太大，而是不知道哪些开关一点就开始计费、超额之后又不会自动停。这篇就把这件事一次讲清：哪些产品有多少免费额度、哪些动作会让账单开始跳字、开了付费功能怎么关回去。&lt;/p&gt;
&lt;p&gt;官方定价页：https://www.cloudflare.com/plans/&lt;/p&gt;
&lt;p&gt;需要先声明一句：Cloudflare 的定价和额度时有调整，本文所有数字均以官方定价页和控制台实际显示为准；你在后台看到的数字和本文不一致时，以后台为准。&lt;/p&gt;
&lt;h2&gt;免费额度总表：个人站长真正用得到的&lt;/h2&gt;
&lt;p&gt;先给结论：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Cloudflare 免费版的额度对个人网站来说基本等于「用不完」，收费的口子全在主动开启的付费功能和少数按量产品上。&amp;lt;/span&amp;gt;下面这张表把本系列涉及的主要产品免费额度汇总在一起，够日常查阅。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;产品&lt;/th&gt;
&lt;th&gt;免费额度&lt;/th&gt;
&lt;th&gt;超出之后&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Workers&lt;/td&gt;
&lt;td&gt;每天 100,000 次请求&lt;/td&gt;
&lt;td&gt;免费版直接返回错误、不扣费；付费版按量计费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Pages&lt;/td&gt;
&lt;td&gt;静态请求不限量，每月 500 次构建&lt;/td&gt;
&lt;td&gt;构建次数用完等下月；静态托管本身不收费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;R2 对象存储&lt;/td&gt;
&lt;td&gt;10 GB 存储；每月 A 类操作 100 万次、B 类操作 1000 万次；出口流量免费&lt;/td&gt;
&lt;td&gt;按量计费，见下一节单价&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;D1 数据库&lt;/td&gt;
&lt;td&gt;每天读 500 万行、写 100,000 行；总存储 5 GB&lt;/td&gt;
&lt;td&gt;免费版超限后拒绝新请求；付费版按量计费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Workers KV&lt;/td&gt;
&lt;td&gt;每天读 100,000 次、写 1000 次；1 GB 存储&lt;/td&gt;
&lt;td&gt;免费版超限报错；付费版按量计费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Tunnel&lt;/td&gt;
&lt;td&gt;免费，无连接数和流量限制&lt;/td&gt;
&lt;td&gt;不收费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Access（Zero Trust 免费版）&lt;/td&gt;
&lt;td&gt;最多 50 个用户&lt;/td&gt;
&lt;td&gt;超过 50 人需升级 Zero Trust 付费计划&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Turnstile&lt;/td&gt;
&lt;td&gt;免费&lt;/td&gt;
&lt;td&gt;不收费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Email Routing&lt;/td&gt;
&lt;td&gt;免费&lt;/td&gt;
&lt;td&gt;不收费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;DNS 与 CDN 基础功能&lt;/td&gt;
&lt;td&gt;免费版包含，不限域名解析量&lt;/td&gt;
&lt;td&gt;不收费&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;看这张表先注意一个口径差异：额度分「按天重置」和「按月累计」两种。Workers、D1、KV 是按天算的，今天用超了只影响今天，明天零点（UTC）自动回满，这种额度最适合扛突发流量——某天被爬虫刷爆，第二天照常营业。而 R2 的操作次数和 Pages 的构建次数是按月累计的，月初手滑刷掉一大截，剩下的日子就得省着用。把两类额度的脾气分清，盯用量时才知道该看日视图还是月视图。&lt;/p&gt;
&lt;p&gt;有几个数字值得单独说。Workers 免费版每天 10 万次请求，折算下来平均每秒一个多请求，个人博客、小工具、API 中转完全够用，而且&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;免费版超限只会让请求报错，绝不会偷偷扣钱&amp;lt;/span&amp;gt;——扣费只发生在你主动订阅了 Workers Paid 之后。R2 的 10 GB 免费存储加上出口流量免费，是它最出名的一点：把图床、备份、静态资源放进去，下行流量再大也不产生流量费，详细玩法见 &lt;a href=&quot;/posts/cloudflare-r2-storage/&quot;&gt;R2 对象存储入门&lt;/a&gt;。D1 每天读 500 万行、写 10 万行，给 &lt;a href=&quot;/posts/cloudflare-d1-database/&quot;&gt;D1 数据库实战&lt;/a&gt; 里那种小型应用绰绰有余。&lt;/p&gt;
&lt;h2&gt;哪些动作会开始收费：收费触发点清单&lt;/h2&gt;
&lt;p&gt;免费额度用超了不一定收费，但下面这些动作一旦做了，计费立刻开始。把它们分成两类：订阅型（每月固定扣）和按量型（用多少扣多少）。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;收费项&lt;/th&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;价格/触发方式&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Workers Paid&lt;/td&gt;
&lt;td&gt;订阅＋按量&lt;/td&gt;
&lt;td&gt;每月 5 美元起，含更高的请求与 CPU 时间额度，超出再按量加收&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;R2 超出免费额度&lt;/td&gt;
&lt;td&gt;按量&lt;/td&gt;
&lt;td&gt;存储每 GB 每月 0.015 美元；A、B 类操作超出部分按次计费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;D1 / KV 付费版用量&lt;/td&gt;
&lt;td&gt;按量&lt;/td&gt;
&lt;td&gt;订阅 Workers Paid 后生效，按读写行数/次数与存储计费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Argo Smart Routing&lt;/td&gt;
&lt;td&gt;按量&lt;/td&gt;
&lt;td&gt;按经过加速的流量计费，后台一键开启即生效&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Load Balancing 负载均衡&lt;/td&gt;
&lt;td&gt;订阅＋按量&lt;/td&gt;
&lt;td&gt;按订阅档位收费，含一定查询量，超出另计&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cache Reserve&lt;/td&gt;
&lt;td&gt;按量&lt;/td&gt;
&lt;td&gt;按写入次数和保留存储量计费，开启缓存规则时可选&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Zero Trust 付费计划&lt;/td&gt;
&lt;td&gt;订阅&lt;/td&gt;
&lt;td&gt;Access 用户超过 50 人，或需要更长日志保留等高级功能时升级&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Registrar 域名&lt;/td&gt;
&lt;td&gt;一次性/年费&lt;/td&gt;
&lt;td&gt;注册、续费、转入按域名后缀标价，这本来就是要花钱的&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;付费证书/高级 SSL 功能&lt;/td&gt;
&lt;td&gt;订阅&lt;/td&gt;
&lt;td&gt;如 Advanced Certificate Manager 等，在 SSL 设置页开通&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;最容易踩的坑集中在三处。第一处是 Argo：它在控制台性能相关页面里是个不起眼的开关，点开之后按流量收费，站点流量一大，账单涨得比谁都快。第二处是 Workers：很多人为了用 D1 的更高额度或 KV 的更高写入量去订阅 Workers Paid，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;订阅一旦生效，名下所有 Workers、D1、KV 的用量都进入按量计费&amp;lt;/span&amp;gt;，不再享受「超限只报错」的保护。第三处是 R2：存储单价看起来便宜得离谱（每 GB 每月 0.015 美元），但如果把备份脚本写错、把整个硬盘往上同步，几百 GB 存一个月也是真金白银。&lt;/p&gt;
&lt;p&gt;:::warning
绑了信用卡之后，上面这些开关全都是「一点即生效、立即开始计费」，不会再有二次确认弹窗。更要命的是按量计费&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;超额不会自动停&amp;lt;/span&amp;gt;：R2 存超了继续按 GB 收钱、Workers Paid 请求超了继续按次收钱，系统默认一路扣到你手动关掉为止。没绑卡的账户反而天然安全——想扣也没地方扣。
:::&lt;/p&gt;
&lt;h2&gt;几个最容易误判的边界&lt;/h2&gt;
&lt;p&gt;除了清单里的收费项，还有几个地方经常让人误判，单独拎出来说清。&lt;/p&gt;
&lt;p&gt;**Pages 的 500 次构建和 Workers 的 10 万次不是一回事。**Pages 构建指的是你推代码触发的部署次数，纯静态站推一次算一次；但如果你的 Pages 项目用了 Functions（动态函数），函数调用走的是 Workers 的额度池，每天 10 万次和你其他 Worker 合并计算。静态站随便推，函数调用要算着点。&lt;/p&gt;
&lt;p&gt;**Workers 免费版还有 CPU 时间上限。**每个请求除了次数，还受单次 CPU 执行时间限制，跑死循环或重计算会在次数没用完之前先被掐掉报错。这不是收费问题，是免费版的硬限额；真需要长计算，要么拆任务，要么上付费版。&lt;/p&gt;
&lt;p&gt;**图片处理类功能基本都要钱。**控制台里和图片沾边的 Polish、图片缩放（现归入 Cloudflare Images 体系）都属于付费或按量功能，免费版能用的是基础缓存和压缩。给博客做图床时，老老实实走 R2 加 Pages/Workers 分发，别顺手把图片优化开关全打开。&lt;/p&gt;
&lt;p&gt;**套餐（Free/Pro/Business）与产品订阅是两笔账。**域名套餐决定的是 CDN、WAF 规则数这类站点级功能；Workers Paid、Load Balancing 这些是独立的产品订阅，一个账户可以域名全是 Free 套餐、同时单独订着 Workers Paid。对账时分开看，别把产品订阅的扣费误以为是套餐涨价。&lt;/p&gt;
&lt;p&gt;**免费版的功能受限不等于数据受限。**免费版主要卡的是用量上限和高级功能（更长的日志保留、更细的规则条数等），你已经存进去的数据、已经配好的 DNS 和规则不会因为没付费被清掉。把它理解成「限量版」而不是「试用版」，心态会稳很多。&lt;/p&gt;
&lt;h2&gt;怎么盯用量：别等账单来了才发现&lt;/h2&gt;
&lt;p&gt;防坑的核心是提前知道用量涨到哪了。Cloudflare 提供三个层面的查看方式，建议都过一遍。&lt;/p&gt;
&lt;p&gt;第一是各产品自己的用量页。Workers 的用量在控制台「Workers 和 Pages」里每个 Worker 的指标页能看到当天请求数和错误数，免费版还会显示距离 10 万次上限还有多远；R2 的用量在 R2 概览页按存储桶统计存储量和操作次数；D1 和 KV 同样在各自的管理页有读写计数。这些数字通常有几小时延迟，别拿它当实时监控。&lt;/p&gt;
&lt;p&gt;第二是账单页。控制台右上角头像菜单进入 Billing，能看到当前周期的预估费用、已订阅的产品清单和历史账单 PDF。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;只要订阅清单里出现了你不认识的条目，就是有人（多半是过去的你）点开了付费功能&amp;lt;/span&amp;gt;，顺着条目名字就能找到关停入口。&lt;/p&gt;
&lt;p&gt;第三是通知。在 Billing 的通知设置里可以开启账单相关邮件提醒；Zero Trust 和 Workers 也有各自的用量通知选项。把能开的都开上，让系统在产生费用时第一时间发邮件，而不是等你月底对账。&lt;/p&gt;
&lt;p&gt;顺带一提，API 侧也能查用量：通过 GraphQL Analytics API 可以拉到 Workers 请求量、R2 操作量等数据，配合本系列 API Token 那篇里讲的最小权限令牌，完全可以自己写个脚本每天汇总一份用量日报，超阈值就推送告警。这属于进阶玩法，个人站长用控制台加邮件提醒已经足够。&lt;/p&gt;
&lt;p&gt;还有两个容易忽略的统计口径，提前知道能省掉很多对账焦虑。一是 Workers 的「请求数」按进入 Worker 的次数算，静态资源如果走了缓存、没触发 Worker，就不占额度；Pages 的 Functions 本质也是 Workers，调用量和你的 Workers 额度合并计算，别以为 Pages 那边是另一本账。二是 R2 的操作分 A、B 两类：A 类是写操作（上传、删除、列举等），B 类是读操作（下载、读取元信息等），免费额度分别是每月 100 万次和 1000 万次——图床场景下读多写少，B 类额度基本用不完，真正要防的是备份软件抽风式地反复全量列举和重传，把 A 类次数刷爆。&lt;/p&gt;
&lt;h2&gt;不小心开了付费功能：关停与降级手册&lt;/h2&gt;
&lt;p&gt;发现账单不对，按这个顺序处理：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;先定位&lt;/strong&gt;：打开 Billing 页看订阅清单和当前周期明细，确认是哪一项在收费、从哪天开始的。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;关功能开关&lt;/strong&gt;：Argo、Cache Reserve 这类在各自的产品设置页里关掉开关即可，关掉之后按量计费立刻停止，已产生的用量按当月结算。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;取消订阅&lt;/strong&gt;：Workers Paid、Load Balancing、Zero Trust 付费计划在 Billing 的订阅管理里取消。取消后一般是当前周期结束才失效，周期内已付的钱不退，但不会再续下个月。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;降级套餐&lt;/strong&gt;：整个账户的套餐在域名概览页可以从 Pro/Business 降回 Free，降级同样在周期末生效。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;实在不行解绑支付方式&lt;/strong&gt;：确认没有在付订阅之后，可以在 Billing 里移除信用卡。没有支付方式，按量功能即便被误开也扣不到钱，是最后一道保险。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;如果确认是误开且金额已经产生，可以走控制台的支持工单说明情况：写清是哪项功能、何时开启、自己实际的使用意图，附上账单编号。官方对首次误开、金额不大的情况有时会酌情处理，但这属于个案裁量，不要把它当成常规退款通道；工单的结果以官方回复为准，处理期间先把开关和订阅关掉止损，这一步不要等工单回复了再做。&lt;/p&gt;
&lt;p&gt;关于降级后数据会不会丢：Workers 的脚本、KV 的数据、D1 的数据库、R2 的文件在降回免费版之后都还在，只是用量上限变回免费额度；超过免费额度上限的部分功能会受限（比如 KV 写入超限报错），但数据本身不会因为降级被删除。真正要注意的是 Zero Trust：Access 免费版最多 50 个用户，从付费版降下来时如果用户数超了，需要先精简到 50 以内，具体保护访问应用的方法见 &lt;a href=&quot;/posts/cloudflare-access-zero-trust/&quot;&gt;Access 零信任实战&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;给个人站长的省钱组合&lt;/h2&gt;
&lt;p&gt;把本系列前面各篇的免费玩法拼起来，一套零成本组合大致长这样：域名用免费版套餐托管 DNS 和 CDN；静态站用 Pages 部署，静态请求不限量、每月 500 次构建对个人博客富富有余；动态小功能用 Workers 免费版每天 10 万次额度，配 KV 存配置、D1 存结构化数据；文件和图床放 R2，吃满 10 GB 免费存储和免费出口流量；内网服务用 Tunnel 免费穿出来，再套 Access 免费版 50 个用户做登录保护；表单防机器人用 Turnstile，收域名邮件用 Email Routing。这一整套跑下来，唯一的固定支出是域名本身的年费。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;需求&lt;/th&gt;
&lt;th&gt;用哪个免费功能&lt;/th&gt;
&lt;th&gt;额度够不够&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;博客/静态站托管&lt;/td&gt;
&lt;td&gt;Pages&lt;/td&gt;
&lt;td&gt;静态请求不限量，构建每月 500 次足够&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;动态接口/小工具&lt;/td&gt;
&lt;td&gt;Workers 免费版&lt;/td&gt;
&lt;td&gt;每天 10 万次，个人项目很难用满&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;配置与缓存数据&lt;/td&gt;
&lt;td&gt;Workers KV&lt;/td&gt;
&lt;td&gt;每天读 10 万次，写 1000 次适合低频写&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;结构化业务数据&lt;/td&gt;
&lt;td&gt;D1&lt;/td&gt;
&lt;td&gt;每天读 500 万行，小型应用绰绰有余&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;图床/备份/下载站&lt;/td&gt;
&lt;td&gt;R2&lt;/td&gt;
&lt;td&gt;10 GB 免费存，出口流量免费是最大优势&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;内网服务对外访问&lt;/td&gt;
&lt;td&gt;Tunnel ＋ Access&lt;/td&gt;
&lt;td&gt;Tunnel 免费，Access 50 人以内免费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;防机器人表单&lt;/td&gt;
&lt;td&gt;Turnstile&lt;/td&gt;
&lt;td&gt;免费无量限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;域名邮箱收信&lt;/td&gt;
&lt;td&gt;Email Routing&lt;/td&gt;
&lt;td&gt;免费转发到现有邮箱&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这张组合表还有个隐藏好处：所有组件都在免费额度内互不牵连，哪天某一项真的涨到要付费了（比如 R2 存满 10 GB），你只需要为那一项单独决策，不会像某些全家桶那样牵一发动全身。&lt;/p&gt;
&lt;p&gt;用 &lt;a href=&quot;/posts/cloudflare-workers-intro/&quot;&gt;Workers 入门&lt;/a&gt; 里的方法把第一个 Worker 跑起来之后，建议养成两个习惯：一是每个月扫一眼 Billing 页，确认订阅清单里只有自己认识的东西；二是任何在控制台里没见过的开关，先搜一下价格再点，尤其是带 Accelerate、Reserve、Paid 字样的。做到这两点，账单邮件就只会是 0 元的那种。&lt;/p&gt;
&lt;h2&gt;同样是超限，免费版和付费版下场完全不同&lt;/h2&gt;
&lt;p&gt;最后把全文最核心的一个区别做成表，贴在手边看：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;情形&lt;/th&gt;
&lt;th&gt;免费版（未订阅付费）&lt;/th&gt;
&lt;th&gt;付费版（已订阅 Workers Paid 等）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Workers 请求超限&lt;/td&gt;
&lt;td&gt;当日剩余请求报错，次日恢复，不扣费&lt;/td&gt;
&lt;td&gt;继续放行，按量计费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;R2 存储超限&lt;/td&gt;
&lt;td&gt;无法再写入新对象（需自行清理）&lt;/td&gt;
&lt;td&gt;继续存储，按 GB 按月计费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;KV 写入超限&lt;/td&gt;
&lt;td&gt;当日写入报错，次日恢复&lt;/td&gt;
&lt;td&gt;继续写入，按量计费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Access 用户超 50&lt;/td&gt;
&lt;td&gt;无法再添加用户&lt;/td&gt;
&lt;td&gt;需升级更高档位计划&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;你的钱包&lt;/td&gt;
&lt;td&gt;绝对安全，最多功能停摆&lt;/td&gt;
&lt;td&gt;按账单自动扣款，直到你手动关停&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这张表就是为什么本文对「订阅」二字如此谨慎：免费版的世界里，最坏结果是功能停摆；一旦跨进付费版，最坏结果变成账单失控。升级之前先问自己一句——我是真的撞到了免费额度的天花板，还是只是被某个高级功能的介绍页种了草？大多数个人项目诚实回答完这一句，会发现免费版还能再战很久。&lt;/p&gt;
&lt;h2&gt;常见疑问&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;收到 0 元账单邮件正常吗？&lt;/strong&gt;
正常。只要账户绑了卡或有过订阅，Cloudflare 每月都会按周期出账单，哪怕金额是 0 也会发一封。金额为 0 说明这个周期没有任何计费项，放心归档即可；要警惕的是金额非 0 且自己没印象的账单。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;控制台的用量数字对不上，是不是多扣了？&lt;/strong&gt;
用量统计普遍有几小时延迟，账单页的预估数和产品页的计数也可能因为统计口径不同（比如按 UTC 自然日还是按账期）有小幅差异。先等 24 小时再看最终账单，一般会收敛一致；最终账单 PDF 上的数字才是结算依据。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;免费版 Workers 每天 10 万次用超了会扣费吗？&lt;/strong&gt;
不会。免费版没有任何支付授权时，超限请求直接返回错误，功能停摆但不产生费用。只有订阅了 Workers Paid 的账户才进入按量计费，这也是本文反复强调「订阅要慎重」的原因。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;降级或取消订阅后，这个月已经扣的钱能退吗？&lt;/strong&gt;
按官方政策，订阅费和已产生的按量费用一般不退，取消只对下个周期生效。所以发现误开要第一时间关，拖得越久按量部分涨得越多；金额明显异常且是首次误开时，可以提交工单说明情况，是否酌情处理以官方回复为准，本文不做承诺。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;到底要不要绑信用卡？&lt;/strong&gt;
看需求。只用 Free 套餐加各产品免费额度，完全可以不绑卡，白嫖得理直气壮。需要买域名（Registrar）、开 Workers Paid 或用付费功能时才必须绑。本文的建议是：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绑卡之后务必每月扫一眼订阅清单&amp;lt;/span&amp;gt;，因为从那一刻起，所有按量开关都从「开了也扣不到钱」变成「开了立即计费」。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;多个域名和多个产品，是合并成一张账单吗？&lt;/strong&gt;
是同一个账户维度出账：套餐费、产品订阅、按量费用汇总在同一张月度账单里，按产品分行列明。所以对账时按行核对即可，哪一行不认识就去查哪一个产品。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;R2 的出口流量真的全免费？&lt;/strong&gt;
是的，R2 的出站流量（egress）不收费，这也是它和很多对象存储最大的区别。但注意存储量和操作次数仍有免费上限，超出按量计费；另外通过某些第三方工具高频刷小文件时，A 类操作次数会涨得很快，账单大头可能出在操作费而不是存储费上。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Cloudflare 的收费逻辑其实不复杂：免费额度覆盖了个人站长的绝大多数需求，Workers 每天 10 万次、R2 10 GB 加免费出口、Pages 静态不限量，这些数字正常用都摸不到顶。真正的风险点只有三个——误开 Argo 这类按量开关、为了提额订阅 Workers Paid 后全线进入计费、以及超额不自动停的默认策略。把 Billing 页的订阅清单当作每月必查项，不认识的开关先查价再点，就能一直安心用免费版，真正做到让每一封账单邮件都是安心的 0 元，再也不用心跳漏拍。最后再提醒一次：额度与价格以官方定价页 https://www.cloudflare.com/plans/ 和你控制台的实际显示为准，本文数字若与官方不一致，以官方为准。&lt;/p&gt;
</content:encoded></item><item><title>域名接入 Cloudflare：DNS 托管与橙云灰云</title><link>https://www.anexns.cloudns.org/posts/cloudflare-getting-started/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-getting-started/</guid><description>把域名搬进 Cloudflare 的全过程：在注册商处改 NS、接入后逐条核对被自动扫描的解析记录，再讲清橙云代理与灰云直连到底差在哪、各自适合什么记录。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;把域名买回来之后，大多数人就停在了注册商自带的 DNS 解析面板里：能解析、能打开网站，好像也没什么问题。直到某一天想给网站套一层防护、想隐藏源站 IP、想让海外访客打开快一点，才发现这些能力注册商基本给不了，或者要另外收费。这时候的标准动作，就是把域名的 DNS 托管搬到 Cloudflare。&lt;/p&gt;
&lt;p&gt;本篇是 Cloudflare 实战系列的第一篇，只干一件打地基的事：&lt;strong&gt;把一个域名完整、正确地接入 Cloudflare&lt;/strong&gt;。流程本身不难，难的是细节——自动扫描漏掉的记录、改 NS 之后漫长的等待、橙云和灰云到底该怎么选，任何一处没处理好，轻则网站打不开，重则邮件全线中断。&lt;/p&gt;
&lt;p&gt;本篇主线如下：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;先讲清为什么要把 DNS 放到 Cloudflare，收益到底在哪&lt;/li&gt;
&lt;li&gt;接入全流程走一遍：添加站点、选计划、扫描记录、改 NS、确认生效&lt;/li&gt;
&lt;li&gt;重点讲接入第一大坑：自动扫描会漏记录，以及接入后逐条核对的清单&lt;/li&gt;
&lt;li&gt;讲透橙云（代理）与灰云（仅 DNS）的区别和选型&lt;/li&gt;
&lt;li&gt;最后是 DNS 传播验证方法和一份排障清单&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;一、为什么把 DNS 放到 Cloudflare&lt;/h2&gt;
&lt;p&gt;先把概念说清：域名托管分两件事，一是&lt;strong&gt;注册&lt;/strong&gt;（域名在谁家买的、归谁管续费），二是&lt;strong&gt;解析托管&lt;/strong&gt;（域名的 NS 服务器指向谁，由谁负责回答解析请求）。这两件事完全可以分开：域名可以在任何一家注册商买，解析却交给 Cloudflare 来管，注册关系不用动，续费还走原来的注册商。&lt;/p&gt;
&lt;p&gt;把解析托管搬到 Cloudflare，收益主要有四点：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;收益&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;免费且功能完整&lt;/td&gt;
&lt;td&gt;免费计划就包含 DNS 托管、基础 CDN、边缘 SSL 证书和基础防护，对个人站点和中小业务完全够用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;全球 Anycast 网络&lt;/td&gt;
&lt;td&gt;Cloudflare 的 DNS 服务器遍布全球，访客的解析请求会被就近应答，解析速度和稳定性都优于多数注册商自带 DNS&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;顺带获得 CDN 与防护&lt;/td&gt;
&lt;td&gt;开启代理后，网站流量自动经过 Cloudflare 边缘节点，缓存、抗攻击、隐藏源站 IP 这些能力是解析托管之外白送的&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;统一的管理面板&lt;/td&gt;
&lt;td&gt;DNS、证书、缓存规则、防火墙规则、安全分析全在一个控制台里，后续本系列讲的所有功能都建立在这次接入之上&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;需要提前说明的是：&lt;strong&gt;只做 DNS 托管、所有记录都不开代理时，Cloudflare 就只是一个更快更稳的解析服务商&lt;/strong&gt;，网站流量并不会经过它。CDN、防护、隐藏源站这些收益，全部来自后面要讲的&quot;橙云代理&quot;。所以接入只是第一步，记录怎么配才是关键。&lt;/p&gt;
&lt;p&gt;:::warning
接入 Cloudflare 只改解析托管，不改域名注册商，也不需要把域名转移（Transfer）到 Cloudflare。转移注册是另一回事，不要在接入时顺手点了转移，白白多等一个流程。
:::&lt;/p&gt;
&lt;h2&gt;二、接入全流程：五步走完&lt;/h2&gt;
&lt;h3&gt;第 1 步：添加站点&lt;/h3&gt;
&lt;p&gt;登录 Cloudflare 控制台，点「添加站点」（Add a site），输入你的根域名，例如 &lt;code&gt;example.com&lt;/code&gt;，注意只填根域名，不要带 &lt;code&gt;www&lt;/code&gt;、不要带 &lt;code&gt;https://&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;第 2 步：选择免费计划&lt;/h3&gt;
&lt;p&gt;接下来会让你选计划，页面最下方就是免费计划（Free），个人使用直接选它，后续随时可以升级。具体的付费计划价格和免费版的条数、额度限制，控制台里有实时说明，以控制台为准即可，本系列涉及的所有功能用免费计划都能完成。&lt;/p&gt;
&lt;h3&gt;第 3 步：等系统自动扫描现有记录&lt;/h3&gt;
&lt;p&gt;选完计划，Cloudflare 会自动去查询你域名现有的 DNS 记录，把扫到的结果列成一张表给你确认。这张表是本篇最需要认真对待的地方，下一节会专门讲。此时先不要急着点继续，把表里的记录和注册商面板里的记录在心里有个对比印象即可。&lt;/p&gt;
&lt;h3&gt;第 4 步：去注册商处修改 NS&lt;/h3&gt;
&lt;p&gt;确认记录后，Cloudflare 会给出两个专属于你的 NS 地址，形如：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;aria.ns.cloudflare.com
bob.ns.cloudflare.com
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;（每人分到的名字不同，以你控制台显示的为准。）&lt;/p&gt;
&lt;p&gt;然后回到域名注册商的管理后台，找到「DNS 服务器 / Nameservers」设置，把原来的 NS 全部删掉，换成 Cloudflare 给的这两个。这一步在注册商那边操作，不是在 Cloudflare 这边操作，第一次接入的人经常找错地方。&lt;/p&gt;
&lt;p&gt;改 NS 之前，还有一个容易被忽略的动作：如果你的域名在原解析商那里&lt;strong&gt;开启过 DNSSEC&lt;/strong&gt;，先去把它关掉，或者把注册商处的 DS 记录删掉。NS 换了之后旧的 DS 记录还留在注册局，新旧对不上，验证会直接失败，表现为域名在全球范围内解析异常。改完 NS 之后，可以在 Cloudflare 里重新开启 DNSSEC，它会给你新的 DS 记录，再回注册商处填上即可。&lt;/p&gt;
&lt;h3&gt;第 5 步：等待生效并确认状态&lt;/h3&gt;
&lt;p&gt;顺带说明一句接入方式的选择：Cloudflare 还提供一种「部分接入」（CNAME 接入），不用改 NS、只把单个子域名用 CNAME 指过来，但那是付费计划才有的能力。免费计划只有本篇讲的完整接入这一条路，对绝大多数人来说也正是更推荐的方式——整个域名的解析、防护和统计都在一个面板里，不用在两个服务商之间来回切换。&lt;/p&gt;
&lt;p&gt;改完 NS 回到 Cloudflare，点「完成，检查名称服务器」。之后就是等待：Cloudflare 会周期性地检测 NS 是否已经指向它，检测通过后站点状态变为「有效」（Active），并会发一封确认邮件。&lt;/p&gt;
&lt;p&gt;状态没变绿之前，站点处于「待处理」（Pending）状态，这段时间里你的解析仍然由旧服务商应答（只要旧解析还在），网站一般不受影响，所以不用慌，但也不要在这个阶段就去旧服务商那里删记录。&lt;/p&gt;
&lt;h2&gt;三、接入第一大坑：自动扫描一定会漏记录&lt;/h2&gt;
&lt;p&gt;这是整个接入流程里最容易翻车的一环，必须单独拿出来讲。&lt;/p&gt;
&lt;p&gt;Cloudflare 的自动扫描并不是把你旧服务商的记录原样&quot;导出&quot;过来的——它没有这个权限。它的做法是拿一张常见子域名词典（www、mail、ftp、api 等）逐个去查询，再加上根域名的常见记录类型，把查得到的拼成一张表。这意味着：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;不常见的子域名查不到&lt;/strong&gt;：比如你自己起的 &lt;code&gt;nas&lt;/code&gt;、&lt;code&gt;git&lt;/code&gt;、&lt;code&gt;panel&lt;/code&gt; 这类子域名，不在词典里，直接漏掉&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;邮箱相关记录最容易出事&lt;/strong&gt;：MX、SPF（TXT）、DKIM（TXT）、DMARC（TXT）这一套记录如果漏掉或指错，网站照常打开，但&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;邮件会直接收不到、发不出去，而且往往过了好几天才有人发现&amp;lt;/span&amp;gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;验证类 TXT 记录会漏&lt;/strong&gt;：各种域名所有权验证、推送服务验证的 TXT 记录，漏了之后对应服务会莫名失效&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
绝对不要相信自动扫描的结果是完整的。接入完成后，必须打开旧注册商（或旧解析商）的 DNS 面板，把两边的记录逐条对照一遍，缺一条补一条。这是整个接入流程里唯一不能偷懒的步骤。
:::&lt;/p&gt;
&lt;p&gt;逐条核对清单，照着旧面板从上往下过：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;检查项&lt;/th&gt;
&lt;th&gt;核对要点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;根域名 A / AAAA 记录&lt;/td&gt;
&lt;td&gt;IP 是否正确，是否需要开代理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;www 记录&lt;/td&gt;
&lt;td&gt;是 A 记录还是 CNAME，指向对不对&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;全部子域名&lt;/td&gt;
&lt;td&gt;逐个对照，重点找词典里不会有的自命名子域名&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MX 记录&lt;/td&gt;
&lt;td&gt;优先级（Priority）数字有没有抄错，目标主机名对不对&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TXT 记录&lt;/td&gt;
&lt;td&gt;SPF、DKIM、DMARC、各种验证记录，一条都不能少&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;CAA 记录&lt;/td&gt;
&lt;td&gt;如果原来有，决定证书签发机构的那几条也要补上&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SRV 等冷门记录&lt;/td&gt;
&lt;td&gt;有用到（比如某些语音、游戏、微软服务）才存在，存在就必须补&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;补记录的操作很简单：在 Cloudflare 的「DNS → 记录」页面点「添加记录」，类型、名称、内容、优先级照着旧面板抄过来即可。TTL 这一项在接入阶段统一选「自动」就行，TTL 的讲究留到本系列的 DNS 记录详解篇再细说。&lt;/p&gt;
&lt;p&gt;还有一个时间点上的纪律：&lt;strong&gt;旧解析商那边的记录至少保留几天再删&lt;/strong&gt;。NS 传播不是瞬间完成的，全球各地的递归 DNS 还在缓存旧 NS，在传播彻底结束前，仍有少量查询会打到旧服务商那里；旧记录要是提前删了，这部分访客就会解析失败。&lt;/p&gt;
&lt;h2&gt;四、橙云与灰云：本篇最核心的概念&lt;/h2&gt;
&lt;p&gt;在 Cloudflare 的记录列表里，每条 A、AAAA、CNAME 记录右边都有一个云朵图标，点它可以在两种状态间切换：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;橙色云朵（已代理，Proxied）&lt;/strong&gt;：这条记录的流量经过 Cloudflare&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;灰色云朵（仅 DNS，DNS only）&lt;/strong&gt;：这条记录只由 Cloudflare 负责解析，流量直连源站&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;橙云还是灰云，本质区别只有一个：访客的流量要不要经过 Cloudflare 的边缘网络中转。&amp;lt;/span&amp;gt;由此衍生出的全部差异如下：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;橙云（已代理）&lt;/th&gt;
&lt;th&gt;灰云（仅 DNS）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;流量路径&lt;/td&gt;
&lt;td&gt;访客 → Cloudflare 边缘 → 源站&lt;/td&gt;
&lt;td&gt;访客 → 直连源站&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;解析返回的 IP&lt;/td&gt;
&lt;td&gt;Cloudflare 边缘节点的 IP&lt;/td&gt;
&lt;td&gt;源站的真实 IP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;源站 IP 是否暴露&lt;/td&gt;
&lt;td&gt;隐藏，外界查不到&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;完全暴露，等于把服务器地址公开&amp;lt;/span&amp;gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;CDN 缓存&lt;/td&gt;
&lt;td&gt;生效&lt;/td&gt;
&lt;td&gt;不生效&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;WAF / 防护规则&lt;/td&gt;
&lt;td&gt;生效&lt;/td&gt;
&lt;td&gt;不生效&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;边缘 SSL 证书&lt;/td&gt;
&lt;td&gt;可用（访客到边缘这一段由 Cloudflare 终止加密）&lt;/td&gt;
&lt;td&gt;不可用，证书完全由源站自己负责&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TTL 设置&lt;/td&gt;
&lt;td&gt;强制为自动，手动 TTL 不起作用&lt;/td&gt;
&lt;td&gt;可自由设置&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适用对象&lt;/td&gt;
&lt;td&gt;网站类流量（HTTP / HTTPS）&lt;/td&gt;
&lt;td&gt;邮件、SSH、游戏、各种非网页协议，以及需要真实 IP 直连的场景&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;还有一个硬性限制必须记住：&lt;strong&gt;只有 A、AAAA、CNAME 三种记录能开代理&lt;/strong&gt;。MX、TXT、NS、SRV 等记录根本没有云朵开关，天生就是仅 DNS 状态。这背后的原因也不难理解：Cloudflare 的代理本质上代理的是 HTTP / HTTPS 流量，邮件投递、文本验证这类记录没有&quot;流量中转&quot;的概念。&lt;/p&gt;
&lt;p&gt;由此得出两条实操结论：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;网站记录开橙云&lt;/strong&gt;：根域名和 www 这类跑网页的记录，接入后确认无误就把代理打开，本系列后面讲的缓存、WAF、SSL 全部依赖它。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;邮件相关记录必须保持灰云&lt;/strong&gt;：MX 指向的邮件主机名（比如 &lt;code&gt;mail.example.com&lt;/code&gt;）如果本身是一条 A 记录，这条 A 记录&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不能开代理&amp;lt;/span&amp;gt;。开了代理之后，邮件服务器的 25、465、993 等端口流量会被塞进只处理网页流量的通道里，收发信会直接中断。同理，SSH 登录用的子域名、数据库远程连接、游戏服务器地址，一律灰云。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;一个常见的推荐配置长这样：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;记录&lt;/th&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;代理状态&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;example.com&lt;/td&gt;
&lt;td&gt;A&lt;/td&gt;
&lt;td&gt;橙云&lt;/td&gt;
&lt;td&gt;网站主入口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;www&lt;/td&gt;
&lt;td&gt;CNAME → example.com&lt;/td&gt;
&lt;td&gt;橙云&lt;/td&gt;
&lt;td&gt;网站别名入口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;mail&lt;/td&gt;
&lt;td&gt;A&lt;/td&gt;
&lt;td&gt;灰云&lt;/td&gt;
&lt;td&gt;邮件服务器，必须直连&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;example.com&lt;/td&gt;
&lt;td&gt;MX → mail.example.com&lt;/td&gt;
&lt;td&gt;不可代理&lt;/td&gt;
&lt;td&gt;邮件投递&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ssh&lt;/td&gt;
&lt;td&gt;A&lt;/td&gt;
&lt;td&gt;灰云&lt;/td&gt;
&lt;td&gt;管理入口，直连源站&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;五、开了代理之后，源站那边发生了什么变化&lt;/h2&gt;
&lt;p&gt;很多人在打开橙云之后会遇到一个困惑：源站的访问日志里，访客 IP 全变成了 Cloudflare 的节点 IP，地区统计也全乱了。这不是故障，而是代理的工作方式决定的，提前知道能少踩很多坑：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;源站看到的来源 IP 是边缘节点 IP&lt;/strong&gt;。真实访客 IP 被 Cloudflare 放在 &lt;code&gt;CF-Connecting-IP&lt;/code&gt; 请求头里传递，网站程序和日志系统需要专门读取这个头，才能拿到真实 IP。Nginx、Apache 以及主流程序都有对应的配置方法，属于接入后要补的一课。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;基于 IP 的判断都会受影响&lt;/strong&gt;：源站上按 IP 做的地区判断、访问频率限制、白名单，如果还按老逻辑读来源 IP，效果会完全走样。尤其是源站防火墙如果设置了&quot;只允许某些 IP 访问&quot;，开代理后要改成只允许 Cloudflare 的官方 IP 段回源，否则正常访客会被挡在门外。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;加密在边缘终止&lt;/strong&gt;。访客到 Cloudflare 这一段 HTTPS，用的是 Cloudflare 边缘的证书；Cloudflare 再到源站这一段是否加密、用什么证书，取决于 SSL 加密模式的设置。这一块水很深——选错模式会出现重定向死循环或者看似有锁、实则回源明文的情况，本系列的 SSL 篇会专门讲透，这里只需要先建立概念：&lt;strong&gt;开了橙云，你的 HTTPS 就变成了两段，而不是一段&lt;/strong&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;六、DNS 传播：为什么改了 NS 不是马上生效&lt;/h2&gt;
&lt;p&gt;NS 变更的生效速度，取决于全球递归 DNS 服务器里旧 NS 记录的缓存什么时候过期，这个缓存时间由注册局那一层的 TTL 决定，常见的是 24 到 48 小时。所以官方口径一直是&quot;最长可能需要 24 小时&quot;，实际体验中多数域名几小时内就完成，但&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;在传播期内会出现新旧解析并存的状态，这段时间不要急着下结论说接入失败&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;自己验证传播进度，用 &lt;code&gt;dig&lt;/code&gt; 命令最直接：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 查根域名的 NS 现在指向谁（看全局视角的结果）
dig NS example.com

# 直接向 Cloudflare 的公共 DNS 查，通常更新较快
dig NS example.com @1.1.1.1

# 向国内常见的公共 DNS 查，对比传播进度
dig NS example.com @223.5.5.5

# 查网站记录实际解析到什么 IP
dig +short example.com
dig +short www.example.com
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;判断方法很简单：几个查询点返回的 NS 都已经是 Cloudflare 给的那两个地址，说明传播基本完成；如果有的还是旧 NS，就继续等。也可以用在线的 DNS 传播检测工具看全球各节点的返回结果，结论一致。&lt;/p&gt;
&lt;p&gt;另外注意自己电脑和手机的本地缓存：浏览器、操作系统都会缓存解析结果。你改完配置自己却打不开、别人却能打开的情况，多半是本地缓存还没过期，换个网络或者等一会儿再试，不要急着回滚配置。&lt;/p&gt;
&lt;h2&gt;七、排障清单&lt;/h2&gt;
&lt;h3&gt;7.1 接入后网站打不开&lt;/h3&gt;
&lt;p&gt;按顺序排查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;先查状态：Cloudflare 里站点是否已经「有效」。还是「待处理」，说明 NS 没生效，见 7.3。&lt;/li&gt;
&lt;li&gt;查记录：&lt;code&gt;dig +short example.com&lt;/code&gt;，看有没有返回 IP。没有返回，大概率是根域名的 A 记录在自动扫描时漏了，去旧面板对照补上。&lt;/li&gt;
&lt;li&gt;有 IP 但打不开：如果开的是灰云，IP 就是源站地址，直接在服务器上排查服务本身；如果开的是橙云，把代理临时切成灰云再访问一次——灰云能打开、橙云打不开，问题在 Cloudflare 到源站这一段（源站防火墙没放行 Cloudflare 回源、源站 HTTPS 配置有问题等），这是定位分界点的经典手法。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;7.2 网站正常，但邮件收不到了&lt;/h3&gt;
&lt;p&gt;这是接入后最典型的事故，九成是记录问题：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;查 MX：&lt;code&gt;dig MX example.com&lt;/code&gt;，确认 MX 记录存在、优先级和目标主机名与旧配置一致。&lt;/li&gt;
&lt;li&gt;查邮件主机：&lt;code&gt;dig +short mail.example.com&lt;/code&gt;（把 mail 换成你 MX 实际指向的主机名），确认能解析出 IP。&lt;/li&gt;
&lt;li&gt;查代理状态：邮件主机名对应的 A 记录必须是灰云，开了橙云立即关掉。&lt;/li&gt;
&lt;li&gt;查 TXT：SPF、DKIM 记录是否齐全。缺 SPF 和 DKIM 主要影响发信（容易被对方判为垃圾邮件或直接拒收），缺 MX 和邮件主机记录则直接影响收信。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;7.3 站点状态一直是「待处理」&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code&gt;dig NS example.com&lt;/code&gt; 看 NS 到底指向谁。如果还是旧服务商的 NS，说明注册商那边的修改没保存成功，或者改错了地方（改成了在 DNS 记录里加 NS 记录，而不是修改域名的 Nameservers 设置，这是两种完全不同的操作）。&lt;/li&gt;
&lt;li&gt;确认填的是 Cloudflare 给的&lt;strong&gt;你自己的&lt;/strong&gt;那两个 NS 地址，没有从别人的教程里抄错，也没有多空格、多字符。&lt;/li&gt;
&lt;li&gt;检查注册商处是否残留旧的 DS 记录（DNSSEC）：在注册商后台关闭 DNSSEC 或删除 DS 记录，然后耐心等 DS 的缓存过期，这个过程可能需要数小时。&lt;/li&gt;
&lt;li&gt;如果 NS 已经指对了，只是 Cloudflare 还没检测到，点一下控制台里的「重新检查」即可，不要反复改动配置。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;7.4 某些子域名打不开&lt;/h3&gt;
&lt;p&gt;不用怀疑，就是自动扫描漏了这条记录。去旧面板找到它，在 Cloudflare 里补上，并顺手想一想这个子域名跑的是网页还是其他协议，再决定开橙云还是灰云。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;把这一篇的要点收拢一下：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;接入 Cloudflare 改的是解析托管，不是域名注册，域名不用转移。&lt;/li&gt;
&lt;li&gt;接入流程五步：添加站点、选免费计划、看扫描结果、去注册商改 NS、等状态变「有效」。&lt;/li&gt;
&lt;li&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;接入真正的验收标准，不是状态变绿，而是新旧两边的记录逐条核对无误&amp;lt;/span&amp;gt;——自动扫描漏记录是常态，邮箱记录漏一条就是一场事故。&lt;/li&gt;
&lt;li&gt;橙云与灰云的区别就是流量过不过 Cloudflare：网站开橙云吃 CDN 和防护，邮件、管理类记录保持灰云直连；只有 A、AAAA、CNAME 能开代理。&lt;/li&gt;
&lt;li&gt;开代理后，源站日志里的 IP、证书的终止位置都会变化，这些变化都有对应的处理方法，后续篇目会逐个展开。&lt;/li&gt;
&lt;li&gt;NS 传播需要时间，新旧并存期内不要乱动旧记录，更不要急着回滚。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;地基打好之后，下一篇我们进入 DNS 记录本身：每种记录类型到底管什么、TTL 怎么设、以及一批在日常运维中真实会遇到的解析坑。&lt;/p&gt;
</content:encoded></item><item><title>Cloudflare Pages 部署静态网站</title><link>https://www.anexns.cloudns.org/posts/cloudflare-pages-deploy/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-pages-deploy/</guid><description>把静态站免费托管到 Cloudflare 的边缘网络：连接 Git 仓库自动部署、构建设置与框架预设、自定义域名、预览部署与回滚，和手动上传的另一条路线。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;上一篇我们用 Workers 在边缘跑起了代码，但回头想想：绝大多数个人网站根本不需要&quot;跑代码&quot;——博客、文档站、作品集、落地页，本质上都是一堆生成好的 HTML、CSS、JavaScript 和图片文件。给这种站点专门开一台服务器，等于为了放几本书租了一间仓库：要打理系统、要续证书、要防入侵，还要为带宽和电费买单。&lt;/p&gt;
&lt;p&gt;Cloudflare Pages 就是为这类站点准备的托管服务：你把代码推到 Git 仓库，它自动拉取、构建、把产物分发到 Cloudflare 的全球边缘网络，访客从离自己最近的节点拿文件。没有服务器要维护，没有证书要续期，HTTPS 自动配好。这一篇我们把 Pages 的两条部署路线——连接 Git 自动部署和手动上传——完整走一遍，再讲清构建设置、自定义域名、预览部署、回滚这些日常真正会用到的东西，最后和&quot;自己拿服务器托管静态站&quot;做一次老实的取舍对比。&lt;/p&gt;
&lt;p&gt;主线先说清楚：先分清 Pages 和 Workers 各管什么，再走路线 A（连接 Git），逐项拆解构建设置，然后走路线 B（手动部署），接着绑自定义域名、用好预览部署与回滚，顺手认识 &lt;code&gt;_redirects&lt;/code&gt;、&lt;code&gt;_headers&lt;/code&gt;、&lt;code&gt;_routes.json&lt;/code&gt; 三个进阶文件，文末是排障小节。&lt;/p&gt;
&lt;h2&gt;先分清：Pages 和 Workers 各管什么&lt;/h2&gt;
&lt;p&gt;上一篇的 Workers 是&quot;在边缘运行你的 JavaScript 代码&quot;，适合需要逻辑判断的场景：改写请求、做接口、鉴权、A/B 分流。Pages 则是&quot;在边缘托管你的静态文件&quot;，适合内容在构建期就已经定型的站点。两者不是二选一的对手，而是分工不同的两件工具：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;Cloudflare Pages&lt;/th&gt;
&lt;th&gt;Cloudflare Workers&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;本质&lt;/td&gt;
&lt;td&gt;静态文件托管 + 全球分发&lt;/td&gt;
&lt;td&gt;边缘函数运行时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;产物&lt;/td&gt;
&lt;td&gt;HTML / CSS / JS / 图片等文件&lt;/td&gt;
&lt;td&gt;一段处理请求的函数代码&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合&lt;/td&gt;
&lt;td&gt;博客、文档、官网、作品集、单页应用&lt;/td&gt;
&lt;td&gt;接口代理、鉴权、改写、动态逻辑&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;部署方式&lt;/td&gt;
&lt;td&gt;推 Git 自动构建，或直接上传产物&lt;/td&gt;
&lt;td&gt;Wrangler 发布脚本&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;要不要写服务端代码&lt;/td&gt;
&lt;td&gt;不需要&lt;/td&gt;
&lt;td&gt;需要&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;收费模式&lt;/td&gt;
&lt;td&gt;静态请求免费额度慷慨，细则以控制台为准&lt;/td&gt;
&lt;td&gt;按请求与 CPU 时间计，细则以控制台为准&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;还有一个组合用法先点一句：Pages 项目里可以放一个 &lt;code&gt;functions&lt;/code&gt; 目录，里面的文件会被当作 Pages Functions 运行——它底层就是 Workers。也就是说，纯静态站用 Pages，哪天某个路径需要一点动态逻辑（比如表单提交、简单接口），不用搬家，在 Pages 里加 Functions 就行。本篇以纯静态部署为主，Functions 只在后面的 &lt;code&gt;_routes.json&lt;/code&gt; 部分露个脸。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;判断标准只有一条：内容在构建时能不能定死。能定死，归 Pages；必须按请求现算，归 Workers。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;路线 A：连接 Git 仓库自动部署&lt;/h2&gt;
&lt;p&gt;这是 Pages 的主线用法，也是推荐给长期维护站点的路线：本地写完，&lt;code&gt;git push&lt;/code&gt;，剩下的事全自动。整个过程分四步。&lt;/p&gt;
&lt;h3&gt;第一步：授权并选择仓库&lt;/h3&gt;
&lt;p&gt;进入 Cloudflare 控制台，左侧进入 &lt;strong&gt;Workers 和 Pages&lt;/strong&gt;，点 &lt;strong&gt;创建&lt;/strong&gt;，选择 &lt;strong&gt;Pages&lt;/strong&gt;，再选 &lt;strong&gt;连接到 Git&lt;/strong&gt;。第一次使用会跳转到 GitHub（或 GitLab）做 OAuth 授权，这里有个容易忽略的细节：授权时可以选择只授权某几个仓库，不必把全部仓库都交出去。按最小授权原则，只勾选要部署的那个仓库就够了。&lt;/p&gt;
&lt;p&gt;授权完成后回到控制台，在仓库列表里选中目标仓库，点 &lt;strong&gt;开始设置&lt;/strong&gt;。&lt;/p&gt;
&lt;h3&gt;第二步：配置构建设置&lt;/h3&gt;
&lt;p&gt;接下来是最关键的一屏：项目名称、生产分支、框架预设、构建命令、构建输出目录。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;项目名称&lt;/strong&gt;：会成为默认访问地址的一部分，比如填 &lt;code&gt;my-blog&lt;/code&gt;，默认域名就是 &lt;code&gt;my-blog.pages.dev&lt;/code&gt;，创建后不可改名，起名字时想清楚。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;生产分支&lt;/strong&gt;：一般是 &lt;code&gt;main&lt;/code&gt; 或 &lt;code&gt;master&lt;/code&gt;。推到这个分支的提交触发生产部署，其他分支触发预览部署（后面专门讲）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;框架预设&lt;/strong&gt;：下拉里选你用的框架，Cloudflare 会自动填好构建命令和输出目录。选对了，后面两项基本不用动。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;三个最典型的框架，预设填法对照如下：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;框架&lt;/th&gt;
&lt;th&gt;构建命令&lt;/th&gt;
&lt;th&gt;构建输出目录&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Astro&lt;/td&gt;
&lt;td&gt;&lt;code&gt;npm run build&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;dist&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Hugo&lt;/td&gt;
&lt;td&gt;&lt;code&gt;hugo&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;public&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;纯静态（无构建）&lt;/td&gt;
&lt;td&gt;留空&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/&lt;/code&gt;（直接填仓库根目录，或填存放 HTML 的目录名）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;纯静态站点没有构建步骤，构建命令留空即可，输出目录填文件所在的目录；如果 HTML 就在仓库根目录，填 &lt;code&gt;/&lt;/code&gt; 或者直接留默认。&lt;/p&gt;
&lt;h3&gt;第三步：保存并部署&lt;/h3&gt;
&lt;p&gt;点 &lt;strong&gt;保存并部署&lt;/strong&gt;，控制台会跳进构建日志页面，实时滚动输出：克隆仓库、安装依赖、执行构建命令、上传产物。第一次构建通常一两分钟。成功后页面顶部会给出形如 &lt;code&gt;https://my-blog.pages.dev&lt;/code&gt; 的地址，点开就能看到你的站点——这一刻它已经在全球边缘节点上对外服务了。&lt;/p&gt;
&lt;h3&gt;第四步：验证自动部署&lt;/h3&gt;
&lt;p&gt;在本地随便改一个字，提交并推送到生产分支：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git add .
git commit -m &quot;test auto deploy&quot;
git push origin main
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;回到控制台的部署列表，应该能看到一条新的构建正在排队或运行。从此你的发布流程就只剩 &lt;code&gt;git push&lt;/code&gt; 一个动作，构建失败时控制台会把日志停在出错的那一步，排障部分会讲怎么读。&lt;/p&gt;
&lt;p&gt;:::warning
Git 授权是长期有效的凭证，仓库里如果混进了密钥、令牌这类敏感文件，推送前务必先清理并写进 &lt;code&gt;.gitignore&lt;/code&gt;。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把带密钥的仓库连上任何自动部署平台，等于把密钥又复制了一份到第三方。&amp;lt;/span&amp;gt;
:::&lt;/p&gt;
&lt;h2&gt;构建设置逐项拆解&lt;/h2&gt;
&lt;p&gt;第一次配置时匆匆带过的几个字段，日后出问题基本都出在它们身上，逐个讲清。&lt;/p&gt;
&lt;h3&gt;构建命令&lt;/h3&gt;
&lt;p&gt;构建命令是在 Cloudflare 的构建环境里执行的 shell 命令，工作目录默认是仓库根目录。多数框架就是包管理器的一条脚本命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npm run build        # Node 系框架最常见
pnpm run build       # 用 pnpm 的项目
hugo --minify        # Hugo 也可以追加参数
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;命令执行失败（退出码非 0），整个部署就失败，不会拿旧产物顶替——这点是好事，不会出现&quot;以为更新了其实没更新&quot;的静默事故。&lt;/p&gt;
&lt;h3&gt;构建输出目录&lt;/h3&gt;
&lt;p&gt;构建产物所在的目录，相对于仓库根目录写。比如 Astro 产物在 &lt;code&gt;dist&lt;/code&gt;，就填 &lt;code&gt;dist&lt;/code&gt;；Hugo 在 &lt;code&gt;public&lt;/code&gt;，填 &lt;code&gt;public&lt;/code&gt;。&lt;strong&gt;这是所有设置里最容易填错、也是 404 故障的头号来源&lt;/strong&gt;，排障部分会再强调。注意不要写成绝对路径，也不要多带一层：产物里直接就是 &lt;code&gt;index.html&lt;/code&gt; 的那一层目录，才是输出目录。&lt;/p&gt;
&lt;h3&gt;根目录（高级设置）&lt;/h3&gt;
&lt;p&gt;如果你的站点代码不在仓库根目录，而是放在子目录里（比如一个仓库放多个项目，博客在 &lt;code&gt;blog/&lt;/code&gt; 下面），展开 &lt;strong&gt;高级设置&lt;/strong&gt;，把根目录填成 &lt;code&gt;blog&lt;/code&gt;。构建命令和输出目录都会以这个根目录为基准计算。单项目仓库保持默认空着即可。&lt;/p&gt;
&lt;h3&gt;环境变量&lt;/h3&gt;
&lt;p&gt;构建期需要注入的变量在这里配置，最常见的用途是指定运行时版本。Cloudflare 构建环境的 Node.js 默认版本未必和你本地一致，版本对不上时构建报错信息往往很隐晦。稳妥做法是显式声明：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;变量名&lt;/th&gt;
&lt;th&gt;示例值&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;NODE_VERSION&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;20&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;指定 Node.js 大版本&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;HUGO_VERSION&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0.128.0&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;指定 Hugo 版本（需要扩展版时另有变量）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;PYTHON_VERSION&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;3.11&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;指定 Python 版本&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;也可以在仓库根目录放一个 &lt;code&gt;.nvmrc&lt;/code&gt; 文件写上版本号，效果相同且能跟着代码一起版本管理，团队协作时更推荐这种方式。&lt;/p&gt;
&lt;p&gt;另一个关键点：&lt;strong&gt;生产环境和预览环境的环境变量是分开配置的&lt;/strong&gt;。控制台里切换到&quot;预览&quot;页签单独设置。比如预览环境想连测试接口、加统计排除标记，就只写在预览那一份里，别让预览构建污染生产配置。反过来，生产专用的变量也不要顺手勾选&quot;同时用于预览&quot;，先想一想再勾。&lt;/p&gt;
&lt;h2&gt;路线 B：手动部署&lt;/h2&gt;
&lt;p&gt;不是所有场景都适合连 Git：手里只有一个构建好的成品文件夹、临时要发个演示页、或者代码不方便进 GitHub。这时走手动路线。&lt;/p&gt;
&lt;h3&gt;方式一：控制台拖拽上传&lt;/h3&gt;
&lt;p&gt;在创建 Pages 项目时选择 &lt;strong&gt;上传资产&lt;/strong&gt;，把构建产物文件夹（或打包好的 ZIP）直接拖进浏览器，命名项目，部署完成。整个过程不到一分钟，适合一次性页面和临时演示。&lt;/p&gt;
&lt;p&gt;注意上传的是&lt;strong&gt;构建产物&lt;/strong&gt;，不是源代码：Astro 项目要先在本地 &lt;code&gt;npm run build&lt;/code&gt;，把生成的 &lt;code&gt;dist&lt;/code&gt; 文件夹拖上去；纯静态站点则直接拖放着 HTML 的文件夹。&lt;/p&gt;
&lt;h3&gt;方式二：Wrangler 命令行&lt;/h3&gt;
&lt;p&gt;Wrangler 是 Cloudflare 的官方命令行工具，装好之后一条命令就能部署，适合写进脚本或本地工作流：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 全局安装 Wrangler
npm install -g wrangler

# 登录 Cloudflare 账号（会打开浏览器授权）
wrangler login

# 部署指定目录为 Pages 项目
wrangler pages deploy dist --project-name my-blog
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个参数说明：&lt;code&gt;dist&lt;/code&gt; 是要部署的产物目录，换成你自己的；&lt;code&gt;--project-name&lt;/code&gt; 对应控制台里的项目名，项目不存在时 Wrangler 会引导你新建；后续更新同一个项目，再执行同一条命令即可，会生成一条新的部署记录，同样支持回滚。&lt;/p&gt;
&lt;p&gt;两种手动方式的取舍很简单：偶尔点一次，用拖拽；要反复发、或者想把部署写进自己的发布脚本，用 Wrangler。&lt;/p&gt;
&lt;p&gt;:::warning
手动部署没有&quot;推代码即上线&quot;的自动链路，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;最大的风险是改完代码忘了重新构建、把旧产物又传了一遍&amp;lt;/span&amp;gt;，页面看起来&quot;更新了&quot;其实没变。长期维护的站点，还是回到路线 A 让流程自动跑。
:::&lt;/p&gt;
&lt;h2&gt;自定义域名&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;*.pages.dev&lt;/code&gt; 地址能用，但正经站点都要绑自己的域名。Pages 的自定义域名在项目里 &lt;strong&gt;设置 → 自定义域&lt;/strong&gt; 中添加，分两种情况。&lt;/p&gt;
&lt;h3&gt;绑定子域名&lt;/h3&gt;
&lt;p&gt;比如把 &lt;code&gt;blog.example.com&lt;/code&gt; 绑到 Pages 项目，前提是这个域名已经托管在 Cloudflare（DNS 在 Cloudflare 这边）。满足前提时，添加域名后 Cloudflare 会&lt;strong&gt;自动&lt;/strong&gt;在 DNS 里生成一条指向该 Pages 项目的 CNAME 记录，你什么都不用手动配，等状态变为&quot;有效&quot;即可，HTTPS 证书也是自动签发、自动续期。&lt;/p&gt;
&lt;p&gt;如果域名不在 Cloudflare 托管，就需要去外部 DNS 服务商那里手动添加 CNAME 记录指向 &lt;code&gt;项目名.pages.dev&lt;/code&gt;，再回来等验证。能托管过来的域名，建议先转托管，省掉后续所有手动对接的麻烦（接入方法见本系列前面的域名接入篇）。&lt;/p&gt;
&lt;h3&gt;绑定根域（apex 域名）&lt;/h3&gt;
&lt;p&gt;把 &lt;code&gt;example.com&lt;/code&gt; 本身（不带任何前缀）绑到 Pages，有个协议层面的前提：DNS 规范里根域不能直接写 CNAME 记录。Cloudflare 的处理方式是它自家的 CNAME 展平（CNAME Flattening）技术——你在控制台照常添加根域，它在解析层把这条记录动态展平成 A 记录对外应答。所以&lt;strong&gt;根域绑定只在域名托管于 Cloudflare 时才顺畅&lt;/strong&gt;，这也是把 DNS 托管过来的又一个实际理由。&lt;/p&gt;
&lt;p&gt;实务上更常见的搭配是：根域和 &lt;code&gt;www&lt;/code&gt; 子域名都绑上，选一个作主域名，另一个用重定向跳过去（重定向的写法在下面 &lt;code&gt;_redirects&lt;/code&gt; 一节），避免两个地址各发一份内容。&lt;/p&gt;
&lt;p&gt;证书方面不用操心：自定义域名生效后边缘证书自动覆盖这个域名。但要注意刚添加时状态会经历&quot;正在验证 → 签发证书 → 有效&quot;的过程，几分钟内访问可能报证书错误，等状态变绿再对外宣布地址。&lt;/p&gt;
&lt;h2&gt;预览部署：每个分支一个网址&lt;/h2&gt;
&lt;p&gt;这是 Pages 用过就回不去的功能。连接 Git 的项目里，&lt;strong&gt;推到非生产分支的每一次提交、每一个 Pull Request，都会生成一个独立的预览地址&lt;/strong&gt;，形如：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;https://分支名.项目名.pages.dev
https://一串哈希.项目名.pages.dev
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;预览部署和生产环境完全隔离：产物独立、地址独立，还能套用预览环境专属的环境变量。它的正确用法是一条纪律：&lt;strong&gt;新文章、新改版先推到分支上，打开预览地址在手机和电脑上都验一遍，确认没问题再合并到生产分支上线&lt;/strong&gt;。出了问题也只烂在预览里，线上访客毫不知情。&lt;/p&gt;
&lt;p&gt;反过来也要克制：预览地址默认是公开可访问的（知道地址就能打开），&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把未发布的敏感内容、内部页面长期挂在预览部署上等人猜地址&amp;lt;/span&amp;gt;。团队项目可以在控制台开启访问控制限制预览的可见范围，个人项目则养成习惯：验完就删分支，预览随分支删除而失效。免费版能保留的部署数量、预览的保留时长等细节以控制台为准。&lt;/p&gt;
&lt;h2&gt;版本与回滚&lt;/h2&gt;
&lt;p&gt;Pages 的每一次部署（无论来自 Git 推送还是手动上传）都会在项目的 &lt;strong&gt;部署&lt;/strong&gt; 列表里留一条记录：时间、分支、提交信息、构建状态，一目了然。生产环境当前正在服务的，是列表中标记为生产的那一条。&lt;/p&gt;
&lt;p&gt;如果刚上线的一版出了问题——文章排版崩了、构建产物缺文件——不需要手忙脚乱改代码重发。在部署列表里找到上一个正常的版本，点右侧菜单选择 &lt;strong&gt;回滚到此部署&lt;/strong&gt;，确认后生产流量立即切回那一版产物，秒级生效。回滚切的是已经构建好的产物，不重新构建，所以快。&lt;/p&gt;
&lt;p&gt;两个注意点：第一，回滚只是把线上指回旧产物，&lt;strong&gt;代码仓库里的错误提交还在&lt;/strong&gt;，事后必须把代码修好再正常发布，否则下一次推送又会把坏版本带上线；第二，预览部署之间互不影响，回滚操作只针对生产环境当前生效的那条。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;回滚是止血，不是修 bug：先回滚恢复线上，再回头慢慢查代码。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;三个进阶文件&lt;/h2&gt;
&lt;p&gt;把下面三个纯文本文件放在构建输出目录的根部（用框架的项目通常是放在静态资源目录里，让它们被复制进产物），Pages 会在边缘按它们的规则处理请求。不用写代码，就能补上静态托管最常缺的三块能力。&lt;/p&gt;
&lt;h3&gt;&lt;code&gt;_redirects&lt;/code&gt;：跳转规则&lt;/h3&gt;
&lt;p&gt;每行一条规则，源路径在前、目标在后、状态码可选：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/old-post      /new-post      301
/blog/*        /posts/:splat  301
/www           /              302
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第一列是匹配路径，&lt;code&gt;*&lt;/code&gt; 是通配符，命中的部分用 &lt;code&gt;:splat&lt;/code&gt; 引用；状态码不写默认 302，永久迁移记得写 301。域名层面的跳转（比如 &lt;code&gt;www&lt;/code&gt; 跳根域）也可以在这里按路径层面近似处理，或者去 Cloudflare 的重定向规则里做，本系列的规则改写篇讲过那套体系，按需选一处配置即可，不要两边重复配同一件事。&lt;/p&gt;
&lt;h3&gt;&lt;code&gt;_headers&lt;/code&gt;：自定义响应头&lt;/h3&gt;
&lt;p&gt;给指定路径统一附加响应头，常用于安全头和缓存策略：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/*
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin

/assets/*
  Cache-Control: public, max-age=31536000, immutable
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第一段给全站加基础安全头；第二段给带指纹的静态资源设置一年长缓存。缩进和冒号格式要严格照抄，写错一行那一组就不生效且不报错，改完务必用浏览器开发者工具或 &lt;code&gt;curl -I&lt;/code&gt; 验一下响应头真的出现了。&lt;/p&gt;
&lt;h3&gt;&lt;code&gt;_routes.json&lt;/code&gt;：控制 Functions 的范围&lt;/h3&gt;
&lt;p&gt;只有当项目里用了 Pages Functions 时才需要它。它决定哪些路径的请求要经过 Functions 处理、哪些直接发静态文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;version&quot;: 1,
  &quot;include&quot;: [&quot;/api/*&quot;],
  &quot;exclude&quot;: []
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;上面这份配置的意思是：只有 &lt;code&gt;/api/*&lt;/code&gt; 走函数，其余路径全部按静态文件直出。这样既省函数调用次数，也避免函数逻辑意外拦截静态资源。纯静态项目没有 &lt;code&gt;functions&lt;/code&gt; 目录，这个文件写不写都无效果，可以跳过。&lt;/p&gt;
&lt;h2&gt;和自建服务器托管静态站的取舍&lt;/h2&gt;
&lt;p&gt;最后一张对比表，把 Pages 和&quot;自己拿一台 VPS 用 Nginx 托管静态站&quot;摆在一起。没有谁全面胜出，只有哪种更贴合你当前的阶段：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;Cloudflare Pages&lt;/th&gt;
&lt;th&gt;自建服务器 + Nginx&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;直接成本&lt;/td&gt;
&lt;td&gt;免费额度内零成本，细则以控制台为准&lt;/td&gt;
&lt;td&gt;服务器月租 + 域名，持续支出&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;日常运维&lt;/td&gt;
&lt;td&gt;无服务器、无补丁、无证书续期&lt;/td&gt;
&lt;td&gt;系统更新、证书、日志、备份全要自己管&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;访问速度&lt;/td&gt;
&lt;td&gt;全球边缘节点就近分发&lt;/td&gt;
&lt;td&gt;取决于机房位置，远距离访客慢&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;发布流程&lt;/td&gt;
&lt;td&gt;&lt;code&gt;git push&lt;/code&gt; 自动构建部署&lt;/td&gt;
&lt;td&gt;自己写脚本或手动传文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;控制力&lt;/td&gt;
&lt;td&gt;平台规则内使用，进阶靠三个配置文件&lt;/td&gt;
&lt;td&gt;完全自主，任何 Nginx 玩法都可以&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;风险面&lt;/td&gt;
&lt;td&gt;平台政策与额度调整不受你控制&lt;/td&gt;
&lt;td&gt;机器故障、被攻击、欠费停机都是你的事&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合&lt;/td&gt;
&lt;td&gt;博客、文档、官网等纯静态内容&lt;/td&gt;
&lt;td&gt;需要特殊服务端逻辑、或就是想练手折腾&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;结论很实际：纯静态内容放在 Pages，是在用平台的规模换自己的时间；除非你有明确的特殊需求，或者享受折腾服务器本身，否则没必要为几页静态文件养一台机器。真有动态需求，先想 Pages Functions 和 Workers 补不补得上，再考虑回自建。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;h3&gt;构建失败：先学会看日志的哪一行&lt;/h3&gt;
&lt;p&gt;构建失败时控制台会把完整日志摆出来，不要从头读到尾，&lt;strong&gt;直接拉到日志末尾往上找第一处报错&lt;/strong&gt;。失败九成集中在三类：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;依赖安装失败&lt;/strong&gt;：日志停在 &lt;code&gt;npm install&lt;/code&gt; 一带，多半是依赖版本与 Node 版本不兼容，或锁文件（&lt;code&gt;package-lock.json&lt;/code&gt; 等）没提交进仓库。先在高级设置里用 &lt;code&gt;NODE_VERSION&lt;/code&gt; 对齐本地版本，再确认锁文件在仓库里。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;构建命令失败&lt;/strong&gt;：日志里能看到你配的命令本身报错，比如脚本名写错、框架在构建机上缺环境变量。把报错命令复制到本地终端跑一遍，本地能复现就先在本地修好。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;命令成功但产物不对&lt;/strong&gt;：日志显示构建成功，部署却 404——这不是构建失败，是下一条的问题。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;部署成功但页面 404：先查输出目录&lt;/h3&gt;
&lt;p&gt;部署状态绿了、地址能打开却只有 404，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;第一嫌疑永远是构建输出目录配错&amp;lt;/span&amp;gt;：Astro 的产物在 &lt;code&gt;dist&lt;/code&gt;，你填了 &lt;code&gt;public&lt;/code&gt;；或者站点在子目录，根目录没配。判断方法很简单：看构建日志最后阶段上传的文件列表里有没有 &lt;code&gt;index.html&lt;/code&gt;，没有就是目录指错了层。改对输出目录后重新部署（推一个空提交或在控制台点重试部署）即可。&lt;/p&gt;
&lt;p&gt;还有一种情况是单页应用（SPA）：前端路由的路径在服务器上并不存在对应文件，直接访问子路径会 404。这需要在框架侧开启 SPA 模式支持，或用 &lt;code&gt;_redirects&lt;/code&gt; 把未命中路径兜底到 &lt;code&gt;index.html&lt;/code&gt;（状态码用 200 的重写写法），按框架文档确认后再配。&lt;/p&gt;
&lt;h3&gt;自定义域名一直&quot;待验证&quot;&lt;/h3&gt;
&lt;p&gt;按顺序排查三件事：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;DNS 记录冲突&lt;/strong&gt;：同名记录已经存在一条 A 记录或指向别处的 CNAME，新记录加不进去。去 DNS 管理里把冲突的旧记录删掉，再回 Pages 里重新添加域名。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;记录指错目标&lt;/strong&gt;：域名不在 Cloudflare 托管、手动配 CNAME 的，检查目标是不是写成了带 &lt;code&gt;https://&lt;/code&gt; 的完整网址——CNAME 的值只能是主机名 &lt;code&gt;项目名.pages.dev&lt;/code&gt;，不带协议、不带路径。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;只是还没生效&lt;/strong&gt;：DNS 修改和证书签发都需要几分钟，状态没变绿之前先耐心等，不要反复删除重加——每重加一次，验证流程就从头再来一遍。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;如果等待时间明显超出正常范围，再去看域名的 DNSSEC 状态：从别处新迁入的域名若残留旧的 DS 记录，会导致解析验证失败，需要在注册商处删除旧 DS 记录或按 Cloudflare 给的值更新，这一步对新手最隐蔽，卡住超过半小时优先查它。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Pages 管静态、Workers 管逻辑，内容构建期能定死就用 Pages，需要动态再加 Functions 或 Workers。&lt;/li&gt;
&lt;li&gt;路线 A 连接 Git 是长期站点的正道：授权时最小化仓库范围，框架预设选对，构建命令与输出目录照框架的规矩填。&lt;/li&gt;
&lt;li&gt;构建设置里最容易翻车的是输出目录，其次是 Node 版本；环境变量分生产与预览两套，别混用。&lt;/li&gt;
&lt;li&gt;路线 B 手动部署分拖拽和 Wrangler 两种，适合临时页面与脚本化发布，长期维护别靠它。&lt;/li&gt;
&lt;li&gt;自定义域名在 Cloudflare 托管下子域名自动配记录，根域靠 CNAME 展平实现，证书全自动。&lt;/li&gt;
&lt;li&gt;预览部署是上线前的验收场，先验后合并；回滚是秒级止血手段，但代码里的错误仍要修掉。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;_redirects&lt;/code&gt;、&lt;code&gt;_headers&lt;/code&gt;、&lt;code&gt;_routes.json&lt;/code&gt; 三个文件，分别补上跳转、响应头和函数范围三块能力。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;下一篇我们讲 Cloudflare Access：给那些必须放在公网、又不想裸奔的自建服务后台，套一层正经的登录门禁。&lt;/p&gt;
</content:encoded></item><item><title>R2 进阶应用：预签名链接、rclone 与博客图床</title><link>https://www.anexns.cloudns.org/posts/cloudflare-r2-advanced/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-r2-advanced/</guid><description>R2 桶建好、文件传上去之后怎么办：预签名链接临时分享私有文件、rclone 把服务器备份自动同步上来、绑自定义域名当博客图床、生命周期规则自动清理旧备份，一篇讲透。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;桶建好了、文件也传上去了，然后呢？&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;/posts/cloudflare-r2-storage/&quot;&gt;入门篇&lt;/a&gt;解决的是从零到一：开通、建桶、拿凭据、传上第一个文件。但真正把 R2 用进日常之后，冒出来的全是另一类问题，随便数数就有四个：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;备份桶是私有的，里面有个大文件要临时发给别人下载。把桶改公开不合适，把自己的访问密钥发过去更离谱，有没有只给这一个文件、还带过期时间的办法？&lt;/li&gt;
&lt;li&gt;服务器每天凌晨都会打出新的备份包，难道每次都要手动登录、手动上传？能不能让它自己同步上去，传完不用管？&lt;/li&gt;
&lt;li&gt;博客的图片想直接放桶里当图床，怎么公开读最省事？控制台里那个 r2.dev 开关一键就能开，和绑自己的域名有什么区别？&lt;/li&gt;
&lt;li&gt;备份一天一份往上堆，三个月后桶里躺着九十份全量包。旧的能不能自动删，别让它无声无息一直占着容量计费？&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;这四个问题，分别对应 R2 的四件进阶工具：预签名链接、rclone 同步、自定义域名公开桶、生命周期规则。下面逐个解。&lt;/p&gt;
&lt;p&gt;官方文档：https://developers.cloudflare.com/r2/&lt;/p&gt;
&lt;h2&gt;一、先回顾：端点长什么样&lt;/h2&gt;
&lt;p&gt;R2 对外提供的是 S3 兼容 API，所有程序化访问都打到同一个端点上，格式固定：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;https://&amp;lt;account_id&amp;gt;.r2.cloudflarestorage.com
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;其中 &lt;code&gt;&amp;lt;account_id&amp;gt;&lt;/code&gt; 是 Cloudflare 账户 ID，在控制台右侧栏和 R2 总览页都能找到。桶名不出现在域名里，而是作为请求参数或路径的一部分传过去；区域（region）在 SDK 里填 &lt;code&gt;auto&lt;/code&gt;，由 Cloudflare 自己就近调度。本篇所有代码用的都是这个端点加一对 R2 API Token 换来的 Access Key ID 与 Secret Access Key，凭据怎么创建在第六节统一讲，先把四件事办了。&lt;/p&gt;
&lt;h2&gt;二、预签名链接：私有文件的临时通行证&lt;/h2&gt;
&lt;p&gt;预签名链接（Presigned URL）解决第一个问题。它的原理是：服务端用密钥在本地算出一个签名，把签名、允许的操作、目标对象、过期时间一起拼进 URL 里。拿到链接的人不需要任何密钥，点开就能执行被授权的那一个动作——比如下载某个文件，或者往某个键上传一个文件——到期自动作废。整个生成过程纯粹是本地签名计算，不需要真的向 R2 发请求。&lt;/p&gt;
&lt;p&gt;有效期最短 1 秒、最长 7 天（604800 秒）。但先把丑话说前面：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;预签名链接是无记名通行证，谁拿到谁就能用&amp;lt;/span&amp;gt;，在过期之前可以被任意转发、重复使用。它等同于一张临时密码，只适合走私密渠道点对点发送，不要贴到公开页面、群聊或日志里。&lt;/p&gt;
&lt;h3&gt;生成下载与上传链接&lt;/h3&gt;
&lt;p&gt;Node.js 环境装两个官方包：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;一段代码同时生成下载和上传两种链接：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;import { S3Client, GetObjectCommand, PutObjectCommand } from &quot;@aws-sdk/client-s3&quot;;
import { getSignedUrl } from &quot;@aws-sdk/s3-request-presigner&quot;;

const S3 = new S3Client({
  region: &quot;auto&quot;,
  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
  credentials: {
    accessKeyId: process.env.R2_ACCESS_KEY_ID,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
  },
});

// 临时下载链接：允许在 1 小时内下载这一个文件
const downloadUrl = await getSignedUrl(
  S3,
  new GetObjectCommand({ Bucket: &quot;anexns-backup&quot;, Key: &quot;reports/2026-report.pdf&quot; }),
  { expiresIn: 3600 }
);
console.log(&quot;下载链接：&quot;, downloadUrl);

// 临时上传链接：允许在 10 分钟内往这个键上传一个 mp4 文件
const uploadUrl = await getSignedUrl(
  S3,
  new PutObjectCommand({
    Bucket: &quot;anexns-backup&quot;,
    Key: &quot;uploads/big-video.mp4&quot;,
    ContentType: &quot;video/mp4&quot;,
  }),
  { expiresIn: 600 }
);
console.log(&quot;上传链接：&quot;, uploadUrl);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;对方拿到链接后不需要装任何工具，浏览器打开下载链接即可下载；上传链接用 curl 就能推文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -X PUT --upload-file ./big-video.mp4 \
  -H &quot;Content-Type: video/mp4&quot; \
  &quot;&amp;lt;上面生成的上传链接&amp;gt;&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果只是临时给一个下载链接、不想专门写代码，AWS CLI 也能直接生成（需要先配好指向 R2 的凭据与端点）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;aws s3 presign s3://anexns-backup/reports/2026-report.pdf \
  --endpoint-url https://&amp;lt;account_id&amp;gt;.r2.cloudflarestorage.com \
  --expires-in 3600
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 CLI 的 &lt;code&gt;presign&lt;/code&gt; 只支持生成下载（GET）链接，上传链接还得走 SDK——这也符合实际分工：下载分享是临时起意，上传入口通常是程序功能的一部分。&lt;/p&gt;
&lt;h3&gt;三个使用要点&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;只能用 S3 API 端点。&lt;/strong&gt; 预签名链接只认 &lt;code&gt;r2.cloudflarestorage.com&lt;/code&gt; 这个域名，绑在桶上的自定义域名不能用来拼预签名链接，这是排障一节里最常见的一个坑。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;上传时 Content-Type 必须对上。&lt;/strong&gt; 生成链接时如果指定了 &lt;code&gt;ContentType&lt;/code&gt;，对方上传时请求头里必须带一模一样的值，否则签名校验不过。反过来这也是个优点：可以借它把上传限制在指定文件类型。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;有效期按场景给，别图省事拉满。&lt;/strong&gt; 发给人下载给 1 小时、网页直传给 10 分钟，足够用了；7 天那种长度只适合极少数内部场景。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;三、rclone 同步备份：从手动上传到定时任务&lt;/h2&gt;
&lt;p&gt;第二个问题交给 rclone。它是命令行界的「云存储瑞士军刀」，对 R2 这种 S3 兼容存储，配置一次远程（remote），之后服务器备份就能靠脚本和定时任务全自动跑。&lt;/p&gt;
&lt;h3&gt;写配置文件&lt;/h3&gt;
&lt;p&gt;交互式向导 &lt;code&gt;rclone config&lt;/code&gt; 一步步问也能配，但手写配置文件更直观、好备份。编辑 &lt;code&gt;~/.config/rclone/rclone.conf&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[r2]
type = s3
provider = Cloudflare
access_key_id = 你的AccessKeyID
secret_access_key = 你的SecretAccessKey
region = auto
endpoint = https://&amp;lt;account_id&amp;gt;.r2.cloudflarestorage.com
acl = private
no_check_bucket = true
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;最后一项 &lt;code&gt;no_check_bucket = true&lt;/code&gt; 值得单独说：如果你的 Token 只给了某个桶的对象读写权限（第六节推荐的最小权限配法），rclone 默认在操作前会尝试探测、甚至创建桶，权限不够就会报错。加上这一项，它跳过桶级探测，直接按对象操作，正好和桶级授权的 Token 严丝合缝。&lt;/p&gt;
&lt;p&gt;配完先验证连通性：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;rclone lsd r2:              # 列出账户下能看到的桶
rclone ls r2:anexns-backup  # 列出桶内对象（带大小）
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;copy 与 sync 的分工&lt;/h3&gt;
&lt;p&gt;日常命令就两个，分工必须分清：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# copy：把本地目录里的新文件、改过的文件补传上去，目标端多出来的文件不动
rclone copy /data/backup r2:anexns-backup/server-a --progress

# sync：让目标端和本地保持完全一致，本地没有的，目标端也会删掉
rclone sync /data/backup r2:anexns-backup/server-a --progress
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;区别一句话：&lt;code&gt;copy&lt;/code&gt; 只增改、不删除；&lt;code&gt;sync&lt;/code&gt; 是镜像，目标以本地为准。备份场景多数时候用 &lt;code&gt;copy&lt;/code&gt; 就够了，配合第五节的生命周期规则在桶端统一清理过期文件。如果要用 &lt;code&gt;sync&lt;/code&gt;，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;sync 会删掉目标端本地没有的文件，第一次跑务必先加 --dry-run 空跑一遍&amp;lt;/span&amp;gt;，确认删除清单符合预期再去掉。路径写反、把空目录 sync 到桶上，是这类工具最经典的事故，没有之一。&lt;/p&gt;
&lt;h3&gt;定时备份脚本&lt;/h3&gt;
&lt;p&gt;把打包和上传串成一个脚本，交给 cron 每天凌晨执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/usr/bin/env bash
set -euo pipefail

BACKUP_DIR=&quot;/data/backup&quot;
REMOTE=&quot;r2:anexns-backup/server-a&quot;
STAMP=&quot;$(date +%F)&quot;

# 打包站点文件与数据库导出
tar -czf &quot;${BACKUP_DIR}/site-${STAMP}.tar.gz&quot; -C /var/www site
mysqldump --single-transaction appdb | gzip &amp;gt; &quot;${BACKUP_DIR}/db-${STAMP}.sql.gz&quot;

# 只上传，不删除桶端已有文件；旧备份的清理由生命周期规则负责
rclone copy &quot;${BACKUP_DIR}/&quot; &quot;${REMOTE}/${STAMP}/&quot; \
  --transfers 4 \
  --log-file /var/log/rclone-backup.log --log-level INFO

# 本地只留最近 7 天
find &quot;${BACKUP_DIR}&quot; -type f -mtime +7 -delete
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;挂到定时任务里，每天凌晨 3 点跑：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;chmod +x /usr/local/bin/backup-to-r2.sh
crontab -e
# 加入一行：
# 0 3 * * * /usr/local/bin/backup-to-r2.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;同步类任务最怕「命令没报错，但文件其实没传全」。rclone 自带校验命令，拿不准时跑一次，它会逐个比对两端文件的大小与哈希，给出差异清单，定时任务里也可以接在 copy 后面当验收环节：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;rclone check /data/backup r2:anexns-backup/server-a
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这套组合跑起来之后，服务器本地留 7 天热备份，R2 上留更久的历史版本，两边互不依赖。哪天要恢复，从 R2 用 &lt;code&gt;rclone copy&lt;/code&gt; 把对应日期的包拉回来即可，R2 出口流量不收费，恢复大备份时不用心疼流量账单。&lt;/p&gt;
&lt;h2&gt;四、给博客当图床：公开读的三种方式怎么选&lt;/h2&gt;
&lt;p&gt;第三个问题的本质是「怎么让桶里的对象被公开访问」。R2 一共有三条路，先看对比表再做决定：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方式&lt;/th&gt;
&lt;th&gt;公开范围&lt;/th&gt;
&lt;th&gt;走 Cloudflare 缓存&lt;/th&gt;
&lt;th&gt;限速与管控&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;自定义域名&lt;/td&gt;
&lt;td&gt;整个桶（或指定域名路径）全公开&lt;/td&gt;
&lt;td&gt;支持，可配缓存规则&lt;/td&gt;
&lt;td&gt;无额外限速，可叠加 WAF、缓存规则&lt;/td&gt;
&lt;td&gt;正式图床、静态资源分发&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;r2.dev 子域名&lt;/td&gt;
&lt;td&gt;整个桶全公开&lt;/td&gt;
&lt;td&gt;不支持自定义缓存策略&lt;/td&gt;
&lt;td&gt;有限速，仅适合开发调试&lt;/td&gt;
&lt;td&gt;临时预览、功能联调&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;预签名链接&lt;/td&gt;
&lt;td&gt;单个对象、限时&lt;/td&gt;
&lt;td&gt;不走自定义域名&lt;/td&gt;
&lt;td&gt;到期自动失效&lt;/td&gt;
&lt;td&gt;私有文件的临时分享&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;结论很直接：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;正式图床只推荐自定义域名这一条路&amp;lt;/span&amp;gt;。它走的是你自己域名下的子域名（比如 &lt;code&gt;img.example.com&lt;/code&gt;），能吃满 Cloudflare 的边缘缓存，图片被反复访问时大部分请求由缓存直接响应，回源次数少、速度也稳；缓存多久、哪些路径缓存，可以再用&lt;a href=&quot;/posts/cloudflare-cache-rules/&quot;&gt;缓存规则&lt;/a&gt;细调。&lt;/p&gt;
&lt;p&gt;绑定步骤：进入桶的设置页，在「自定义域名」（Custom Domains）里添加一个子域名，域名必须是已经接入同一 Cloudflare 账户的 zone。Cloudflare 会自动创建对应的 &lt;a href=&quot;/posts/cloudflare-dns-records/&quot;&gt;DNS 记录&lt;/a&gt;并签发证书，状态从「正在初始化」变成「已启用」后，用 &lt;code&gt;https://img.example.com/图片键名&lt;/code&gt; 就能访问桶里的对象，全程不用自己碰证书和回源配置。&lt;/p&gt;
&lt;p&gt;:::warning
r2.dev 只适合开发调试，别拿它当正式图床。它是 Cloudflare 提供的共享子域名，官方明确定位为开发用途：有限速、不支持自定义缓存规则，也享受不到 WAF 等安全策略。联调时开一下没问题，博客上线前务必切到自定义域名。
:::&lt;/p&gt;
&lt;p&gt;还有一条安全边界：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;桶一旦公开，等于里面的每个对象全世界可读&amp;lt;/span&amp;gt;，任何人拿到键名就能访问。所以图床桶里只能放本来就打算公开的图片，备份、私有文件永远不要往公开桶里放——这也是入门篇强调图床桶与备份桶从第一天就分开建的原因。&lt;/p&gt;
&lt;h2&gt;五、生命周期规则：让旧备份自己消失&lt;/h2&gt;
&lt;p&gt;第四个问题不用写脚本删，R2 自带对象生命周期规则（Object Lifecycle Rules）：在控制台按桶配置，满足条件的对象由平台自动处理。入口在桶的设置页「对象生命周期规则」，常用动作有三个：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;到期删除&lt;/strong&gt;：对象存满指定天数后自动删除。比如给备份桶加一条「前缀 &lt;code&gt;server-a/&lt;/code&gt;、存满 30 天删除」，第三节脚本每天往上同步的新备份就不用操心清理，30 天前的自动消失。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;转入低频访问类别&lt;/strong&gt;：对象存满指定天数后，从标准存储转到 Infrequent Access（低频访问）类别，存储单价更低，代价是取回时要收费。适合「必须留着、但几乎不会打开」的长期归档，比如季度全量备份。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;清理未完成的分片上传&lt;/strong&gt;：大文件分片上传中断会留下残片，残片同样占容量。加一条「中止并清理超过 7 天未完成的分片上传」，避免这类隐形占用越攒越多。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;一个实用的组合是：备份桶前缀按服务器分，统一 30 天删除；其中每月第一份全量包打到单独的 &lt;code&gt;archive/&lt;/code&gt; 前缀下，7 天后转低频、保留一年。热数据自动滚动、冷数据低价长存，桶的容量曲线自己会收敛，不需要任何外部清理脚本。&lt;/p&gt;
&lt;h2&gt;六、访问密钥管理：Token 的权限边界&lt;/h2&gt;
&lt;p&gt;前面所有操作都建立在一对 Access Key 上，最后把凭据本身管好。在控制台 R2 页面进入「管理 R2 API 令牌」（Manage R2 API Tokens）创建 Token 时，有三个维度可以收紧：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;权限级别&lt;/strong&gt;：分对象只读、对象读写、管理员读写三档。备份脚本只需要对象读写，图床的发布工具同理；只在确实要程序化建桶删桶时才用管理员档。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;作用范围&lt;/strong&gt;：可以指定 Token 只对某几个桶生效。给服务器 A 的备份 Token 就只授权 &lt;code&gt;anexns-backup&lt;/code&gt; 一个桶，它泄漏了也碰不到图床桶和其他数据。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;有效期&lt;/strong&gt;：Token 可以设置到期时间，短期调试用的凭据别给永久。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;创建完成后页面会给出 Access Key ID 与 Secret Access Key，其中&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Secret Access Key 只显示一次，关掉页面就再也看不到&amp;lt;/span&amp;gt;，当场存进密码管理器。Token 的日常管理原则和普通 &lt;a href=&quot;/posts/cloudflare-api-token-ddns/&quot;&gt;API Token 一样&lt;/a&gt;：一台服务器一把、一个用途一把，绝不共用；怀疑泄漏时先新建一把替换上线，再删旧的，轮换不断档；每隔一段时间去列表里清掉已经没人用的僵尸 Token。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;预签名链接打开报签名错误（SignatureDoesNotMatch）或 403。&lt;/strong&gt; 按顺序查四点：生成链接的机器系统时间是否准确，签名对时钟偏差很敏感，服务器先对时；链接是不是拼在了自定义域名上——预签名只认 S3 API 端点；上传链接的 Content-Type 与实际请求头是否一致；用的密钥是否已被删除或轮换。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;rclone 报 403 AccessDenied，连桶都列不出来。&lt;/strong&gt; 多半是 Token 的作用范围不含这个桶，或者桶级授权下 rclone 在做桶探测——确认配置里有 &lt;code&gt;no_check_bucket = true&lt;/code&gt;。如果连 &lt;code&gt;rclone lsd r2:&lt;/code&gt; 都失败，先核对 endpoint 里的 account_id 和密钥有没有抄错、Token 是否选了对象读写以上权限。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;自定义域名绑定后打不开，或证书报错。&lt;/strong&gt; 先看桶设置里该域名的状态，没变成「已启用」之前访问不通是正常的，初始化通常要几分钟。再确认这个域名确实在同一个 Cloudflare 账户的 zone 里，跨账户的域名绑不上。状态正常仍报错的，检查有没有给这个子域名单独套过重定向或访问策略互相打架。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;图明明换了，访客看到的还是旧图。&lt;/strong&gt; 这是缓存的正常表现：同名覆盖上传后，边缘节点还存着旧版本。两个解法：发布流程里主动去控制台清一次该 URL 的缓存，或者更省心——图片文件名带版本号或哈希（如 &lt;code&gt;cover-a1b2c3.jpg&lt;/code&gt;），每次更新换新名，天然绕开缓存。博客图床推荐后者。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;r2.dev 访问偶尔 429。&lt;/strong&gt; 限速触发了，这正是它不适合正式用途的信号，按第四节切自定义域名即可根治。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;回到开头四个问题，现在都有了落点：临时分享私有文件用预签名链接，有效期自己定、到期自动作废；服务器备份用 rclone 加定时脚本自动同步，桶端交给生命周期规则滚动清理；博客图床绑自定义域名公开读，吃缓存、不限速，r2.dev 只留给调试；所有凭据按桶、按用途拆分 Token，最小权限发放。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;R2 的进阶用法，核心就是给每种数据选对访问方式&amp;lt;/span&amp;gt;：私有的用签名链接限时放行，要公开的用自定义域名大大方方分发，要长久留存的用生命周期规则自动归档。方式选对了，剩下的都是体力活，而体力活已经全部交给脚本和平台了。&lt;/p&gt;
</content:encoded></item><item><title>R2 对象存储实战：图床与备份目标</title><link>https://www.anexns.cloudns.org/posts/cloudflare-r2-storage/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-r2-storage/</guid><description>S3 兼容、出口流量不收费：R2 建桶与访问凭据、rclone 对接全流程、绑自定义域名做图床、再把它接成服务器备份的异地副本，以及公开桶的安全边界。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;服务器运维做到一定阶段，总会撞上两个存储问题：图片和附件放哪儿、备份往哪儿存。放服务器本地，磁盘迟早爆，迁服务器时还得跟着搬；放传统对象存储，存是便宜了，可一旦做图床给人看、给人下载，出口流量费会按 GB 往外冒，账单比存储费还吓人。&lt;/p&gt;
&lt;p&gt;Cloudflare 的 R2 就是冲着这两个痛点来的：它是一个 S3 兼容的对象存储，API 和生态工具跟 Amazon S3 通用，但&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;出口流量（egress）完全不收费&amp;lt;/span&amp;gt;。这一条决定了它特别适合两个场景：对外分发的图床，以及服务器备份的异地副本。本篇就把这条线走通：先讲清对象存储的概念，再开通建桶、拿凭据、用 rclone 对接、绑域名做图床、接上备份流程，最后把公开桶的安全边界划清楚。&lt;/p&gt;
&lt;h2&gt;一、对象存储是什么&lt;/h2&gt;
&lt;p&gt;对象存储和我们平时用的文件系统不是一回事。文件系统是树状的：目录套目录，文件挂在某一级下面，还能改名、移动、追加写入。对象存储是平的：只有一个个「桶」（bucket），桶里平铺着一个个「对象」（object），每个对象由一个键（key）标识。键里可以带斜杠，看起来像路径，但那只是命名约定，底层并不存在真正的目录。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;文件系统（如 ext4）&lt;/th&gt;
&lt;th&gt;网盘（如各类云盘）&lt;/th&gt;
&lt;th&gt;对象存储（如 R2、S3）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;组织方式&lt;/td&gt;
&lt;td&gt;树状目录层级&lt;/td&gt;
&lt;td&gt;文件夹层级，面向人浏览&lt;/td&gt;
&lt;td&gt;桶 + 键，扁平结构&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;访问方式&lt;/td&gt;
&lt;td&gt;本地系统调用、挂载&lt;/td&gt;
&lt;td&gt;客户端、网页、同步盘&lt;/td&gt;
&lt;td&gt;HTTP API（S3 协议）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;修改文件&lt;/td&gt;
&lt;td&gt;可局部追加、随机写&lt;/td&gt;
&lt;td&gt;整文件上传下载&lt;/td&gt;
&lt;td&gt;只能整对象上传覆盖&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;扩展性&lt;/td&gt;
&lt;td&gt;受单机磁盘上限约束&lt;/td&gt;
&lt;td&gt;受套餐容量约束&lt;/td&gt;
&lt;td&gt;容量近乎无限，按量付费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合放什么&lt;/td&gt;
&lt;td&gt;系统与程序运行数据&lt;/td&gt;
&lt;td&gt;个人文档、协作文件&lt;/td&gt;
&lt;td&gt;图片、附件、备份包、静态资源&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这个区别决定了用法：对象存储不适合拿来「挂载当硬盘使」，它适合的是「把一整个文件交出去、再按 URL 或 API 取回来」。图床的图片、备份打成的 tar 包，正好都是这种整存整取的形态。&lt;/p&gt;
&lt;p&gt;还有一个新手常踩的认知点：键里的斜杠只是名字的一部分。&lt;code&gt;blog/2026/cover.jpg&lt;/code&gt; 和 &lt;code&gt;blog/2025/cover.jpg&lt;/code&gt; 在存储层就是两个毫不相干的对象，不存在一个叫 blog 的真实文件夹。所以「改名」在对象存储里约等于「复制一份到新键、再删掉旧键」，「列目录」则是按前缀做的一次筛选查询。理解了这一点，后面用 rclone 看到 &lt;code&gt;copy&lt;/code&gt;、&lt;code&gt;sync&lt;/code&gt; 这类整对象操作时就不会别扭了：它本来就是为这种模型设计的。&lt;/p&gt;
&lt;h2&gt;二、R2 的差异化卖点&lt;/h2&gt;
&lt;p&gt;对象存储不是新东西，S3 已经当了十几年的事实标准。R2 的差异点主要有两个：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一，出口流量费为零。&lt;/strong&gt; 传统云厂商的对象存储，存储单价看着便宜，但数据从桶里流出去要按 GB 收 egress 费用。做图床最怕这个：图被刷得越多，账单越高，热门内容反而成了负担。R2 把出口费砍掉之后，图床和文件分发的成本只剩存储与请求数两项，可预测性完全不一样。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二，S3 兼容 API。&lt;/strong&gt; R2 没有发明一套新协议，而是兼容 S3 的接口。这意味着 rclone、各类 SDK、备份工具、图床程序里现成的「S3 存储」选项，换个端点和凭据就能指向 R2，不用等生态慢慢适配。&lt;/p&gt;
&lt;p&gt;取舍也要说一句：如果你的业务深度绑定某一家云的内网生态（比如同厂的计算服务走内网拉数据、要最细粒度的企业级权限策略），原厂 S3 仍然更顺手；但对个人站点、图床、异地备份这类场景，R2 的账算得过来、工具链又通用，基本没有短板。具体价格与免费额度各家时有调整，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要拿任何文章里的数字当准数，以 Cloudflare 官方定价页为准&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;R2 的计费结构可以粗略理解成三块：存了多少数据（按 GB 按月计）、做了多少次操作（读、写、列举等请求按次计，不同操作单价不同）、以及流出多少流量——第三块正是被免掉的那块。免费额度也是按这三块分别给的，个人博客量级的图床和几台服务器的备份，通常在免费额度内就能跑很久；但一旦图床被大量引用、或者备份频率拉得很高，最先涨起来的往往是请求数而不是容量，这一点在第八节讲保留策略时还会提到。&lt;/p&gt;
&lt;h2&gt;三、开通与建桶&lt;/h2&gt;
&lt;p&gt;R2 在 Cloudflare 控制台左侧菜单里，第一次进入会要求先开通。按控制台当前的流程走，一般需要确认计费信息（免费额度之内不扣费，但开通动作本身可能要求绑定支付方式），照提示完成即可。&lt;/p&gt;
&lt;p&gt;建桶时有三个注意点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;桶名全局唯一&lt;/strong&gt;，且创建后不能改名。命名建议带上用途和归属前缀，比如 &lt;code&gt;anexns-images&lt;/code&gt;、&lt;code&gt;anexns-backup&lt;/code&gt;，以后桶多了不至于分不清。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;区域（Location）&lt;/strong&gt; 建桶时可选就近的区域提示，选完不能改。图床桶选离访客近的区域，备份桶无所谓，选默认也可以。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;一个桶只干一件事&lt;/strong&gt;。图床桶和备份桶从第一天就分开建，后面第五节会讲为什么这是安全上的硬要求。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;桶建好后，控制台里能看到它的对象列表、用量统计和设置入口。设置里有两处值得先扫一眼：一是「公开访问」区域，自定义域名和 r2.dev 都在这里开关，第六、第七节会细讲；二是「对象生命周期规则」，决定旧对象多久自动删，第八节细讲。现在这两处都不用动，先保持默认的私密状态。&lt;/p&gt;
&lt;p&gt;建好桶之后先不用急着传文件，下一步是拿访问凭据。&lt;/p&gt;
&lt;h2&gt;四、凭据体系：API Token 与 S3 端点&lt;/h2&gt;
&lt;p&gt;R2 有两套访问方式：控制台网页是给人用的，程序访问走 S3 API，凭据是一对 Access Key ID 与 Secret Access Key。在控制台进入 R2 的「管理 R2 API 令牌」（Manage R2 API Tokens）页面，创建一个 API Token：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;权限选「对象读和写」（Object Read &amp;amp; Write）即可满足图床与备份的读写需求，不要图省事选管理员级权限。&lt;/li&gt;
&lt;li&gt;可以把令牌的作用范围限定到指定的桶，这样就算凭据泄露，损失也被锁在这一个桶里。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
令牌的 Secret Access Key 只在创建时完整显示一次，关掉页面就再也看不到，只能删掉重建。创建后立刻存进密码管理器或服务器的受控配置文件，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把密钥写进公开仓库、博客文章或截图里&amp;lt;/span&amp;gt;。同时给每个用途单独发令牌：图床一个、备份一个，出事时只吊销对应的那一个，不互相牵连。
:::&lt;/p&gt;
&lt;p&gt;创建完成后记下三样东西，后面 rclone 配置全靠它们：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Access Key ID&lt;/strong&gt;：令牌的公开标识。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Secret Access Key&lt;/strong&gt;：令牌的密钥，只出现一次。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;S3 端点地址&lt;/strong&gt;：格式固定为 &lt;code&gt;https://&amp;lt;accountid&amp;gt;.r2.cloudflarestorage.com&lt;/code&gt;，其中 &lt;code&gt;&amp;lt;accountid&amp;gt;&lt;/code&gt; 是你的 Cloudflare 账户 ID，在控制台右侧栏或 R2 概览页能找到。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;令牌的日常管理还有两件事值得养成习惯。一是定期轮换：每隔几个月新建一个令牌、把各服务器和工具切换过去、确认无误后删掉旧令牌，整个过程业务不中断，泄露窗口却被压到最短。二是心里有本账：哪个令牌发给了哪台机器、哪个工具，在密码管理器里记一行；真出事时，打开 R2 的令牌列表就能按图索骥地吊销，不用把全部凭据推倒重来。反过来，如果某个令牌你已经想不起来用在哪了，那它大概率可以先删掉观察几天——没人来报障，就说明它确实闲置，留着只是风险。&lt;/p&gt;
&lt;h2&gt;五、rclone 对接全流程&lt;/h2&gt;
&lt;p&gt;rclone 是对接对象存储最顺手的命令行工具，支持的后端里正好有 S3，并且专门给了 Cloudflare 的 provider 预设。在服务器上装好 rclone 后，新建一个远程配置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;rclone config
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;交互流程里依次选 &lt;code&gt;n&lt;/code&gt;（新建）、名字填 &lt;code&gt;r2&lt;/code&gt;、存储类型选 &lt;code&gt;s3&lt;/code&gt;、provider 选 &lt;code&gt;Cloudflare&lt;/code&gt;，然后填入上一步的三样东西。最终生成的配置（位于 &lt;code&gt;~/.config/rclone/rclone.conf&lt;/code&gt;）核心字段长这样，逐行对照检查：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[r2]
type = s3
provider = Cloudflare
access_key_id = 你的AccessKeyID
secret_access_key = 你的SecretAccessKey
endpoint = https://&amp;lt;accountid&amp;gt;.r2.cloudflarestorage.com
acl = private
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个字段的含义：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;type = s3&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;走 S3 协议对接，这是 R2 兼容的根本&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;provider = Cloudflare&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;套用 Cloudflare 预设，省去一堆签名与分块参数的手工调整&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;endpoint&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;R2 的 S3 端点，必须换成你自己账户的地址&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;acl = private&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;默认对象不公开，公开与否由桶级设置统一管，别在这里放开&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;在动手实测之前，先把 rclone 几个核心命令的分工理清，免得用混：&lt;code&gt;copy&lt;/code&gt; 是「把源的新文件和改过的文件补到目标去」，目标里多出来的文件它不管，最安全；&lt;code&gt;sync&lt;/code&gt; 是「让目标变成源的镜像」，源里没有的，目标里就删掉，适合本地图库往图床桶做镜像，不适合备份留存；&lt;code&gt;move&lt;/code&gt; 是 copy 完再删源，搬家时才用；&lt;code&gt;check&lt;/code&gt; 只比对两边差异、不动数据，想审计备份完整性时用它；&lt;code&gt;size&lt;/code&gt; 统计一个桶或前缀占了多少空间、多少个对象，月底对账时顺手跑一下。这几个命令对本地目录和远程桶是同一套语法，学会一次，本地与云端通用。&lt;/p&gt;
&lt;p&gt;配置好后先做连通性实测，列出桶、传一个小文件、再删掉：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 列出 r2 远程下的所有桶
rclone lsd r2:

# 列出某个桶里的内容
rclone ls r2:anexns-backup

# 上传一个测试文件
rclone copy /tmp/test.txt r2:anexns-backup/test/

# 下载回来验证
rclone copy r2:anexns-backup/test/test.txt /tmp/test-back.txt

# 删除测试文件
rclone delete r2:anexns-backup/test/test.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;能列、能传、能下、能删，说明凭据与端点都对了。日常用得最多的三个动作是 &lt;code&gt;copy&lt;/code&gt;（只增不减，目标多出来的文件不动）、&lt;code&gt;sync&lt;/code&gt;（让目标与源完全一致，源里删了的，目标也会删）和 &lt;code&gt;ls&lt;/code&gt;/&lt;code&gt;size&lt;/code&gt;（看内容与占用）。其中 &lt;code&gt;sync&lt;/code&gt; 是双刃剑，用在备份轮转上很方便，但参数写反方向会把桶里的东西删干净，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;第一次对任何桶执行 sync 前，先加 --dry-run 空跑一遍看它打算删什么&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h3&gt;把 R2 接成备份的异地副本&lt;/h3&gt;
&lt;p&gt;在 &lt;a href=&quot;/posts/linux-backup-strategy/&quot;&gt;服务器备份策略&lt;/a&gt; 一篇里，备份的主线是先用 rsync 把数据落到本地备份目录、形成可靠的本地副本。R2 在这条链里的位置是「再往外送一份」：本地备份负责恢复速度，R2 负责扛住整机损毁、机房事故这类本地副本跟着一起没的灾难。脚本上就是在本地 rsync 备份脚本的最后追加一段 rclone 同步：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
# 本地备份目录（rsync 已经把数据落到这里）
BACKUP_DIR=/data/backup
# R2 上的备份桶，按日期分目录存放
DEST=&quot;r2:anexns-backup/$(date +%F)&quot;

# 把当天备份同步一份到 R2
rclone copy &quot;$BACKUP_DIR&quot; &quot;$DEST&quot; \
  --transfers 4 \
  --retries 3 \
  --log-file /var/log/r2-backup.log \
  --log-level INFO

# 只保留最近 30 天的异地副本，更早的交给生命周期规则清理（见第八节）
echo &quot;R2 sync done: $DEST&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意这里用的是 &lt;code&gt;copy&lt;/code&gt; 不是 &lt;code&gt;sync&lt;/code&gt;：备份场景只往上添、按日期分目录，天然不需要删除动作，用 &lt;code&gt;copy&lt;/code&gt; 从根上避免误删。目录按日期切分之后，过期清理交给桶的生命周期规则自动完成，脚本本身不用操心删旧。&lt;/p&gt;
&lt;p&gt;到这一步，存储链就闭环了：服务器本地有一份 rsync 备份（恢复快），R2 里有一份异地副本（扛灾难），两边各司其职。&lt;/p&gt;
&lt;h2&gt;六、做图床：绑自定义域名&lt;/h2&gt;
&lt;p&gt;备份桶是给自己看的，图床桶是给全世界看的，开启公开访问的方式有两种，定位完全不同：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;r2.dev 临时域名&lt;/strong&gt;：在桶的设置里开启后，会得到一个 &lt;code&gt;https://pub-xxxx.r2.dev&lt;/code&gt; 形式的地址，立刻能用。但它有速率限制、没有缓存优化，官方定位就是开发调试用。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;r2.dev 只适合临时测试，正式图床不要用它对外&amp;lt;/span&amp;gt;，一是慢，二是这个地址毫无辨识度，换桶就全废。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;自定义域名（正式做法）&lt;/strong&gt;：在桶设置里选择「连接域名」（Connect Domain），填一个你自己的子域名，比如 &lt;code&gt;img.anexns.com&lt;/code&gt;，Cloudflare 会自动给这个域名建好 DNS 记录并指向桶。之后访问 &lt;code&gt;https://img.anexns.com/path/to/pic.jpg&lt;/code&gt; 就是桶里对应键的对象。用自己域名的好处是：流量顺带走 Cloudflare CDN 的缓存与规则体系（前面系列讲的缓存规则、WAF 都能罩住它），而且将来换存储后端时，域名不变、外链不用改。&lt;/p&gt;
&lt;p&gt;上传工作流任选其一，讲清最通用的 rclone 路线：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 单张图上传到图床桶
rclone copy ./cover.jpg r2:anexns-images/blog/

# 上传后它的公开地址就是
# https://img.anexns.com/blog/cover.jpg

# 批量同步一个目录（本地图库镜像到桶里）
rclone copy ./images r2:anexns-images/images
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三种上传方式对比一下，按场景选：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方式&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;th&gt;特点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;控制台网页上传&lt;/td&gt;
&lt;td&gt;临时传一两个文件&lt;/td&gt;
&lt;td&gt;不用装工具，但批量和大文件体验一般&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;rclone 命令行&lt;/td&gt;
&lt;td&gt;批量同步、脚本自动化&lt;/td&gt;
&lt;td&gt;可进定时任务，博客图库整体迁移靠它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;图床工具/编辑器插件&lt;/td&gt;
&lt;td&gt;写文章时随手贴图&lt;/td&gt;
&lt;td&gt;上传完自动生成链接插入正文，效率最高&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;写博客时用图床插件或编辑器自带的上传工具也可以，它们大多支持 S3 端点，把端点、桶名、访问域名按第四节的参数填进去即可。无论哪种工具，记住一点：上传用的是 API 凭据，访问用的是公开域名，两条路互相独立。&lt;/p&gt;
&lt;p&gt;再补两个图床的日常习惯。一是上传前先压缩：博客配图在本地过一遍压缩、转成合适的尺寸和格式再传，省的不只是存储，还有访客打开页面的等待时间，CDN 缓存救不了首访的慢。二是文件名别用纯顺序数字：&lt;code&gt;1.jpg&lt;/code&gt;、&lt;code&gt;2.jpg&lt;/code&gt; 这种名字等于把全站图片的地址规律拱手送人，谁都能顺着编号往下扒；带上年月目录再加一段随机串或原文件名的哈希，既防遍历，自己按月份找图也方便。&lt;/p&gt;
&lt;h2&gt;七、公开桶的安全边界&lt;/h2&gt;
&lt;p&gt;公开访问一旦开启，含义必须理解透：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;公开桶里的每一个对象，任何人拿到 URL 都能读&amp;lt;/span&amp;gt;，没有登录、没有鉴权，知道路径就能下。这正是图床想要的效果，但也划出了三条硬边界：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;备份桶永远不要开公开&lt;/strong&gt;。备份里有数据库导出、配置文件、甚至密钥材料，公开等于把服务器的底裤挂上网。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;图床桶和备份桶必须分开&lt;/strong&gt;，连 API 令牌都分开发（第四节已经强调过）。分开之后，图床桶就算被塞满垃圾、被盗刷流量，也波及不到备份。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;往图床桶里只放「本来就打算公开」的东西&lt;/strong&gt;。截图里如果带了后台界面、订单信息、聊天记录，先打码再传；传上去再删，缓存里可能还留着。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;防盗链只能算锦上添花：可以在 Cloudflare 的 WAF 或规则里按 Referer 限制图片只能被自己的站点引用，挡住随手盗链的外站。但要明白，Referer 可以伪造，这招防的是「被别的网站直接嵌图耗你的流量」，不是访问控制，真正的私密文件从一开始就不该进公开桶。&lt;/p&gt;
&lt;p&gt;:::warning
再补一个容易忽略的点：公开桶的流量虽然不收出口费，但请求数和存储仍在计费口径内（具体以官方定价页为准）。别把公开桶的地址当成免费网盘到处分发大文件，被人当下载站刷起来，麻烦的不只是账单，还有滥用投诉找上门。
:::&lt;/p&gt;
&lt;h2&gt;八、生命周期规则：让旧备份自动过期&lt;/h2&gt;
&lt;p&gt;备份只进不出，桶会越堆越大。R2 支持给桶设置生命周期规则（Lifecycle Rules），在控制台桶设置的「对象生命周期规则」里添加，思路和备份保留策略对齐即可：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;按前缀匹配&lt;/strong&gt;：备份桶里对象按日期目录存放，规则作用于整个桶或指定前缀都行。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;按天数过期&lt;/strong&gt;：比如「对象上传满 30 天后自动删除」，和第五节脚本里「只保留最近 30 天」的口径保持一致，脚本只管往上同步，删旧的活交给规则，不会出现两边打架。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;清理未完成的分片上传&lt;/strong&gt;：再加一条「中止超过 7 天未完成的分段上传」的规则，避免大文件传一半留下的碎片长期占空间，这类碎片在控制台文件列表里看不见，却实实在在占着容量。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;图床桶一般不需要过期规则，图片是长期资产；真要控制体积，靠的是上传前的压缩与规格约束，而不是事后删图。&lt;/p&gt;
&lt;p&gt;保留天数怎么定，和备份策略篇里的方法一致：先想清楚「最坏情况下，我需要回到几天前的状态」，再留出一倍以上的余量。30 天是个常见的平衡点——足够覆盖「删错东西一周后才发现」这类迟钝事故，又不至于让容量无限滚大。如果备份包体积不小，可以把频率和保留做分层：近一周的日备全留、更早的只留每周一份，这在脚本侧按目录分前缀、再给不同前缀配不同过期天数就能实现，规则各管一段，互不影响。&lt;/p&gt;
&lt;h2&gt;九、排障小节&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. rclone 连不上：报错 403 或 SignatureDoesNotMatch&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;按顺序查三样：端点地址是不是自己账户的（最常见是抄了别人的示例没改 &lt;code&gt;&amp;lt;accountid&amp;gt;&lt;/code&gt;）；Access Key ID 与 Secret 有没有复制串行、带空格；服务器系统时间准不准——S3 签名对时钟敏感，服务器时间偏差过大时签名会直接被判无效，先用 &lt;code&gt;timedatectl&lt;/code&gt; 确认 NTP 同步正常，再怀疑凭据本身。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 绑了自定义域名，访问图片报 404&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;先分清是「桶里没这个对象」还是「域名没指对」：用 rclone &lt;code&gt;ls&lt;/code&gt; 确认对象确实在、键的路径和 URL 拼写完全一致（大小写敏感）；再去 DNS 里看那条记录是不是绑域名时自动生成的那条，中途手动改过解析就会指偏。刚绑完域名立刻访问也可能撞上生效延迟，等几分钟再试。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 上传成功，但公开地址访问 403&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;对象在桶里、域名也对，403 基本就是公开设置没生效：检查这个桶开的是 r2.dev 还是自定义域名，自定义域名的连接状态是否显示已激活；如果只开了其中一种，就只能用对应的地址访问，拿着另一种地址去开必然是 403。另外确认你访问的不是备份桶——备份桶不开公开是设计如此，不是故障。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 大文件上传中断，桶里留下碎片&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;几百 MB 以上的备份包走的是分片上传，中途断网会在桶里留下未完成的碎片，文件列表里看不见、容量却占着。rclone 重跑同一条 &lt;code&gt;copy&lt;/code&gt; 命令通常能续上或重新传完；长期治理靠第八节那条「中止超期未完成分片上传」的生命周期规则兜底。如果某个大文件反复传不上去，先查服务器出口网络质量，再考虑把备份包在本地切成小块分开传。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. sync 之后桶里文件变少了&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;多半是 &lt;code&gt;sync&lt;/code&gt; 的方向或目标写反了。&lt;code&gt;sync&lt;/code&gt; 会让目标与源完全一致，包括删除。恢复思路是先停掉一切定时任务，再看 rclone 日志确认删除范围；这也是第五节反复强调新桶先 &lt;code&gt;--dry-run&lt;/code&gt; 的原因。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;R2 是 S3 兼容的对象存储，杀手锏是出口流量不收费，天生适合图床分发与异地备份。&lt;/li&gt;
&lt;li&gt;桶按用途分开建：图床桶开公开、备份桶永远私密；API 令牌按桶、按用途分别发放，权限收敛到最小。&lt;/li&gt;
&lt;li&gt;rclone 用 &lt;code&gt;provider = Cloudflare&lt;/code&gt; 对接，端点格式是 &lt;code&gt;https://&amp;lt;accountid&amp;gt;.r2.cloudflarestorage.com&lt;/code&gt;；备份同步优先用 &lt;code&gt;copy&lt;/code&gt;，&lt;code&gt;sync&lt;/code&gt; 先 dry-run。&lt;/li&gt;
&lt;li&gt;图床正式访问走自定义域名，顺带吃 CDN 缓存；r2.dev 只用于临时测试。&lt;/li&gt;
&lt;li&gt;备份链路分工：本地 rsync 管恢复速度，R2 管异地容灾，生命周期规则管过期清理，三者口径要一致。&lt;/li&gt;
&lt;li&gt;价格与免费额度会变，涉及数字一律以官方定价页为准。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>重定向规则实战：老链接一个都不能丢</title><link>https://www.anexns.cloudns.org/posts/cloudflare-redirect-rules/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-redirect-rules/</guid><description>改版换域名后老链接全变 404，用 Cloudflare 重定向规则一次配好：www 规范化、整目录通配符迁移、整站换域名与上千条链接批量导入，附状态码选型与避循环排障。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;站点刚改完版，或者域名干脆换了新的，老链接点开全是 404：搜索引擎收录的页面、别人收藏夹里存的地址、其他网站链过来的外链，一夜之间全成了死路。重定向规则就是干这个的——在 Cloudflare 边缘直接告诉浏览器「这个地址搬走了，新家在这里」，老链接点开自动落到新页面，收录权重跟着走，访客也无感。&lt;/p&gt;
&lt;p&gt;这一篇不讲原理铺垫，全是配方：www 与裸域互跳、HTTP 跳 HTTPS、单个页面改名、整目录迁移、整站换域名，再加上几百上千条老链接的批量导入方法。每条配方都给出控制台里逐项照填的值，抄完部署就能用。&lt;/p&gt;
&lt;p&gt;官方文档：https://developers.cloudflare.com/rules/url-forwarding/&lt;/p&gt;
&lt;h2&gt;一、重定向规则在哪配：一条规则的构成&lt;/h2&gt;
&lt;p&gt;登录 Cloudflare 控制台，选中目标域名，左侧进入 &lt;strong&gt;Rules → Redirect Rules&lt;/strong&gt;，点 &lt;strong&gt;Create rule&lt;/strong&gt; 新建。新建时先选匹配方式，二选一：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Wildcard pattern（通配符模式）&lt;/strong&gt;：直接填一个带 &lt;code&gt;*&lt;/code&gt; 的 Request URL 模式，所见即所得，本篇所有配方都用它；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Custom filter expression（自定义筛选表达式）&lt;/strong&gt;：用 &lt;code&gt;http.host&lt;/code&gt;、&lt;code&gt;http.request.uri.path&lt;/code&gt; 这类字段拼条件，适合「只对某个国家、某种设备生效」这类复合条件。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;不管选哪种，一条重定向规则拆开都是四件事：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;构成&lt;/th&gt;
&lt;th&gt;控制台字段&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;匹配条件&lt;/td&gt;
&lt;td&gt;Request URL（通配符模式）或筛选表达式&lt;/td&gt;
&lt;td&gt;什么样的请求会被这条规则拦下&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;目标 URL&lt;/td&gt;
&lt;td&gt;Target URL&lt;/td&gt;
&lt;td&gt;静态填固定地址；动态可用 &lt;code&gt;${1}&lt;/code&gt;、&lt;code&gt;${2}&lt;/code&gt; 引用源模式里第几个 &lt;code&gt;*&lt;/code&gt; 捕获的内容&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;状态码&lt;/td&gt;
&lt;td&gt;Status code&lt;/td&gt;
&lt;td&gt;301 / 302 / 307 / 308，怎么选看下一节&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;查询字符串&lt;/td&gt;
&lt;td&gt;Preserve query string 开关&lt;/td&gt;
&lt;td&gt;开启后，源 URL 的 &lt;code&gt;?a=1&amp;amp;b=2&lt;/code&gt; 原样带到目标 URL&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;先记住核心结论：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;重定向是「永久搬家」还是「临时借住」，全靠状态码表达，配错码比配错地址更难察觉&amp;lt;/span&amp;gt;。另外注意配额：免费版每个域名有 10 条这类单条重定向规则（Single Redirects），日常站点足够用，真不够了用第四节的批量重定向。同一域名下多条规则按列表从上到下匹配，命中第一条就执行，后面的不再看——具体规则放前面、宽泛规则放后面，是贯穿全篇的摆放原则。&lt;/p&gt;
&lt;p&gt;再补一个进阶形态：选了自定义筛选表达式时，目标 URL 可以选 &lt;strong&gt;Dynamic（动态）&lt;/strong&gt;，用表达式现场拼。以「按主机名整站跳转」为例，匹配条件填 &lt;code&gt;http.host eq &quot;old.com&quot;&lt;/code&gt;，目标表达式填：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;concat(&quot;https://new.com&quot;, http.request.uri.path)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;请求进来时，边缘把当前路径实时拼到新域名后面，效果和通配符版整站跳转一样。通配符模式胜在直观、不用学表达式语法；表达式模式胜在条件能叠加（比如「老域名＋路径以 /api 开头」才跳）。日常配方用通配符足够，遇到复合条件再切表达式。&lt;/p&gt;
&lt;h2&gt;二、状态码怎么选：301 / 302 / 307 / 308&lt;/h2&gt;
&lt;p&gt;四个码都是「去别处」，区别在两点：是永久还是临时、跳转后请求方法（GET / POST）和请求体保不保留。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;状态码&lt;/th&gt;
&lt;th&gt;永久 / 临时&lt;/th&gt;
&lt;th&gt;方法与请求体&lt;/th&gt;
&lt;th&gt;典型场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;301 Moved Permanently&lt;/td&gt;
&lt;td&gt;永久&lt;/td&gt;
&lt;td&gt;浏览器可能把 POST 改成 GET 再发&lt;/td&gt;
&lt;td&gt;页面永久改名、整站换域名、www 规范化&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;302 Found&lt;/td&gt;
&lt;td&gt;临时&lt;/td&gt;
&lt;td&gt;浏览器可能把 POST 改成 GET 再发&lt;/td&gt;
&lt;td&gt;活动页临时引流、短期维护跳转&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;307 Temporary Redirect&lt;/td&gt;
&lt;td&gt;临时&lt;/td&gt;
&lt;td&gt;方法与请求体原样保留&lt;/td&gt;
&lt;td&gt;接口地址临时切换、带表单提交的临时跳转&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;308 Permanent Redirect&lt;/td&gt;
&lt;td&gt;永久&lt;/td&gt;
&lt;td&gt;方法与请求体原样保留&lt;/td&gt;
&lt;td&gt;永久迁移且目标是接口、不能丢 POST&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;普通网页之间的跳转，访客发的都是 GET 请求，301 和 308 用起来没差别，选 301 最稳妥、兼容性最好；只有当被跳转的是 API 接口或表单提交地址时，才需要认真区分 307 / 308。控制台的状态码下拉里还有一个 303 See Other：强制把请求改成 GET 再发往目标，典型用途是表单 POST 提交后跳到一个结果页。日常迁移用不上它，知道有这回事即可。SEO 方面，搜索引擎只把 301 / 308 理解为「地址永久变更」，会把旧地址的收录与权重信号转移到新地址；&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;永久迁移如果误用 302，搜索引擎会继续保留旧地址的索引，新地址迟迟没有排名&amp;lt;/span&amp;gt;。反过来，临时跳转老老实实用 302 / 307，活动结束删掉规则即可，不留后遗症。&lt;/p&gt;
&lt;h2&gt;三、常用配方：逐个照抄&lt;/h2&gt;
&lt;p&gt;以下配方都用通配符模式。示例域名统一写 &lt;code&gt;example.com&lt;/code&gt;，替换成你自己的即可。每个配方默认状态码 301、&lt;strong&gt;Preserve query string 开启&lt;/strong&gt;（带参数的老链接跳转后不丢参数），另有说明的除外。&lt;/p&gt;
&lt;h3&gt;配方 1：www 与裸域互跳&lt;/h3&gt;
&lt;p&gt;把 &lt;code&gt;www.example.com&lt;/code&gt; 统一到裸域 &lt;code&gt;example.com&lt;/code&gt;：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;填什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Request URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://www.example.com/*&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Target URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://example.com/${1}&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Status code&lt;/td&gt;
&lt;td&gt;301&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;${1}&lt;/code&gt; 就是源模式里唯一的 &lt;code&gt;*&lt;/code&gt; 捕获到的部分，也就是路径（含多级目录，&lt;code&gt;*&lt;/code&gt; 可以跨 &lt;code&gt;/&lt;/code&gt; 匹配）。反过来裸域跳 www，把两个地址对调即可。前置条件别漏：&lt;code&gt;www&lt;/code&gt; 这条 DNS 记录必须存在且开启橙云代理，否则请求根本到不了 Cloudflare，规则写得再对也不会触发；DNS 记录的配法见 &lt;a href=&quot;/posts/cloudflare-dns-records/&quot;&gt;DNS 记录管理篇&lt;/a&gt;。&lt;/p&gt;
&lt;h3&gt;配方 2：HTTP 跳 HTTPS&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;填什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Request URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http://*&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Target URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://${1}&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Status code&lt;/td&gt;
&lt;td&gt;301&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这里的 &lt;code&gt;*&lt;/code&gt; 捕获的是 &lt;code&gt;http://&lt;/code&gt; 之后的全部内容（主机名＋路径），拼回 &lt;code&gt;https://&lt;/code&gt; 后面即可。其实整站强制 HTTPS 还有个更省事的开关：&lt;strong&gt;SSL/TLS → Edge Certificates → Always Use HTTPS&lt;/strong&gt;，打开后全域 HTTP 请求自动 301 到 HTTPS，一条规则都不用写。两者二选一即可，别叠加使用；证书与 HTTPS 的完整设置见 &lt;a href=&quot;/posts/cloudflare-ssl-tls/&quot;&gt;SSL/TLS 配置篇&lt;/a&gt;。&lt;/p&gt;
&lt;h3&gt;配方 3：单个页面改名&lt;/h3&gt;
&lt;p&gt;文章改了 slug、产品页换了路径，这类一对一跳转用静态目标最稳：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;填什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Request URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://example.com/old-page&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Target URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://example.com/new-page&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Status code&lt;/td&gt;
&lt;td&gt;301&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;源地址不要带 &lt;code&gt;*&lt;/code&gt;，精确匹配这一个 URL；目标地址写完整固定值（必须带 &lt;code&gt;https://&lt;/code&gt; 的完整 URL，只写路径不行）。还有个细节：&lt;code&gt;/old-page&lt;/code&gt; 和 &lt;code&gt;/old-page/&lt;/code&gt;（带尾斜杠）在匹配时是两个不同的 URL，源站如果两种写法都有流量，就补两条规则，或者改用表达式把路径写成集合：&lt;code&gt;http.request.uri.path in {&quot;/old-page&quot; &quot;/old-page/&quot;}&lt;/code&gt;，目标选静态。页面多起来之后不要在单条规则里堆几十条同类跳转，攒多了转第四节的批量方案。&lt;/p&gt;
&lt;h3&gt;配方 4：整目录迁移（通配符保留后缀）&lt;/h3&gt;
&lt;p&gt;博客从 &lt;code&gt;/blog/&lt;/code&gt; 搬到 &lt;code&gt;/posts/&lt;/code&gt;，几百篇文章的后缀（slug）保持不变，这是通配符最典型的用法：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;填什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Request URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://example.com/blog/*&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Target URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://example.com/posts/${1}&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Status code&lt;/td&gt;
&lt;td&gt;301&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;效果：&lt;code&gt;/blog/hello-world&lt;/code&gt; → &lt;code&gt;/posts/hello-world&lt;/code&gt;，&lt;code&gt;/blog/2024/01/review&lt;/code&gt; → &lt;code&gt;/posts/2024/01/review&lt;/code&gt;，一级目录平移、后面原样保留。&lt;/p&gt;
&lt;p&gt;这里藏着一个最容易踩的编号坑：&lt;code&gt;${n}&lt;/code&gt; 按源模式里 &lt;code&gt;*&lt;/code&gt; 出现的顺序编号，&lt;strong&gt;协议部分的 &lt;code&gt;*&lt;/code&gt; 也算一个&lt;/strong&gt;。如果源模式写成 &lt;code&gt;http*://example.com/blog/*&lt;/code&gt;（想同时匹配 HTTP 和 HTTPS），路径部分的捕获就变成了 &lt;code&gt;${2}&lt;/code&gt;，目标要写 &lt;code&gt;https://example.com/posts/${2}&lt;/code&gt;。写错一位，跳转目标会变成空段或字面量，上线前务必用真实链接验一遍。&lt;/p&gt;
&lt;h3&gt;配方 5：换域名整站跳转&lt;/h3&gt;
&lt;p&gt;老域名 &lt;code&gt;old.com&lt;/code&gt; 整体搬到 &lt;code&gt;new.com&lt;/code&gt;，路径全保留：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;填什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;所在域名&lt;/td&gt;
&lt;td&gt;&lt;code&gt;old.com&lt;/code&gt;（规则配在老域名下）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Request URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://old.com/*&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Target URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://new.com/${1}&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Status code&lt;/td&gt;
&lt;td&gt;301&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;三个前置条件：第一，新域名已经接入 Cloudflare 且站点可正常访问；第二，老域名哪怕源站已经关停，DNS 里也要留一条开启橙云的记录占位（随便一条 A 记录即可，流量在边缘就被跳走，不会真打到源站），否则请求进不了边缘、规则无从触发；第三，这条规则要放在老域名所有规则的最前面，避免被别的规则截胡。域名注册本身的转移与接入流程，见 &lt;a href=&quot;/posts/cloudflare-registrar-transfer/&quot;&gt;域名转入篇&lt;/a&gt;。&lt;/p&gt;
&lt;h3&gt;配方 6：子域名下线并入主站&lt;/h3&gt;
&lt;p&gt;独立博客子域名 &lt;code&gt;blog.example.com&lt;/code&gt; 不再维护，内容并进主站的 &lt;code&gt;/posts/&lt;/code&gt; 目录：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;填什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;所在域名&lt;/td&gt;
&lt;td&gt;&lt;code&gt;example.com&lt;/code&gt;（子域名与主域名同属一个 zone 时，规则配在该 zone 下即可）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Request URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://blog.example.com/*&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Target URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://example.com/posts/${1}&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Status code&lt;/td&gt;
&lt;td&gt;301&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;它本质是配方 4 的跨主机版：匹配条件里把主机名换成子域名，目标里把落点换成主站目录。同理，&lt;code&gt;shop.&lt;/code&gt;、&lt;code&gt;help.&lt;/code&gt; 这类退役子域名都能用同一形状收编，无非是目标目录不同。子域名的 DNS 记录同样要保持橙云，哪怕对应的服务早已下线。&lt;/p&gt;
&lt;p&gt;:::warning
重定向最怕成环：配方 1 把 www 跳到裸域，又在另一条规则里把裸域跳回 www；或者整站迁移后新域名上残留一条指回老域名的规则——两种都会让浏览器原地打转，最后报 ERR_TOO_MANY_REDIRECTS，访客眼里就是「网站打不开」。另一个同级大坑是范围失控：用 &lt;code&gt;https://example.com/*&lt;/code&gt; 这类全站通配符做跳转时，先想清楚后台、接口、验证文件这类特殊路径会不会被一起卷走，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把自己锁在管理后台门外，就是这么发生的&amp;lt;/span&amp;gt;。宽泛规则上线前，先用窄条件灰度，确认无误再放开。
:::&lt;/p&gt;
&lt;h2&gt;四、批量重定向：上千条老链接一次导入&lt;/h2&gt;
&lt;p&gt;单条规则适合「一类链接一条规则」；如果是整站迁移留下的几百上千条一对一映射（每篇老文章对应一个新地址，毫无规律可循），逐条建规则不现实，用 &lt;strong&gt;Bulk Redirects（批量重定向）&lt;/strong&gt;：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;它是&lt;strong&gt;账户级&lt;/strong&gt;功能：进入账户主页打开 &lt;strong&gt;Bulk Redirects&lt;/strong&gt;，先建一个 &lt;strong&gt;URL Redirect List（重定向列表）&lt;/strong&gt;，逐条添加「源 URL → 目标 URL」，也可以按官方模板用 &lt;strong&gt;CSV 文件导入&lt;/strong&gt;，几千条一次进；&lt;/li&gt;
&lt;li&gt;再建一条 &lt;strong&gt;Bulk Redirect Rule&lt;/strong&gt; 把列表绑上，规则生效后列表里的映射全部开始跳转；&lt;/li&gt;
&lt;li&gt;每条映射可带参数：状态码、是否保留查询字符串、是否包含子域名（Include subdomains）、是否子路径匹配（Subpath matching）、是否保留路径后缀（Preserve path suffix）——后三个开关决定一条映射能「顺带」覆盖多少相邻 URL，导入前先想清楚再勾。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;列表里躺着的就是一堆纯粹的一对一映射，长这样：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;源 URL&lt;/th&gt;
&lt;th&gt;目标 URL&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;https://example.com/2023/05/first-post.html&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://example.com/posts/first-post&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;https://example.com/Article/Show?id=812&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://example.com/posts/legacy-812&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;https://example.com/download/v1.zip&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://example.com/releases/v2.zip&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这种映射没有通配符可提炼——每条路径都独一无二，正是批量列表的主场。两个使用习惯值得养成：其一，列表是账户级的，同一个列表可以被账户下多个域名的批量规则引用，集团站、镜像站共用一份映射时不用重复维护；其二，后续增删映射只改列表、不用动规则，改完即时生效，适合上线后陆续补漏。&lt;/p&gt;
&lt;p&gt;免费版的配额是 5 个列表、合计 10,000 条 URL 重定向，中小站点的历史包袱绰绰有余。执行顺序上，单条重定向规则先于批量重定向执行：同一个 URL 两边都配了，以单条规则为准，正好用来给个别链接留「特例通道」。&lt;/p&gt;
&lt;h2&gt;五、老 Page Rules 的 Forwarding URL：该迁了&lt;/h2&gt;
&lt;p&gt;老站长可能还记得 Page Rules 里的 &lt;strong&gt;Forwarding URL&lt;/strong&gt;（URL 转发），当年配 www 跳转、域名跳转全靠它。它和转换规则一样属于上一代功能：Cloudflare 已从 2025 年 1 月起停止新建 Page Rules，存量规则虽还能跑，官方计划逐步自动迁移到新规则体系。与其等迁移，不如自己动手：一条 Forwarding URL 对应一条 Redirect Rule，照第三节配方重建即可。迁移时只有一个换算要注意：老写法里的占位符 &lt;code&gt;$1&lt;/code&gt;，在新规则里写作 &lt;code&gt;${1}&lt;/code&gt;；而且新模式是从完整 URL（含协议）开始数 &lt;code&gt;*&lt;/code&gt; 的，老模式不带协议时编号一致，带了 &lt;code&gt;http*&lt;/code&gt; 时要顺延一位——配方 4 里那个编号坑，迁移时最常翻车。&lt;/p&gt;
&lt;h2&gt;六、与转换规则的分工&lt;/h2&gt;
&lt;p&gt;一句话：要让浏览器地址栏变成新地址、让搜索引擎认新地址的，用重定向；地址不变、只在 Cloudflare 内部把请求换个路径递给源站的，用 URL Rewrite（改写）——两者在规则体系里的位置和更多改写配方，见 &lt;a href=&quot;/posts/cloudflare-rules-transform/&quot;&gt;规则转换篇&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;七、上线后怎么验&lt;/h2&gt;
&lt;p&gt;规则部署后等几十秒，先用 curl 看响应头，别急着开浏览器：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 看状态码和 Location 是否符合预期
curl -sI https://www.example.com/blog/hello-world | grep -iE &quot;HTTP/|location&quot;

# 跟完整条跳转链，确认最终落地且跳数正常
curl -sIL https://example.com/old-page -o /dev/null -w &quot;final: %{http_code}, hops: %{num_redirects}\n&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第一条应看到 &lt;code&gt;301&lt;/code&gt; 和指向新地址的 &lt;code&gt;location&lt;/code&gt;；第二条的 hops 正常应为 1–2，数字异常大或命令迟迟不结束，就是成环了。curl 通过后，再用浏览器无痕窗口点开老链接实测一次（无痕是为了避开浏览器对 301 的本地缓存——301 会被浏览器长期记住，改错了之后哪怕规则已修正，你自己的浏览器还可能拿着旧缓存跳错地方）。最后抽查几个带查询字符串、带多级目录的链接，确认参数和后缀都没丢。&lt;/p&gt;
&lt;p&gt;上线前还有一道保险：控制台 Rules 区域提供的 &lt;strong&gt;Rules simulator（规则模拟器）&lt;/strong&gt; 可以拿任意 URL 试跑，提前看它会命中哪条规则、跳到哪里。宽泛规则（整站、整目录）部署前先在模拟器里喂几个样本 URL——首页、深层文章页、带参数的链接各一个——比上线后等访客踩坑划算得多。&lt;/p&gt;
&lt;h2&gt;八、排障：规则不生效时按这个顺序查&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;DNS 不是橙云&lt;/strong&gt;：重定向在边缘执行，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;目标主机名的 DNS 记录如果是灰云（仅解析），流量直达源站，规则完全不会触发&amp;lt;/span&amp;gt;。先去 DNS 列表确认相关记录是橙云，尤其是配方 1、5 里的 www 和老域名占位记录。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;规则没启用或改错了域名&lt;/strong&gt;：确认规则状态为 Active，且配在请求实际进入的那个域名下（规则是域名级隔离的，配在 A 域名下的规则管不到 B 域名）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;被前面的规则截胡&lt;/strong&gt;：同类规则命中第一条即停。把不生效的规则往上拖，或检查前面是不是有更宽泛的规则先命中了；单条规则与批量列表撞车时，也是单条规则优先。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;重定向循环&lt;/strong&gt;：浏览器报 ERR_TOO_MANY_REDIRECTS、&lt;code&gt;curl -sIL&lt;/code&gt; 里 Location 反复横跳。逐条列出所有跳转的起点和终点画成链：A→B、B→A 是最典型的环；还有一种隐蔽环是目标地址本身又落进源模式的通配符范围（比如 &lt;code&gt;/posts/*&lt;/code&gt; 跳 &lt;code&gt;/posts/*&lt;/code&gt; 的自引用）。另外别只查 Cloudflare：源站 Nginx、程序框架自己配的跳转和边缘规则叠加，同样能拼出一条环。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;捕获编号错位&lt;/strong&gt;：目标 URL 里出现空段、字面量或少了一截路径，多半是 &lt;code&gt;${n}&lt;/code&gt; 数错了 &lt;code&gt;*&lt;/code&gt;，回配方 4 对照协议部分的 &lt;code&gt;*&lt;/code&gt; 重新数。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;跳是跳了，落地 404&lt;/strong&gt;：规则没问题，是目标地址本身不存在。用浏览器直接打开 Target URL 验证一遍，别在规则里找不存在的错。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;刚改完没变化&lt;/strong&gt;：等一分钟再测；浏览器测不准就以 curl 结果为准，301 的本地缓存是这里最常见的假象。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;重定向规则的全部要点，收拢起来就四句：地址永久变了用 301 / 308、临时借用用 302 / 307；一类链接一条通配符规则，&lt;code&gt;${1}&lt;/code&gt; 把后缀原样带走；成百上千条无规律映射交给批量重定向列表导入；上线后先 curl 看状态码和 Location、再无痕实测，重点防成环。老链接是站点多年攒下的资产，改版和换域名时把这一篇的配方过一遍，就能让它们一个都不丢。&lt;/p&gt;
</content:encoded></item><item><title>域名转入 Cloudflare Registrar 省续费</title><link>https://www.anexns.cloudns.org/posts/cloudflare-registrar-transfer/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-registrar-transfer/</guid><description>Cloudflare 卖域名不加价：转入的完整流程与前提、授权码与注册锁、转入即续一年的规则、不支持的后缀与转入前的检查清单，把每年的续费差价省下来。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;域名是每年都要交的「房租」。同一个域名，在不同注册商手里续费，价格能差出一截：有的第一年便宜得离谱，续费时却翻倍；有的续费价格看着还行，结账时又冒出 WHOIS 隐私保护费、邮箱转发费、管理费。Cloudflare Registrar 的玩法完全不同——它公开承诺按注册局的批发价出售和续费域名，不加价、不捆绑销售，WHOIS 隐私保护默认免费开启。对已经在用 Cloudflare 做 DNS 解析的人来说，把域名注册也一并搬过来，等于每年固定省下一笔差价，还能把「注册」和「解析」收进同一个控制台管理。&lt;/p&gt;
&lt;p&gt;本篇主线如下：先讲清为什么值得转、传统注册商的钱到底赚在哪；再过一遍转入的前提清单和转入前的检查动作；然后完整走一遍转入流程和账目规则；最后说转入后的日常管理、哪些情况不建议转，以及转移被拒时的逐项排查。整个过程不涉及换解析、不停站，只要前置动作做对，就是一次安静的后台搬家。&lt;/p&gt;
&lt;h2&gt;为什么把域名注册也搬过来&lt;/h2&gt;
&lt;p&gt;先要分清两个角色：注册商（Registrar）是你「买下并持有」域名的地方，负责向注册局登记你的所有权、处理续费和转移；DNS 解析商负责把域名指向服务器。两者可以是同一家，也可以分开。很多人最初在哪家买的域名，就一直在那家续费，从没想过注册这件事本身也能搬家。&lt;/p&gt;
&lt;p&gt;传统注册商的盈利点主要在三处：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;续费加价&lt;/strong&gt;：注册局给每个后缀定一个批发价，注册商在此基础上加价出售。首年促销价往往低于成本，靠后续年份的续费价把钱赚回来。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;增值捆绑&lt;/strong&gt;：WHOIS 隐私保护、企业邮箱、建站工具、SSL 证书等被拆开单独收费，结账页面层层加购。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;默认勾选&lt;/strong&gt;：自动续费默认开启且价格不透明，很多人是扣款短信来了才知道今年又涨了。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Cloudflare Registrar 的机制是反过来的：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;传统注册商（常见）&lt;/th&gt;
&lt;th&gt;Cloudflare Registrar&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;续费价格&lt;/td&gt;
&lt;td&gt;批发价基础上加价，逐年可能上调&lt;/td&gt;
&lt;td&gt;按注册局批发价，不加价&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;WHOIS 隐私保护&lt;/td&gt;
&lt;td&gt;常单独收费或首年免费&lt;/td&gt;
&lt;td&gt;默认免费开启&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;捆绑销售&lt;/td&gt;
&lt;td&gt;邮箱、建站、证书层层加购&lt;/td&gt;
&lt;td&gt;无捆绑，结账即标价&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;首年促销陷阱&lt;/td&gt;
&lt;td&gt;首年低价、续费翻倍很常见&lt;/td&gt;
&lt;td&gt;无促销价，也无续费涨幅套路&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;管理入口&lt;/td&gt;
&lt;td&gt;与解析、CDN 分属不同平台&lt;/td&gt;
&lt;td&gt;与 DNS、CDN 同一个控制台&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这里要把一句话说透：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Cloudflare 卖域名不赚差价，它赚的是让你把解析、CDN、安全这一整套服务都留在它这里。&amp;lt;/span&amp;gt;对用户来说这笔账很划算——域名本身按成本价续，省下的是每年都重复发生的支出，域名持有越久、数量越多，省得越明显。&lt;/p&gt;
&lt;p&gt;另一个容易被忽略的点是 WHOIS 隐私。域名注册信息（姓名、邮箱、电话、地址）默认会进入公开的 WHOIS 数据库，任何人都能查，这也是垃圾邮件和诈骗电话的一大来源。在 Cloudflare 这边，隐私保护默认开启且免费，公开查询只能看到被打码后的信息，不需要额外花钱买。&lt;/p&gt;
&lt;h2&gt;转入前提清单&lt;/h2&gt;
&lt;p&gt;不是所有域名随时都能转。发起转入之前，先逐项核对下面这张清单，任何一项不满足，流程都会在中途卡住：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;前提&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;域名已接入 Cloudflare&lt;/td&gt;
&lt;td&gt;转入功能只对已添加并激活（状态为 Active）的站点开放，先完成 DNS 接入再谈转注册&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;后缀在支持列表内&lt;/td&gt;
&lt;td&gt;Cloudflare 只支持一部分后缀的注册与转入，完整列表以官方文档和控制台为准&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;不在 60 天限制期内&lt;/td&gt;
&lt;td&gt;ICANN 规则：新注册未满 60 天、上一次转移未满 60 天的域名，不能再次转移&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;域名状态正常&lt;/td&gt;
&lt;td&gt;未被注册局或注册商锁定（除可手动解除的注册锁外）、无所有权争议、无欠费冻结&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;你能操作原注册商账号&lt;/td&gt;
&lt;td&gt;解锁、取授权码、确认放行都要在原注册商一侧完成&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;联系邮箱可用&lt;/td&gt;
&lt;td&gt;转移过程中的确认邮件会发到域名联系人邮箱，收不到信流程就走不下去&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;其中 60 天规则是 ICANN 的统一规定，不是 Cloudflare 一家的限制，目的是防止域名被盗转。刚买的域名想立刻搬家是搬不了的，先老老实实用满 60 天再说。&lt;/p&gt;
&lt;p&gt;:::warning
转入只改变「注册商」这一层，DNS 解析记录、指向的服务器、网站本身都不受影响。转移过程中解析照常工作，不需要停站，也不要因为要转入就去动任何解析记录。
:::&lt;/p&gt;
&lt;h2&gt;转入前检查：在原注册商一侧做的四件事&lt;/h2&gt;
&lt;p&gt;转入失败的案例，九成出在原注册商一侧的准备工作没做全。发起转入之前，按顺序做完这四件事：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一件：关闭注册锁（Transfer Lock）。&lt;/strong&gt; 域名默认通常处于锁定状态，锁着就无法转出。在原注册商的域名管理页找到「域名锁」「转移锁」一类的开关，将其关闭。关锁后域名处于可转移状态，这段时间里要保管好自己的注册商账号，别让其他风险钻空子。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二件：拿到授权码（AuthCode / EPP Code）。&lt;/strong&gt; 授权码是转移的「钥匙」，一串由原注册商生成的字符，在域名管理页一般有「获取授权码」「发送 EPP 码」之类的入口，有的会直接展示，有的会发送到联系人邮箱。复制时注意不要多带空格，大小写要原样保留。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三件：确认联系人邮箱能正常收信。&lt;/strong&gt; 转移确认、授权码发送、异常通知都走这个邮箱。如果当年注册时填的邮箱早已不用，先在原注册商处把联系人邮箱改成现用邮箱，再等信息同步后再发起转移。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第四件：看一眼到期日。&lt;/strong&gt; 这一点最容易被忽视，也最容易吃亏：&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;域名临近到期（比如只剩一两周）时不要贸然发起转入。&amp;lt;/span&amp;gt;转移需要数天时间，万一流程卡住、被拒或超时，域名可能在半路过期，轻则站点停摆，重则进入赎回期要花大价钱捞回来。稳妥的做法是先在原注册商处续费一年，等状态稳定后再转入——转入时还会再续一年，年限叠加不浪费，账目规则下文会讲。
:::&lt;/p&gt;
&lt;p&gt;四件事做完，再回到 Cloudflare 控制台发起转入，成功率就高得多。&lt;/p&gt;
&lt;h2&gt;转入流程：从发起到完成&lt;/h2&gt;
&lt;p&gt;准备就绪后，流程本身很简单，在 Cloudflare 控制台内完成：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;进入控制台，打开「Domain Registration（域名注册）」下的「Transfer Domains（转入域名）」页面，系统会列出你账号下已接入、且符合转入条件的域名。&lt;/li&gt;
&lt;li&gt;勾选要转入的域名。列表里没有的，通常是后缀不支持或站点未激活，对照前提清单逐项查。&lt;/li&gt;
&lt;li&gt;填写从原注册商拿到的授权码，一个域名一个码，不要填串。&lt;/li&gt;
&lt;li&gt;确认联系人信息（Registrant Contact）。这份信息会提交给注册局登记，必须真实准确；WHOIS 隐私保护会在展示层打码，但登记层的信息不能乱填。&lt;/li&gt;
&lt;li&gt;确认价格并付款。页面会明示这一年的续费价格，即该后缀的批发价，各后缀具体价格以控制台显示为准。&lt;/li&gt;
&lt;li&gt;提交后进入等待期。Cloudflare 会向原注册商发起转移请求，原注册商通常会给联系人邮箱发一封确认信，有的支持点击确认加速放行，不操作则等系统自动放行。&lt;/li&gt;
&lt;li&gt;转移完成后，域名出现在控制台的域名列表里，注册商一栏变为 Cloudflare，控制台会发邮件通知。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;时间预期上，顺利的话一两天，慢则五到七天，这主要取决于原注册商的放行速度，不在 Cloudflare 的控制范围内。等待期间解析一切照旧，不用守着刷新。部分原注册商会在收到转移请求后主动发信提供「立即批准」入口，点下去能把等待期压缩到几小时，收件箱里留意一下这类邮件。&lt;/p&gt;
&lt;h2&gt;转入的账目规则：为什么说不浪费钱&lt;/h2&gt;
&lt;p&gt;很多人担心：我在原注册商那里刚续的费还没用完，转入是不是白花了？不会。域名转移的账目规则由 ICANN 统一规定，核心就三条：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;转移本身不单独收费，但转入必须同时按一年续费。&lt;/strong&gt; 你在付款页看到的那笔钱，本质是买了一年续期，不是「过户费」。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;到期日在原有基础上顺延一年。&lt;/strong&gt; 比如域名原来到期日是 2027 年 3 月，转入完成后变为 2028 年 3 月。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;原注册商处的剩余年限完整保留，不清零。&lt;/strong&gt; 之前在原注册商续的年份一分不少地带过来，再叠加转入的这一年。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;把这三条合起来看：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;转入等于提前用批发价锁定了一年续期，任何已付的年限都不会损失。&amp;lt;/span&amp;gt;所以「刚续过费」和「快到期」都不构成推迟转入的理由——除了上文说的临近到期要先求稳这一种情况。&lt;/p&gt;
&lt;p&gt;需要注意的例外是：个别后缀的转移规则由其注册局单独制定，年限处理方式可能不同，遇到时以控制台在付款前展示的条款为准，不要想当然。&lt;/p&gt;
&lt;h2&gt;转入后管理：日常要确认的三件事&lt;/h2&gt;
&lt;p&gt;域名落到 Cloudflare 之后，日常管理都在同一个控制台里，顺手确认三项设置：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;自动续费（Auto-Renew）。&lt;/strong&gt; 建议保持开启。域名过期是小站长最惨烈的事故之一，过期后先是解析停摆，进了赎回期更是要付出数倍代价。自动续费按批发价扣款，没有涨价套路，开着比关着安心。当然，前提是账号绑定的支付方式有效，换卡后记得更新。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;注册锁（Transfer Lock）。&lt;/strong&gt; 转入完成后默认重新开启，这是防盗转的基本盘，平时不要关。只有将来要再转出时，才临时关闭并取授权码。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;WHOIS 隐私状态。&lt;/strong&gt; 在域名详情页确认隐私保护处于开启状态，公开 WHOIS 查询只会显示打码信息。可以用任意 WHOIS 查询工具搜一下自己的域名验证效果，看到的应该是注册商的代持信息而非你的真实邮箱电话。&lt;/p&gt;
&lt;p&gt;管理上的便利也很实在：续费、改解析、调 CDN 和 WAF 规则都在一个后台，不用再记另一个注册商的账号密码；域名和解析同属一家，也少了「注册商续费了但解析在别处过期」这类跨平台乌龙。&lt;/p&gt;
&lt;h2&gt;不支持与例外情况&lt;/h2&gt;
&lt;p&gt;把边界说清楚，省得白忙一场：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;部分后缀不支持转入。&lt;/strong&gt; Cloudflare 支持注册的后缀在持续增加，但仍有不少后缀（包括一些国家和地区后缀）不在列表内。这些域名可以继续在 Cloudflare 做 DNS 解析，只是注册必须留在原注册商。准确的支持列表以官方文档为准，控制台的转入页面搜不到某个域名时，先查列表再怀疑其他原因。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;个别后缀转移规则不同。&lt;/strong&gt; 少数后缀对转移有额外要求，比如需要人工审核、不支持授权码方式、或转移不自动续期，付款页和流程页会给出单独提示，按提示走即可。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;新域名可以直接在 Cloudflare 注册。&lt;/strong&gt; 以后有新项目要买新域名，不必先在别家买了再转，直接在控制台的域名注册页搜索购买，一样是批发价，省去 60 天等待期这一道手续。注意下单前确认后缀在支持列表内，以及首年价格即为常年价格、没有续费涨价问题。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;什么时候不建议转&lt;/h2&gt;
&lt;p&gt;省钱虽好，但有几种情况建议缓一缓，甚至不转：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;域名承载关键业务且临近到期。&lt;/strong&gt; 前面已经强调过：先在原注册商续费求稳，状态稳定后再转，差价不差这一年。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;刚注册或刚转入不满 60 天。&lt;/strong&gt; 规则所限，转不了，硬提交只会被拒。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;企业合规指定注册商。&lt;/strong&gt; 有些公司出于合规、审计或统一资产管理要求，指定域名必须放在特定注册商名下，这种情况以合规为准，个人站长则无此顾虑。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;域名正处于争议或交易流程中。&lt;/strong&gt; 所有权未定的域名不要动注册层面的任何操作，等事情落定再说。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;后缀不在支持列表。&lt;/strong&gt; 这属于客观转不了，继续用 Cloudflare 解析、注册留在原处，也是完全可行的组合，不要为了「统一」去换域名后缀，得不偿失。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;排障：转移被拒与迟迟未完成&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;转移被拒，按这个顺序逐项对：&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;注册锁还开着。&lt;/strong&gt; 回原注册商确认 Transfer Lock 确实已关闭，有些平台改完状态要等几分钟才生效，关完立刻提交可能仍被判定为锁定。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;授权码错误。&lt;/strong&gt; 重新获取一次授权码，注意复制时不要带首尾空格、不要把相似字符看错；授权码在重新生成后旧码会失效，以最新一封邮件或页面显示为准。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;撞上 60 天限制。&lt;/strong&gt; 查域名的注册日期和上次转移日期，任一未满 60 天都只能等，任何注册商都绕不过去。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;联系人邮箱没确认。&lt;/strong&gt; 有些转移需要联系人点击确认邮件，信可能进了垃圾箱，去翻一翻；一直没收到，回原注册商核对联系人邮箱是否正确。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;域名状态异常。&lt;/strong&gt; 欠费、被标记争议、注册局层面锁定（状态码里带 hold 字样）都会导致拒绝，这类要先联系原注册商客服解除。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;转入后解析异常：&lt;/strong&gt; 先冷静——转移不改动任何解析记录，异常基本与转移无关。按 DNS 排查的老思路走：查 NS 记录是否仍指向 Cloudflare、查 A / AAAA / CNAME 记录是否齐全、本地用 &lt;code&gt;dig&lt;/code&gt; 或在线工具验证解析结果。不会查的可以回看本系列前面的 DNS 记录详解一篇，方法完全通用。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 本地验证域名解析是否正常
dig +short example.com A
dig +short example.com NS

# 查看域名当前的注册与状态信息（确认注册商与锁定状态）
whois example.com | grep -iE &quot;registrar|status|expir&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;迟迟未完成：&lt;/strong&gt; 先确认时间，五个自然日以内都属于正常等待。超过这个范围，去原注册商后台看转移请求的状态——很多平台有「待转出」列表，可以直接看到请求卡在哪一步；有「批准转出」按钮的，点下去即可放行。原注册商处确认已放行、Cloudflare 侧仍无动静，再带上域名和时间线去 Cloudflare 提交工单排查。&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;整个转移过程中，不要在原注册商处点击任何「取消转移」「拒绝转出」类的按钮，也不要重新打开注册锁&amp;lt;/span&amp;gt;，手滑一下，流程就会被打回原点，只能重新发起、白等一轮。
:::&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Cloudflare Registrar 按注册局批发价卖域名和续费，不加价、无捆绑、WHOIS 隐私默认免费，省的是每年重复发生的钱。&lt;/li&gt;
&lt;li&gt;转入前提四件套：域名已在 Cloudflare 激活、后缀在支持列表内、不在 60 天限制期、状态正常。&lt;/li&gt;
&lt;li&gt;转入前在原注册商处做完四件事：关注册锁、取授权码、确认联系邮箱、检查到期日；临近到期先续费再转。&lt;/li&gt;
&lt;li&gt;账目不吃亏：转入即续一年，到期日顺延，原有年限完整保留。&lt;/li&gt;
&lt;li&gt;转入后保持自动续费和注册锁开启，确认 WHOIS 隐私生效，注册与解析同台管理。&lt;/li&gt;
&lt;li&gt;转移被拒按「锁、码、60 天、邮箱、状态」的顺序排查；解析异常与转移无关，回到 DNS 的思路查。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;域名这种东西，平时毫无存在感，过期那天存在感拉满。把它搬到一个不靠它赚差价的注册商名下、按批发价自动续着，是给自己所有站点做的一次性的省钱加固。&lt;/p&gt;
</content:encoded></item><item><title>规则体系实战：重定向、改写与响应头</title><link>https://www.anexns.cloudns.org/posts/cloudflare-rules-transform/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-rules-transform/</guid><description>不改源站代码，在边缘把请求收拾干净：Redirect Rules 做域名规范化与链接迁移、Transform Rules 改写 URL 与请求头、Origin Rules 改回源地址与端口，以及这套规则的执行顺序。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;源站程序跑得好好的，总有一些事情不值得为它改代码、重新发版：www 和裸域名要统一成一个、老链接换了新路径、某个接口临时要指到另一台机器、响应里少了几个安全头。这些事过去要么改 Nginx 配置，要么改应用代码，要么干脆凑合着不管。现在它们有一个更合适的位置——Cloudflare 的边缘规则：请求还没到达源站，就先在离用户最近的边缘节点上被整理一遍。&lt;/p&gt;
&lt;p&gt;这一篇讲 Cloudflare 现行的新规则体系里负责「改请求」的四类规则：Redirect Rules 管跳转，Transform Rules 管 URL 改写和请求/响应头修改，Origin Rules 管回源时改地址、改端口、改 Host 头。Cache Rules 在本系列的缓存篇已经讲过，这里只在执行顺序里带一句。读完这一篇，你应该能独立完成三件最常见的事：把 www 规范化到裸域名、把整站老链接平滑迁移到新域名、给全站响应补上安全头——全程不动源站一行代码。&lt;/p&gt;
&lt;p&gt;先把核心结论放在前面：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;重定向会改浏览器地址栏，重写不会——这是 Redirect 和 Rewrite 最根本的区别&amp;lt;/span&amp;gt;，后面所有的选型都从这一句出发。要让用户和搜索引擎都知道「地址变了」，用重定向；只是内部把请求递到另一个路径、对外地址保持原样，用重写。&lt;/p&gt;
&lt;h2&gt;一、先看全景：新规则体系与执行顺序&lt;/h2&gt;
&lt;p&gt;Cloudflare 现在的规则体系按职责拆成了好几类，每一类只管一段「请求生命周期」。一个请求从用户浏览器出发，大致要依次经过这些阶段：先判断要不要直接跳转（Redirect），然后改写 URL（Transform 的 URL Rewrite），再修改请求头（Transform 的 HTTP Request Header Modification），接着决定到底回哪个源、走哪个端口（Origin Rules），再决定缓存策略（Cache Rules），请求才真正发往源站；源站返回之后，响应在回用户的路上还会经过响应头修改（Transform 的 HTTP Response Header Modification）和压缩等阶段。安全类的 WAF 自定义规则、速率限制等阶段也插在这条链里，本篇不展开，只聚焦「改请求」的这几段。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;执行阶段（先 → 后）&lt;/th&gt;
&lt;th&gt;对应规则&lt;/th&gt;
&lt;th&gt;在这一段做什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1. 重定向&lt;/td&gt;
&lt;td&gt;Redirect Rules&lt;/td&gt;
&lt;td&gt;命中就直接返回 3xx，请求不再往下走&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2. URL 改写&lt;/td&gt;
&lt;td&gt;Transform Rules → URL Rewrite&lt;/td&gt;
&lt;td&gt;在内部把路径/查询串换成另一个样子&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3. 请求头修改&lt;/td&gt;
&lt;td&gt;Transform Rules → Request Header Modification&lt;/td&gt;
&lt;td&gt;增、改、删发往源站的请求头&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4. 回源改写&lt;/td&gt;
&lt;td&gt;Origin Rules&lt;/td&gt;
&lt;td&gt;改 Host 头、改解析目标、改回源端口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5. 缓存设置&lt;/td&gt;
&lt;td&gt;Cache Rules&lt;/td&gt;
&lt;td&gt;决定缓存资格与 TTL（缓存篇已讲）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;6. 请求到达源站&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;源站看到的是被前面几步整理过的请求&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7. 响应头修改&lt;/td&gt;
&lt;td&gt;Transform Rules → Response Header Modification&lt;/td&gt;
&lt;td&gt;在响应回用户前增、改、删响应头&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这张顺序表有两个直接的实战推论。第一，重定向排在最前面：一旦某条 Redirect Rule 命中并返回了 301，后面的改写、回源规则对这个请求全部失效，浏览器会拿着新地址重新发一个请求、从头再走一遍。所以「既想跳转又想改写」的需求，要拆成两次请求来理解。第二，同一类规则内部是按列表从上到下依次执行的，顺序靠前的先处理；把更具体的规则放在更宽泛的规则前面，是避免互相截胡的基本功。具体的阶段全集与细节以 Cloudflare 官方文档和控制台为准，这里给出的是与本篇相关的简化链路，足够指导日常配置。&lt;/p&gt;
&lt;p&gt;:::warning
规则是在边缘「拦截并加工」请求，配错一条宽泛规则，影响的不是某个页面，而是全站。新建规则时先用尽量窄的匹配条件（具体主机名、具体路径前缀）小范围验证，确认无误再放宽范围；改完立刻用无痕窗口和 curl 各测一次，不要等用户报障。
:::&lt;/p&gt;
&lt;h2&gt;二、和旧 Page Rules 的关系：新配置一律用新规则&lt;/h2&gt;
&lt;p&gt;很多老教程还在教 Page Rules：一条规则里把缓存级别、重定向、SSL 模式等设置打包在一起，按 URL 匹配。需要明确的是，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Page Rules 已经进入淘汰通道，Cloudflare 正在推动用户迁移到新规则体系&amp;lt;/span&amp;gt;，它的功能已经被拆解到 Redirect Rules、Cache Rules、Transform Rules、Configuration Rules 等新规则里一一对应。新站点、新需求不要再往 Page Rules 里加配置，否则将来迁移时还要再拆一遍。&lt;/p&gt;
&lt;p&gt;如果你的站点已经有在跑的 Page Rules，迁移时注意三点。第一，先盘点：把每条 Page Rules 的匹配 URL 和动作列出来，逐项对应到新规则（转发 URL 对应 Redirect Rules、缓存级别对应 Cache Rules、Always Use HTTPS 这类对应 Configuration Rules 或重定向规则）。第二，先建新规则、验证生效，再删旧规则，顺序反过来会出现配置真空期。第三，Page Rules 是「一条命中就不再匹配后续同类设置」的老逻辑，新规则按阶段分层执行，迁移后同一请求可能同时被多个阶段的规则处理，效果需要重新实测，不能想当然地认为和原来完全一致。迁移完成后把 Page Rules 清空，避免新旧两套并存时互相干扰、排查问题时无从下手。&lt;/p&gt;
&lt;h2&gt;三、Redirect Rules 实战：三个最常见的跳转&lt;/h2&gt;
&lt;p&gt;Redirect Rules 的工作方式很直白：当请求的字段（主机名、路径、查询串、来源国家、User-Agent 等）满足匹配条件时，边缘直接返回一个 3xx 响应，告诉浏览器去新地址重新请求。创建入口在控制台对应站点的「规则 → 重定向规则」里，每条规则由三部分组成：名称、匹配条件（通配符或自定义表达式）、跳转参数（目标 URL、状态码、是否保留查询字符串）。免费与付费套餐可建的条数不同，具体以控制台为准。&lt;/p&gt;
&lt;p&gt;选状态码是第一课。跳转分临时和永久，又分保不保持原请求方法：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;状态码&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;方法与请求体&lt;/th&gt;
&lt;th&gt;典型用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;301&lt;/td&gt;
&lt;td&gt;永久移动&lt;/td&gt;
&lt;td&gt;可能被改成 GET&lt;/td&gt;
&lt;td&gt;域名迁移、www 规范化、链接永久改版&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;302&lt;/td&gt;
&lt;td&gt;临时移动&lt;/td&gt;
&lt;td&gt;可能被改成 GET&lt;/td&gt;
&lt;td&gt;临时活动页、A/B 分流、维护跳转&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;307&lt;/td&gt;
&lt;td&gt;临时重定向&lt;/td&gt;
&lt;td&gt;严格保持原方法与请求体&lt;/td&gt;
&lt;td&gt;接口临时迁移、POST 场景临时跳转&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;308&lt;/td&gt;
&lt;td&gt;永久重定向&lt;/td&gt;
&lt;td&gt;严格保持原方法与请求体&lt;/td&gt;
&lt;td&gt;接口永久迁移且方法不能变&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;SEO 上的一句结论：永久迁移要用 301（或 308），搜索引擎会把旧地址的索引与权重信号转移到新地址；&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;整站迁移如果误用 302，搜索引擎会继续保留旧域名的索引，新域名迟迟排不上去&amp;lt;/span&amp;gt;。反过来，只是临时把流量挪走几天，就老老实实用 302/307，恢复时删掉规则即可，不会给搜索引擎留下「已永久搬家」的错误信号。&lt;/p&gt;
&lt;h3&gt;例一：www 跳裸域名，保留路径与查询串&lt;/h3&gt;
&lt;p&gt;需求：&lt;code&gt;www.example.com/abc?x=1&lt;/code&gt; 统一跳到 &lt;code&gt;example.com/abc?x=1&lt;/code&gt;，让站点只有一个对外域名。用通配符（Wildcard）写最省事：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;规则名称：www 到裸域名
匹配方式：通配符
请求 URL：www.example.com/*
目标 URL：https://example.com/$1
状态代码：301
保留查询字符串：勾选
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里的 &lt;code&gt;*&lt;/code&gt; 是捕获符，它把 &lt;code&gt;www.example.com/&lt;/code&gt; 之后的部分（本例是 &lt;code&gt;abc&lt;/code&gt;）捕获下来，在目标 URL 里用 &lt;code&gt;$1&lt;/code&gt; 引用回去；「保留查询字符串」勾上后，&lt;code&gt;?x=1&lt;/code&gt; 会被自动拼到目标地址后面。注意通配符匹配的是去掉协议后的部分，书写格式以控制台给出的示例为准，第一次建完务必实测一个带多级路径和参数的地址。&lt;/p&gt;
&lt;h3&gt;例二：整站 HTTP 跳 HTTPS（规则版做法）&lt;/h3&gt;
&lt;p&gt;把 HTTP 强制跳 HTTPS，更常见的做法是打开站点 SSL/TLS 设置里的「始终使用 HTTPS」开关；但如果你只想对部分路径、或想留一条可随时回滚的规则，用 Redirect Rules 也能做。匹配条件用表达式判断协议：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;规则名称：HTTP 强制 HTTPS
匹配方式：自定义表达式
表达式：(http.request.uri.scheme eq &quot;http&quot;)
目标 URL：动态，concat(&quot;https://&quot;, http.host, http.request.uri.path)
状态代码：301
保留查询字符串：勾选
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这个表达式里 &lt;code&gt;http.request.uri.scheme&lt;/code&gt; 是请求协议，&lt;code&gt;http.host&lt;/code&gt; 是主机名，&lt;code&gt;concat()&lt;/code&gt; 把几段字符串拼成完整的新地址。需要提醒：跳转目标里的查询串由「保留查询字符串」选项负责拼接，表达式本身只需管到路径为止。&lt;/p&gt;
&lt;h3&gt;例三：整站换域名，旧域名对应路径 301 到新域名&lt;/h3&gt;
&lt;p&gt;站点从 &lt;code&gt;old.com&lt;/code&gt; 迁到 &lt;code&gt;new.com&lt;/code&gt;，要求每条老链接都落到新域名的同路径上，而不是全跳到首页（全跳首页会让搜索引擎把深层页面当作失效处理）。通配符写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;规则名称：旧域名迁移到新域名
匹配方式：通配符
请求 URL：old.com/*
目标 URL：https://new.com/$1
状态代码：301
保留查询字符串：勾选
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;子域名如果也要迁，再补一条 &lt;code&gt;*.old.com/*&lt;/code&gt; 的规则，或用表达式按主机名后缀统一处理。迁移类跳转的配套动作还有两个：一是新域名站点的解析与证书先就绪，再开跳转规则，顺序反了用户点开老链接会直接报错；二是跳转规则至少保留几个月，老链接、外部收藏和搜索引擎索引更新都需要时间，别迁完一周就删。&lt;/p&gt;
&lt;p&gt;:::warning
重定向循环最常见的成因就是跳转打架：Cloudflare 侧把 HTTP 跳到 HTTPS，源站又因为回源协议或配置问题把 HTTPS 跳回 HTTP，浏览器来回几十次后报 ERR_TOO_MANY_REDIRECTS。典型组合是 SSL 模式设为「灵活」时源站误以为请求来自 HTTP 而强制跳 HTTPS。遇到循环先把两边各自的跳转逻辑列出来对一遍，只保留一处负责跳转。
:::&lt;/p&gt;
&lt;h2&gt;四、匹配方式：通配符与表达式怎么选&lt;/h2&gt;
&lt;p&gt;Redirect Rules 和 Transform Rules 都支持两种匹配与取值方式，理解它们的分工能少走很多弯路。&lt;/p&gt;
&lt;p&gt;通配符（Wildcard）是简化模式：一串模式里用 &lt;code&gt;*&lt;/code&gt; 表示「任意一段」，可以出现多次，按出现顺序编号，在目标里用 &lt;code&gt;$1&lt;/code&gt;、&lt;code&gt;$2&lt;/code&gt; 引用。它适合结构规整的场景——域名规范化、目录整体迁移、加前缀去前缀这类「形状不变、只换壳子」的需求，写起来短、可读性好，出错率低。&lt;/p&gt;
&lt;p&gt;表达式（Expression）是完整模式：匹配条件用字段加运算符写，比如 &lt;code&gt;(http.host eq &quot;www.example.com&quot;)&lt;/code&gt;、&lt;code&gt;(starts_with(http.request.uri.path, &quot;/old/&quot;))&lt;/code&gt;；目标值也可以是动态表达式，用函数现场拼。常用函数先认识这几个：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;函数&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;例子&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;concat(a, b, ...)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;拼接字符串&lt;/td&gt;
&lt;td&gt;&lt;code&gt;concat(&quot;https://&quot;, http.host, http.request.uri.path)&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;lower(x)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;转小写&lt;/td&gt;
&lt;td&gt;&lt;code&gt;lower(http.request.uri.path)&lt;/code&gt; 统一路径大小写&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;upper(x)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;转大写&lt;/td&gt;
&lt;td&gt;处理需要大写的参数值&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;substring(x, start, len)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;截取子串&lt;/td&gt;
&lt;td&gt;截掉路径固定前缀&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;regex_replace(...)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;正则替换&lt;/td&gt;
&lt;td&gt;复杂路径变换（可用性以控制台为准）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一条实用的表达式版跳转：把 &lt;code&gt;/old-blog/&lt;/code&gt; 前缀下的文章迁到 &lt;code&gt;/posts/&lt;/code&gt; 下，其余路径不动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;匹配表达式：(starts_with(http.request.uri.path, &quot;/old-blog/&quot;))
目标 URL（动态）：concat(&quot;https://&quot;, http.host, &quot;/posts/&quot;, substring(http.request.uri.path, 10))
状态代码：301
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;substring(http.request.uri.path, 10)&lt;/code&gt; 里的 10 是 &lt;code&gt;/old-blog/&lt;/code&gt; 这 10 个字符的长度，从第 10 位开始截取，正好把前缀剥掉、保留后面的文章路径——这类「差一位就全错」的计算是重写与跳转排障的头号来源，写完先拿三个真实地址手算一遍再保存。选型原则一句话：能用通配符表达的就别上表达式；表达式留给确实需要按字段判断、按函数拼装的场景。匹配字段、运算符与函数的全集以官方文档为准，控制台的表达式编辑器带字段提示，边写边用它的预览校验。&lt;/p&gt;
&lt;h2&gt;五、Transform Rules 之一：URL Rewrite，地址栏不变的内部改写&lt;/h2&gt;
&lt;p&gt;URL Rewrite 和 Redirect 只差一个字，行为却完全相反：重定向是把浏览器打发去新地址，地址栏会变、会多一次请求；重写是边缘在内部把请求换个路径递给源站，浏览器对此一无所知，地址栏保持原样、没有额外往返。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;重写解决的是「对外地址要好看/要稳定，对内实现路径是另一套」的问题&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;典型场景一：内容目录换了组织方式，但不想让外部链接和用户感知到。站点文章实际存放在 &lt;code&gt;/articles/&lt;/code&gt; 下，对外想暴露成 &lt;code&gt;/blog/&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;规则名称：blog 对外、articles 对内
匹配：通配符，请求 URL 为 example.com/blog/*
重写到：/articles/$1（静态改写路径）
查询字符串：保持不变
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这样用户访问 &lt;code&gt;example.com/blog/docker-guide&lt;/code&gt;，源站实际收到的是 &lt;code&gt;/articles/docker-guide&lt;/code&gt;，源站的目录、程序都不用动。场景二：多语言或多版本目录收敛，比如把 &lt;code&gt;/v1/docs/*&lt;/code&gt; 内部转到当前文档目录。场景三：给某些路径统一补上或去掉尾缀，比如把无扩展名的请求重写到实际的 &lt;code&gt;.html&lt;/code&gt; 文件（静态站托管在源站时常用）。&lt;/p&gt;
&lt;p&gt;重写可以改路径，也可以改查询字符串，两者可分别设为「保持不变 / 静态替换 / 动态表达式」。有两条边界要记住。第一，重写只换「递给源站的请求长什么样」，源站程序如果按 Host 头或绝对 URL 生成页面里的链接，生成出来的仍可能是内部地址，需要源站配合或改用重定向，这不是规则能兜底的。第二，重写目标写错一位，源站就是实打实地找不到文件、返回 404，而且因为地址栏没变，用户和你的第一反应都不会怀疑到规则上——排障时记得把重写规则列进嫌疑名单（见第八节）。&lt;/p&gt;
&lt;h2&gt;六、Transform Rules 之二：给请求头和响应头做增删改&lt;/h2&gt;
&lt;p&gt;Transform Rules 里还有两个子类型：HTTP 请求头修改（Request Header Modification）和 HTTP 响应头修改（Response Header Modification）。每个头可以做三种操作：设置（Set，不存在就加、存在就覆盖）、设置动态值（用表达式现场算）、移除（Remove）。请求头修改作用于「发往源站」的方向，响应头修改作用于「返回用户」的方向，两个方向别搞混。&lt;/p&gt;
&lt;p&gt;请求头方向的典型用法，是给源站递一个可信的标记。Cloudflare 本身已经会自动给回源请求带上 &lt;code&gt;CF-Connecting-IP&lt;/code&gt;（真实访客 IP）、&lt;code&gt;CF-Ray&lt;/code&gt; 等头，源站日志和程序应该优先读这些现成的。但有些场景需要自定义：比如同一源站后面挂了两个站点，想让源站按头区分来源，可以加一条规则给某域名来的请求统一设置 &lt;code&gt;X-Site-Mark: main&lt;/code&gt;，源站据此打日志或走不同逻辑。再比如把访客所在国家以自定义头递给源站做统计，用动态值把 &lt;code&gt;ip.src.country&lt;/code&gt; 写进头里：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;规则：请求头修改
匹配：(http.host eq &quot;example.com&quot;)
操作：设置动态请求头
头名称：X-Visitor-Country
值（表达式）：ip.src.country
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;响应头方向最常见的活是补安全头。很多老应用没给响应带安全相关的头，在边缘统一补上比逐个改应用现实得多：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;规则：响应头修改
匹配：(http.host eq &quot;example.com&quot;)
操作 1：设置响应头 X-Content-Type-Options = nosniff
操作 2：设置响应头 Referrer-Policy = strict-origin-when-cross-origin
操作 3：移除响应头 X-Powered-By
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;X-Content-Type-Options: nosniff&lt;/code&gt; 阻止浏览器对响应内容做 MIME 猜测，&lt;code&gt;Referrer-Policy&lt;/code&gt; 控制跳转时带多少来源信息，&lt;code&gt;X-Powered-By&lt;/code&gt; 这类头纯属把技术栈写在脸上、能删就删。同理，如果源站自己已经在发某个头，边缘再 Set 一次就是覆盖，排查「头怎么有两份/怎么对不上」时要把源站和边缘两边一起看。&lt;/p&gt;
&lt;p&gt;:::warning
响应头里有一个要格外小心的：Strict-Transport-Security（HSTS）。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;HSTS 一旦被浏览器记下且 max-age 设得很长，在有效期内浏览器会拒绝一切 HTTP 访问，配错了短时间无法回滚&amp;lt;/span&amp;gt;。确认全站 HTTPS 长期稳定、子域名都覆盖到之前，不要在边缘随手给全站加上大 max-age 的 HSTS，更不要轻易带 preload。
:::&lt;/p&gt;
&lt;h2&gt;七、Origin Rules：同一域名，按路径回不同的源&lt;/h2&gt;
&lt;p&gt;Origin Rules 管的是链路的后半段：请求已经通过前面的阶段，接下来到底发到哪台机器、哪个端口、以什么 Host 头去敲门。默认情况下，回源目标由 DNS 记录决定、端口由请求协议决定、Host 头就是用户访问的主机名。Origin Rules 可以按匹配条件覆盖三样东西：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;可覆盖项&lt;/th&gt;
&lt;th&gt;改的是什么&lt;/th&gt;
&lt;th&gt;典型场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Host 头（Host Header）&lt;/td&gt;
&lt;td&gt;源站收到的 Host 值&lt;/td&gt;
&lt;td&gt;一台源站按虚拟主机分流多个站点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;DNS 记录（DNS Record / Resolve Override）&lt;/td&gt;
&lt;td&gt;把回源解析指到另一个主机名&lt;/td&gt;
&lt;td&gt;同域名部分路径回另一台源站&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;目标端口（Destination Port）&lt;/td&gt;
&lt;td&gt;回源连接的端口&lt;/td&gt;
&lt;td&gt;源站服务跑在 8080 等非标准端口&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一个把三样用得上的场景：主站 &lt;code&gt;example.com&lt;/code&gt; 的普通页面回默认源站，但 &lt;code&gt;/api/&lt;/code&gt; 路径的服务其实跑在另一台机器的 8443 端口上，且那台机器按 Host 头区分租户。可以建一条 Origin Rule：匹配 &lt;code&gt;(starts_with(http.request.uri.path, &quot;/api/&quot;))&lt;/code&gt;，把 DNS 记录覆盖为后端机的主机名、目标端口覆盖为 8443、Host 头覆盖为后端期望的值。用户侧完全无感，域名和证书都不用变，拆分服务只动一条规则。&lt;/p&gt;
&lt;p&gt;这条能力很强，边界也要清楚。第一，Origin Rules 只是「改投递地址」，被指过去的源站必须真的能处理这个 Host 和路径，否则就是把 404/502 换了个地方产生。第二，DNS 覆盖的目标必须是能被正确解析的主机名，填错或目标宕机时，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;全站会直接报 5xx 且报错页面上看不出是规则的锅&amp;lt;/span&amp;gt;，改这类规则务必保留快速回滚的路径（记住原值、改完立刻全链路实测）。第三，改端口只影响 Cloudflare 到源站这一段，用户到 Cloudflare 的端口不变；源站防火墙要放行 Cloudflare 的回源连接打这个新端口，别只改规则忘了放行。&lt;/p&gt;
&lt;h2&gt;八、排障：规则类问题三板斧&lt;/h2&gt;
&lt;p&gt;规则配错的表现通常就三种：跳来跳去、该生效的没生效、改完之后 404。下面按症状给排查顺序。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;症状一：重定向循环（ERR_TOO_MANY_REDIRECTS）。&lt;/strong&gt; 先用 &lt;code&gt;curl -sI https://example.com/路径&lt;/code&gt; 看响应头里的 &lt;code&gt;location&lt;/code&gt; 指向哪，再对 location 的地址继续 &lt;code&gt;curl -sI&lt;/code&gt;，手动跟两三跳，循环的形状立刻现形：是 HTTP 与 HTTPS 之间来回（两边都在做协议跳转，见第三节的 warning，多半还牵涉 SSL 模式「灵活」与源站强制 HTTPS 打架），还是 www 与裸域之间来回（两条规范化规则方向相反，或源站里还留着一条反向跳转）。原则是全网只保留一处负责某类跳转：边缘规则建了，源站里的同类跳转就删掉或关掉。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;症状二：规则保存了却不生效。&lt;/strong&gt; 按这个顺序查：①匹配没命中——路径大小写敏感、主机名对不上、漏了尾斜杠，用表达式的先把条件简化成只匹配主机名验证规则本身能触发，再逐步加回条件；②被同阶段更靠前的规则截胡——同类规则按顺序执行，宽泛规则在前会先处理，把本条拖到更靠前或把前一条的匹配范围收窄；③阶段顺序理解错——期望 URL Rewrite 在 Redirect 之前生效是不可能的，跳转一旦返回，后续阶段对该请求不再执行，需要改方案（比如先在第一次请求里用重写、跳转规则改匹配重写前的地址）；④忘了规则只对「经过 Cloudflare 代理（橙云）」的流量生效，灰云直连源站的请求规则一概管不着，拿灰云子域名测试会得出「规则没用」的错误结论。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;症状三：重写/回源改完之后源站 404 或 502。&lt;/strong&gt; 404 先查路径拼接：把规则的匹配段和目标段拿真实地址逐字手算，重点看前缀长度差一位、重复拼接（源站目录本身带前缀又被规则加了一遍）、丢了尾斜杠导致目录索引不触发。502 先查回源目标：Origin Rules 的 DNS 覆盖与端口是否指向真实在跑的服务，源站防火墙有没有放行新端口，Host 头覆盖后源站虚拟主机认不认这个 Host。验证方法：绕开规则，用源站 IP 加 &lt;code&gt;--resolve&lt;/code&gt; 或 hosts 方式直连源站按「规则改完后的样子」手工发一次请求，能复现就说明问题在源站侧配置，接不通则是规则侧投递参数写错：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 按规则改完后的 Host 与路径，直连源站验证
curl -sI --resolve api.example.com:8443:源站IP https://api.example.com:8443/api/health
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;另外养成一个习惯：任何规则改动后，用 &lt;code&gt;curl -sI&lt;/code&gt; 把关键响应头（&lt;code&gt;location&lt;/code&gt;、&lt;code&gt;cf-ray&lt;/code&gt;、自己加的标记头）留一份记录，出问题时和正常时对比，比对着控制台猜要快得多。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇的规则体系可以收成几句话。请求进边缘后按阶段走：Redirect 先决定要不要把人送走，URL Rewrite 在内部换路径，请求头修改给源站递标记，Origin Rules 决定最终投递到哪台机器哪个端口，响应回来时再过一遍响应头修改。重定向与重写的分界线是地址栏变不变：对外宣布搬家用 301 重定向，只是内部换实现用重写。Page Rules 已在淘汰通道，新配置一律建在新规则上，老配置按「先建新、验证、再删旧」的顺序迁。匹配能用通配符就不用表达式，表达式里的截取长度这类计算先手算再保存。最后一条纪律：规则的影响面是全站，窄范围验证、改完立刻实测、Origin 与跳转类规则留好回滚路径——做到这三点，边缘规则就是省事的工具，而不是半夜把人叫醒的事故源。&lt;/p&gt;
</content:encoded></item><item><title>Cloudflare SSL/TLS 加密模式详解</title><link>https://www.anexns.cloudns.org/posts/cloudflare-ssl-tls/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-ssl-tls/</guid><description>关闭、灵活、完全、完全（严格）四种加密模式到底差在哪：灵活模式为什么会造成重定向死循环、源站证书的两种正规来源、HSTS 为什么不能随手开，一篇把全站 HTTPS 配对。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;把域名接入 Cloudflare 之后，很多人第一件事就是去开 HTTPS，结果在「SSL/TLS → 概述」页面里看到四个选项：关闭、灵活、完全、完全（严格），随手选一个，网站要么打不开，要么陷入无限重定向，要么浏览器地址栏挂着小锁、回源链路却还在裸奔。更麻烦的是，这四个模式的名字起得都很像「加密等级」，实际上它们只管整条链路中的一段——选错段、配错顺序，问题全出在这里。&lt;/p&gt;
&lt;p&gt;这篇就把这件事一次讲透：先分清访客到源站之间的两段链路各自归谁管，再逐个拆解四种加密模式的真实含义和安全性，然后讲清边缘证书与源站证书这两套完全不同的证书体系、源站证书的两条正规申请路线，以及 HSTS 这个「开了就很难回头」的开关应该怎么开。读完这一篇，你的全站 HTTPS 就能一次配对，不用再靠试错。&lt;/p&gt;
&lt;h2&gt;先分清：一条访问链路有两段加密&lt;/h2&gt;
&lt;p&gt;用户在浏览器里输入你的域名，请求并不是直达你的服务器，而是先到 Cloudflare 的边缘节点，再由 Cloudflare 回源到你的服务器。也就是说，一次 HTTPS 访问实际上包含两段独立的 TLS 连接：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;链路段&lt;/th&gt;
&lt;th&gt;两端&lt;/th&gt;
&lt;th&gt;证书由谁提供&lt;/th&gt;
&lt;th&gt;归谁配置&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;第一段&lt;/td&gt;
&lt;td&gt;访客浏览器 ↔ Cloudflare 边缘节点&lt;/td&gt;
&lt;td&gt;Cloudflare 自动签发的边缘证书&lt;/td&gt;
&lt;td&gt;Cloudflare 全自动管理，不用你操心&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;第二段&lt;/td&gt;
&lt;td&gt;Cloudflare 边缘节点 ↔ 你的源站服务器&lt;/td&gt;
&lt;td&gt;你自己在源站上部署的源站证书&lt;/td&gt;
&lt;td&gt;由「加密模式」决定怎么校验、要不要加密&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;第一段你几乎什么都不用做：域名接入 Cloudflare 并开启橙云代理之后，Cloudflare 会自动为你的域名签发边缘证书（Universal SSL），访客看到的地址栏小锁就是这一段的成果。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;而「加密模式」从头到尾只管第二段——Cloudflare 到源站这一段走不走加密、校不校验你的源站证书。&amp;lt;/span&amp;gt;很多人以为把模式调到最高就能让整站变安全，其实第一段的安全与它无关，第二段才是它真正的管辖范围。先把这个认知立住，后面四种模式就非常好理解了。&lt;/p&gt;
&lt;h2&gt;四种加密模式对比：差的不只是「加密强度」&lt;/h2&gt;
&lt;p&gt;在 Cloudflare 控制台「SSL/TLS → 概述」里可以切换加密模式，四种模式对第二段链路的处理方式完全不同：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;模式&lt;/th&gt;
&lt;th&gt;回源是否走 HTTPS&lt;/th&gt;
&lt;th&gt;是否校验证书&lt;/th&gt;
&lt;th&gt;第二段实际安全性&lt;/th&gt;
&lt;th&gt;适用场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;关闭（Off）&lt;/td&gt;
&lt;td&gt;否，全程 HTTP&lt;/td&gt;
&lt;td&gt;不涉及&lt;/td&gt;
&lt;td&gt;无加密，且访客段也会被降为 HTTP&lt;/td&gt;
&lt;td&gt;只适合纯测试、源站完全没有敏感内容的临时站点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;灵活（Flexible）&lt;/td&gt;
&lt;td&gt;否，Cloudflare 用 HTTP 回源&lt;/td&gt;
&lt;td&gt;不涉及&lt;/td&gt;
&lt;td&gt;只有访客段有加密，回源段明文&lt;/td&gt;
&lt;td&gt;源站实在装不了证书时的过渡方案&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;完全（Full）&lt;/td&gt;
&lt;td&gt;是，用 HTTPS 回源&lt;/td&gt;
&lt;td&gt;否，证书过期、自签、域名对不上都照单全收&lt;/td&gt;
&lt;td&gt;有加密，但不防中间人冒充源站&lt;/td&gt;
&lt;td&gt;源站证书不规范时的折中，临时可用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;完全（严格）（Full (Strict)）&lt;/td&gt;
&lt;td&gt;是，用 HTTPS 回源&lt;/td&gt;
&lt;td&gt;是，必须由受信任 CA 签发且域名匹配、未过期&lt;/td&gt;
&lt;td&gt;有加密且校验身份，两段都安全&lt;/td&gt;
&lt;td&gt;正式生产环境的目标状态&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个关键点逐个说清：&lt;/p&gt;
&lt;p&gt;**关闭模式是最危险的一档。**它不只是第二段不加密：只要加密模式是关闭，访客用 HTTPS 访问你的域名会被直接重定向到 HTTP，等于&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;全站明文传输，登录密码、Cookie、后台会话全部裸奔&amp;lt;/span&amp;gt;。这一档除了调试，不应该出现在任何正经站点上。&lt;/p&gt;
&lt;p&gt;**灵活模式是「看起来有锁」的障眼法。**访客到 Cloudflare 这段是 HTTPS，地址栏有锁，但 Cloudflare 回源时用的是明文 HTTP。如果你的源站和 Cloudflare 之间隔着公共网络（绝大多数情况都是），这一段的数据就是明文。灵活模式存在的唯一理由，是源站环境实在没法部署证书（比如某些老旧虚拟主机），拿来先让访客侧有把锁。它有一个非常著名的坑，下一节专门讲。&lt;/p&gt;
&lt;p&gt;**完全模式有加密、没身份。**Cloudflare 会用 HTTPS 回源，但不校验源站证书的有效性：自签证书、过期证书、域名对不上的证书，它全都接受。这意味着加密是有了，但如果有人能劫持回源链路并冒充你的源站，Cloudflare 分辨不出来。它适合源站暂时只能用自签证书的过渡期，不适合长期停留。&lt;/p&gt;
&lt;p&gt;**完全（严格）才是完整形态。**回源走 HTTPS，且源站证书必须满足三个条件：由受信任的 CA 签发（或 Cloudflare Origin CA，见下文）、未过期、证书上的域名与访问域名匹配。任何一条不满足，Cloudflare 直接拒绝回源并返回 525/526 错误（排障节细说）。&lt;/p&gt;
&lt;p&gt;本站的立场很明确：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;生产环境直接上完全（严格），不要在灵活和完全上长期停留。&amp;lt;/span&amp;gt;现在源站证书有完全免费的正规来源（下一节讲），为了省一张证书的功夫去承担明文回源或不校验证书的风险，不划算。切换的正确顺序也很重要：先在源站把证书装好并确认源站自己能用 HTTPS 正常访问，再去 Cloudflare 把模式切到完全（严格），顺序反了网站会当场打不开。&lt;/p&gt;
&lt;h2&gt;灵活模式的大坑：重定向死循环&lt;/h2&gt;
&lt;p&gt;灵活模式最经典的翻车现场是这样的：网站切到灵活模式后，浏览器打开域名直接报 &lt;code&gt;ERR_TOO_MANY_REDIRECTS&lt;/code&gt;，无限重定向，页面根本进不去。&lt;/p&gt;
&lt;p&gt;原理一点都不复杂，把两边的行为叠起来看就明白了：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;灵活模式下，Cloudflare 用 &lt;strong&gt;HTTP&lt;/strong&gt; 回源请求你的源站。&lt;/li&gt;
&lt;li&gt;你的源站上配了「HTTP 强制跳转 HTTPS」的规则（Nginx 的 301、宝塔面板的强制 HTTPS、WordPress 的 HTTPS 插件都爱干这件事），于是源站回了一个跳转：请用 HTTPS 重新访问。&lt;/li&gt;
&lt;li&gt;访客的浏览器收到跳转，用 HTTPS 再次请求——请求先到 Cloudflare，Cloudflare 又用 HTTP 回源，源站又回一个跳转……&lt;/li&gt;
&lt;li&gt;循环往复，直到浏览器判定重定向次数过多，报错收场。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;问题的根源是：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;源站看到的请求永远是 HTTP，它永远在要求跳转；而 Cloudflare 永远用 HTTP 回源，这个跳转永远得不到满足。&amp;lt;/span&amp;gt;源站并不知道访客其实已经在用 HTTPS 了，它只能看到 Cloudflare 发过来的那一段连接。&lt;/p&gt;
&lt;p&gt;解法按推荐程度排：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;**正解：弃用灵活模式。**给源站装一张正规证书（下一节的两条路线都是免费的），加密模式切到完全（严格），源站的强制跳转规则可以保留，问题从根上消失。&lt;/li&gt;
&lt;li&gt;**临时解法：关掉源站的强制 HTTPS 跳转。**让源站老老实实响应 HTTP 回源，灵活模式就能跑通。但这样回源段继续明文，只适合救急。&lt;/li&gt;
&lt;li&gt;**不推荐：在源站按请求头判断。**Cloudflare 回源时会带上 &lt;code&gt;X-Forwarded-Proto&lt;/code&gt; 请求头标识访客侧的协议，可以在源站配置「只有当这个头是 http 时才跳转」。能work，但配置复杂且容易在换环境时失效，不如直接上证书。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;顺带一提，WordPress 等程序还有一类相似症状：站点 URL 里写死了 https，但程序根据连接判断协议，灵活模式下容易出现后台进不去、资源加载走 http 的混合问题。根源都是同一个：灵活模式让源站对协议的感知失真。这也是不建议在灵活模式上长期停留的原因之一。&lt;/p&gt;
&lt;h2&gt;边缘证书：Cloudflare 自动管的那一段&lt;/h2&gt;
&lt;p&gt;回到第一段链路。访客侧的证书叫边缘证书，默认方案是 Universal SSL（通用 SSL）：域名接入 Cloudflare 后自动申请、自动部署、自动续期，全程不用你操作，签发机构一般是 Let&apos;s Encrypt 或 Google Trust Services（以控制台显示为准）。&lt;/p&gt;
&lt;p&gt;它有两个必须知道的细节：&lt;/p&gt;
&lt;p&gt;**第一，覆盖范围是根域加一级子域。**Universal SSL 的证书覆盖 &lt;code&gt;example.com&lt;/code&gt; 和 &lt;code&gt;*.example.com&lt;/code&gt;，也就是说 &lt;code&gt;www.example.com&lt;/code&gt;、&lt;code&gt;blog.example.com&lt;/code&gt; 这类一级子域都在保护范围内，通配符只管一层。&lt;/p&gt;
&lt;p&gt;**第二，多级子域不在覆盖范围内，这是个高频坑。**像 &lt;code&gt;api.dev.example.com&lt;/code&gt; 这样的二级子域（点号有三段），通配符 &lt;code&gt;*.example.com&lt;/code&gt; 管不到它，访客访问时会报证书名称不匹配的错误。解法有三种：把子域拍扁成一级（用 &lt;code&gt;api-dev.example.com&lt;/code&gt; 代替）、在 Cloudflare 付费开通 Advanced Certificate Manager 单独为多级子域签证书、或者这个多级子域干脆走灰云（仅 DNS 解析）让访客直连源站用源站自己的证书。具体额度与开通方式以控制台为准。&lt;/p&gt;
&lt;p&gt;还要注意生效时间：刚接入域名时边缘证书需要一段时间签发（通常几分钟到数小时），在「SSL/TLS → 边缘证书」页面能看到状态，没到 Active 之前访客访问 HTTPS 会报证书错误，这属于正常等待，不是配置错误。&lt;/p&gt;
&lt;h2&gt;源站证书：两条正规路线&lt;/h2&gt;
&lt;p&gt;完全（严格）模式要求源站有一张「受信任 CA 签发、域名匹配、未过期」的证书。正规来源就两条，都是免费的：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;Let&apos;s Encrypt&lt;/th&gt;
&lt;th&gt;Cloudflare Origin CA&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;签发方&lt;/td&gt;
&lt;td&gt;公共 CA，全网浏览器都信任&lt;/td&gt;
&lt;td&gt;Cloudflare 自家 CA，只被 Cloudflare 信任&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;有效期&lt;/td&gt;
&lt;td&gt;90 天，靠工具自动续期&lt;/td&gt;
&lt;td&gt;最长 15 年，基本不用管续期&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;验证方式&lt;/td&gt;
&lt;td&gt;域名验证（HTTP 或 DNS 挑战）&lt;/td&gt;
&lt;td&gt;在 Cloudflare 控制台一键生成，无需验证&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;灰云直连时&lt;/td&gt;
&lt;td&gt;正常，浏览器直接信任&lt;/td&gt;
&lt;td&gt;报错：证书不受任何浏览器信任（正文细说）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合谁&lt;/td&gt;
&lt;td&gt;域名有时要灰云直连、或同一证书多处使用&lt;/td&gt;
&lt;td&gt;域名全程橙云代理、只经 Cloudflare 访问&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;**路线一：Let&apos;s Encrypt。**这是全世界用得最多的免费证书，Certbot 等工具可以全自动申请和续期。它的证书是「全网通用」的：哪怕某天你把某个子域改成灰云直连，访客浏览器也照样信任。如果你的源站是按前面系列文章用 Docker 部署的，具体的申请与部署方法可以直接看《用 Docker 部署 Nginx 反向代理与自动 HTTPS》(/posts/docker-nginx-https/) 里的 Certbot 路线，以及《用 Docker 部署 Caddy：自动 HTTPS 反向代理》(/posts/docker-caddy-https/)——Caddy 更是连证书都全自动托管，申请、续期都不用人管。用这两篇文章的方式把源站 HTTPS 跑通后，再把 Cloudflare 切到完全（严格）就是水到渠成。&lt;/p&gt;
&lt;p&gt;**路线二：Cloudflare Origin CA 源站证书。**在控制台「SSL/TLS → 源站服务器」里可以直接生成，选好域名（含通配符）和有效期（最长 15 年），下载证书和私钥贴到源站的 Nginx/Caddy 配置里就完事，省去了域名验证环节，15 年内不用操心续期。但要牢记它最大的限制：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Origin CA 证书只被 Cloudflare 一家信任，任何绕过 Cloudflare 直连源站的访问（灰云解析、直接用 IP 访问、内网测试）都会报证书不受信任。&amp;lt;/span&amp;gt;所以选它之前先确认：这个域名永远只走橙云、永远不需要直连。两个条件都满足，它就是最省心的选择；有一个不满足，老老实实用 Let&apos;s Encrypt。&lt;/p&gt;
&lt;p&gt;两条路线没有高下之分，只有合不合适。判断标准就一条：这个域名将来会不会有绕过 Cloudflare 直连源站的场景。会，用 Let&apos;s Encrypt；不会，Origin CA 一劳永逸。&lt;/p&gt;
&lt;p&gt;:::warning
无论选哪条路线，私钥文件都要当密码一样保管：权限设为仅 root 可读，不要提交到 Git 仓库，不要贴到任何公开场合。私钥泄露等于证书作废，任何人都能冒充你的源站。
:::&lt;/p&gt;
&lt;h2&gt;配套开关：这几个顺手配对&lt;/h2&gt;
&lt;p&gt;加密模式定好之后，「SSL/TLS」里还有几个配套设置，建议一并检查：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;始终使用 HTTPS（Always Use HTTPS）&lt;/strong&gt;：建议开。它是 Cloudflare 边缘层面的开关，把所有 HTTP 访问 301 跳转到 HTTPS。有了它，源站那边就不需要再配强制跳转规则——这也顺带避开了前面灵活模式死循环的雷区（当然，你已经按本文切到完全（严格）就更不存在这个问题）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;自动 HTTPS 重写（Automatic HTTPS Rewrites）&lt;/strong&gt;：建议开。它会把你页面 HTML 里写死的 &lt;code&gt;http://&lt;/code&gt; 资源链接自动改写成 &lt;code&gt;https://&lt;/code&gt;，专治图片、脚本、样式表写死 http 导致的「混合内容」警告。能改的它帮你改，但治标不治本，源头上还是应该把资源链接改成 https 或相对协议。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;最低 TLS 版本（Minimum TLS Version）&lt;/strong&gt;：建议设为 TLS 1.2。设成 1.0/1.1 会放进来一批老旧不安全的协议；直接拉到 1.3 又会把一部分老设备和老系统挡在门外。1.2 是目前兼容性与安全性的平衡点。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;TLS 1.3&lt;/strong&gt;：建议开。握手更快、安全性更好，没有理由关。同页面的 0-RTT 选项则建议保持关闭，它对静态站收益小，还会引入重放攻击的理论风险，不值得。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这几个开关都在「SSL/TLS → 边缘证书」页面附近，配一次管很久。&lt;/p&gt;
&lt;h2&gt;HSTS：唯一一个不能随手开的开关&lt;/h2&gt;
&lt;p&gt;HSTS（HTTP Strict Transport Security）的作用是告诉浏览器：「这个域名以后只许用 HTTPS 访问，在有效期内不许再走 HTTP，也不许在证书报错时点『继续访问』绕过。」浏览器收到这个响应头后会记下来，后续访问自动在本地把 http 改写成 https 再发出去。&lt;/p&gt;
&lt;p&gt;它确实能堵住降级攻击和首次访问被劫持的口子，但它是本文所有开关里唯一需要格外谨慎的一个，原因很简单：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;HSTS 一旦被浏览器记下，在 max-age 到期之前没有任何办法远程撤销——哪怕你马上在服务器上关掉它，已经收到过这个头的访客依然会强制走 HTTPS。&amp;lt;/span&amp;gt;如果你的 HTTPS 配置其实还没稳（证书会过期、某些子域还没配好 HTTPS、将来想临时切回 HTTP），贸然开一个长 max-age 的 HSTS，等于亲手把自己的站锁死，访客只能看到报错页，你连公告都发不出去。&lt;/p&gt;
&lt;p&gt;:::warning
开启 HSTS 的前提是：全站 HTTPS 已经稳定运行了一段时间、证书有自动续期、所有要包含的子域都确认支持 HTTPS。任何一条没落实，都先不要碰这个开关。
:::&lt;/p&gt;
&lt;p&gt;正确的开启姿势是「小步快跑」：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;先确认全站 HTTPS 稳定、证书续期自动化已经跑通至少一个周期。&lt;/li&gt;
&lt;li&gt;第一次只设很短的 max-age，比如 86400（一天），不开 includeSubDomains、不开 preload，先观察有没有异常。&lt;/li&gt;
&lt;li&gt;没问题后逐步放大：一周、一个月、半年，最后再到一年（31536000）。&lt;/li&gt;
&lt;li&gt;includeSubDomains 只在「所有子域都确定支持 HTTPS」之后才勾；preload 提交浏览器预加载名单是更不可逆的操作，个人站点基本没必要碰。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;在 Cloudflare 里，HSTS 在「SSL/TLS → 边缘证书 → HTTP 严格传输安全（HSTS）」处开启，配置项和上面说的完全对应，按上面的节奏填即可。&lt;/p&gt;
&lt;h2&gt;排障：证书类报错先对号入座&lt;/h2&gt;
&lt;p&gt;最后把这一篇相关的高频报错集中说清，看到错误码先对照是哪一段链路出了问题：&lt;/p&gt;
&lt;p&gt;**525：SSL 握手错误（SSL Handshake Error）。**发生在 Cloudflare 与源站握手阶段：源站的 443 端口没监听、源站证书链残缺、源站不支持 Cloudflare 使用的加密套件或 SNI，都会触发。先在源站本机用 &lt;code&gt;curl -vk https://127.0.0.1&lt;/code&gt; 和 &lt;code&gt;openssl s_client -connect 源站IP:443 -servername 你的域名&lt;/code&gt; 自查证书能不能正常出示，再回头查 Cloudflare 侧设置。&lt;/p&gt;
&lt;p&gt;**526：无效的 SSL 证书（Invalid SSL Certificate）。**这是完全（严格）模式的专属报错，含义非常明确：源站出示的证书没通过校验——过期了、自签的、或者证书上的域名和访问的域名对不上。解法就是回到上一节的两条路线，老老实实换一张正规证书；实在要临时恢复访问，可以先把模式降到完全（注意只是临时），换好证书再切回来。525 与 526 的更完整的定位流程，在本系列的排障篇《Cloudflare 故障排障：错误码全解》(/posts/cloudflare-troubleshooting/) 里有系统展开，这里不重复。&lt;/p&gt;
&lt;p&gt;**浏览器提示证书名称不匹配（NET::ERR_CERT_COMMON_NAME_INVALID）。**十有八九是多级子域问题：你访问的是 &lt;code&gt;a.b.example.com&lt;/code&gt;，而边缘证书的通配符只覆盖一级子域。对照「边缘证书」一节的三种解法处理即可。如果是一级子域还报这个错，先去边缘证书页面确认 Universal SSL 状态是不是还没 Active。&lt;/p&gt;
&lt;p&gt;**页面能打开但浏览器警告「混合内容」（Mixed Content）。**页面本身是 HTTPS，但里面的图片、脚本或接口还写着 &lt;code&gt;http://&lt;/code&gt; 地址，浏览器要么拦截要么警告。先开上文的自动 HTTPS 重写顶一阵，然后去页面源码里把写死的 http 资源逐个改掉，这才是根治。源站返回的 HTML 里如果有绝对地址，通常是程序的站点 URL 配置还留着 http，改掉即可。&lt;/p&gt;
&lt;p&gt;**切换模式后网站打不开。**大概率是顺序反了：先切了完全（严格）、源站却还没有合格证书。处理顺序永远是源站先装好证书并自测通过，再动 Cloudflare 的模式开关。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇的要点收拢成五句：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;加密模式只管 Cloudflare 到源站这一段，访客那一段由边缘证书自动负责，两段不要混为一谈。&lt;/li&gt;
&lt;li&gt;四种模式里，关闭是明文裸奔，灵活是半明文加死循环大坑，完全有加密没身份，完全（严格）才是生产环境该有的样子。&lt;/li&gt;
&lt;li&gt;源站证书走两条正规路线：要直连兼容选 Let&apos;s Encrypt，全程橙云图省心选 Origin CA（最长 15 年），两条都免费，没有理由长期停在自签和灵活模式上。&lt;/li&gt;
&lt;li&gt;配套开关里，始终使用 HTTPS、自动 HTTPS 重写、最低 TLS 1.2、开启 TLS 1.3 是标准组合；唯独 HSTS 必须等 HTTPS 完全稳定后，从短 max-age 开始小步开启。&lt;/li&gt;
&lt;li&gt;报错先对号入座：525 查源站握手与证书链，526 是严格模式在拦不合格证书，名称不匹配先怀疑多级子域，混合内容去改页面里的 http 资源。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;把这一篇配好，你的站点就是两段全加密、证书全正规的状态。下一篇进入加速与安全篇，讲怎么让 Cloudflare 把内容真正缓存起来、把速度提上去。&lt;/p&gt;
</content:encoded></item><item><title>Cloudflare 故障排障：错误码全解</title><link>https://www.anexns.cloudns.org/posts/cloudflare-troubleshooting/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-troubleshooting/</guid><description>网站挂了先看错误码：521 到 526、1000 系列逐个对应什么故障，再给一套通用的二分定位法——暂停 Cloudflare 切到源站直连，五分钟分清是边缘的问题还是源站的问题。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;网站套上 Cloudflare 之后，一旦打不开，屏幕上最先出现的往往是一张带着错误码的页面。很多人第一反应是乱改设置：加密模式换一换、缓存清一清、规则关一关，改了半天故障还在，甚至越改越乱。其实 Cloudflare 的错误码体系非常规整，每个码都精确对应一段链路上的某类故障——&lt;strong&gt;看懂错误码，就等于知道了该往哪儿查&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;这一篇是 Cloudflare 实战系列的收官篇，主线分三段：先给一套不依赖具体错误码的通用定位法（二分法），再把 5xx 和 1xxx 两大系列错误码逐个拆开讲清每个码的官方含义、常见成因和排查入口，最后用一个完整的 522 排障剧本把方法论串起来。以后再遇到网站打不开，照着这篇的顺序走，五分钟内基本能锁定故障在哪一段。&lt;/p&gt;
&lt;h2&gt;先立规矩：排障前不要乱动配置&lt;/h2&gt;
&lt;p&gt;动手之前先强调一条纪律：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;故障期间每改一处配置，都要记下来改了什么、原值是什么&amp;lt;/span&amp;gt;。Cloudflare 的很多设置有传播延迟，DNS 和规则变更又涉及全球节点生效时间，你如果一口气改五处，最后好了都不知道是哪一处起的作用，坏了也不知道该回滚哪一处。正确姿势是：先取证（错误码、错误页截图、发生时间），再按下面的二分法定位，一次只改一处，改完等一两分钟再验证。&lt;/p&gt;
&lt;h2&gt;通用方法论：二分定位法&lt;/h2&gt;
&lt;p&gt;不管错误码是什么，第一步永远是回答同一个问题：&lt;strong&gt;故障出在 Cloudflare 边缘这一段，还是源站那一段？&lt;/strong&gt; 把这个问题答出来，排查范围立刻缩小一半。方法有三种，互为印证。&lt;/p&gt;
&lt;h3&gt;方法一：切灰云直连源站复现&lt;/h3&gt;
&lt;p&gt;在 Cloudflare 控制台的 DNS 管理里，把出问题的那条记录的代理状态从橙云改成灰云（仅 DNS），等一两分钟后重新访问。如果灰云下网站恢复正常，说明源站本身是好的，故障在 Cloudflare 的代理链路或相关设置上（加密模式、规则、缓存等）；如果灰云下还是打不开，那 Cloudflare 只是&quot;背锅&quot;的，问题在源站本身或者 DNS 记录指错了地方。&lt;/p&gt;
&lt;p&gt;:::warning
切灰云会把源站真实 IP 直接暴露在 DNS 解析结果里。如果你的源站 IP 一直靠橙云隐藏，切之前要想清楚；排障结束后记得第一时间切回橙云。
:::&lt;/p&gt;
&lt;h3&gt;方法二：curl 加 --resolve 绕过解析直打源站&lt;/h3&gt;
&lt;p&gt;不想动 DNS 记录的话，用 &lt;code&gt;curl&lt;/code&gt; 的 &lt;code&gt;--resolve&lt;/code&gt; 参数可以不动任何配置就直连源站验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 把 example.com 强制解析到源站 IP，绕过 Cloudflare 直接访问源站
curl -I --resolve example.com:443:203.0.113.10 https://example.com/

# 看详细的连接与 TLS 握手过程
curl -v --resolve example.com:443:203.0.113.10 https://example.com/ 2&amp;gt;&amp;amp;1 | head -40
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--resolve&lt;/code&gt; 的格式是 &lt;code&gt;主机名:端口:IP&lt;/code&gt;。这条命令返回正常页面，说明源站的 Web 服务、证书、应用都是好的，问题在 Cloudflare 侧；如果直连源站就报错，那错误码是什么不重要了，先修源站。注意直打源站时如果源站配了基于 SNI 的虚拟主机或者只认特定 Host 头，结果要结合源站配置看。&lt;/p&gt;
&lt;p&gt;再补一条查当前到底走没走 Cloudflare 的命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 看解析结果：返回的是 Cloudflare 的 Anycast IP 还是源站 IP
dig +short example.com

# 看响应头里有没有 cf-ray，有就是经过了 Cloudflare 边缘
curl -sI https://example.com/ | grep -i &quot;cf-ray\|server&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;方法三：看错误页是谁家的&lt;/h3&gt;
&lt;p&gt;打开出故障的页面，看它长什么样：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;错误页特征&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;带 Cloudflare 标志、显示 Ray ID、标注 &quot;Error 5xx&quot; 和 Host/ Browser/ Cloudflare 三段状态图&lt;/td&gt;
&lt;td&gt;Cloudflare 生成的错误页，故障在回源链路上，页面里三段状态图会直接标出哪一段是红的&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;是源站自己的 404/500 页面样式，或 Nginx/Apache 的默认报错页&lt;/td&gt;
&lt;td&gt;请求已经到达源站，是源站应用层的问题，与 Cloudflare 无关&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;浏览器自己的报错页（如 ERR_TOO_MANY_REDIRECTS、ERR_SSL_VERSION_OR_CIPHER_MISMATCH）&lt;/td&gt;
&lt;td&gt;没有标准错误码，多半是重定向循环或 TLS 配置问题，见后文专节&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;三段状态图是 Cloudflare 错误页里最有价值的信息：Browser、Cloudflare、Host 三段哪段标红，故障就从哪段查起。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;把三种方法合起来，就是一条固定的排障流水线：&lt;strong&gt;记错误码 → 看错误页归属 → curl --resolve 直连源站验证 → 得出&quot;边缘问题还是源站问题&quot;的结论 → 再去查对应那一段的细项&lt;/strong&gt;。下面的错误码详解，本质上都是这条流水线走到最后一步时的对照表。&lt;/p&gt;
&lt;h2&gt;5xx 系列：回源链路故障&lt;/h2&gt;
&lt;p&gt;5xx 错误页都是 Cloudflare 生成的，含义是&quot;Cloudflare 替你去源站取页面时出了问题&quot;。逐个拆：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;错误码&lt;/th&gt;
&lt;th&gt;官方含义&lt;/th&gt;
&lt;th&gt;最常见成因&lt;/th&gt;
&lt;th&gt;第一排查动作&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;520&lt;/td&gt;
&lt;td&gt;源站返回了未知错误或空响应&lt;/td&gt;
&lt;td&gt;源站应用崩溃、返回了超大响应头、连接被源站重置&lt;/td&gt;
&lt;td&gt;看源站错误日志&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;521&lt;/td&gt;
&lt;td&gt;源站拒绝了 Cloudflare 的连接&lt;/td&gt;
&lt;td&gt;Web 服务没起来、端口没监听、防火墙直接拒绝&lt;/td&gt;
&lt;td&gt;在源站本机 curl localhost 验证服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;522&lt;/td&gt;
&lt;td&gt;与源站建立连接超时&lt;/td&gt;
&lt;td&gt;源站防火墙没有放行 Cloudflare 的 IP 段、源站宕机或过载&lt;/td&gt;
&lt;td&gt;查源站防火墙与安全组&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;523&lt;/td&gt;
&lt;td&gt;源站不可达&lt;/td&gt;
&lt;td&gt;DNS 记录指向了不存在或错误的 IP、源站所在网络路由异常&lt;/td&gt;
&lt;td&gt;核对 A/AAAA 记录的 IP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;524&lt;/td&gt;
&lt;td&gt;已连上源站但源站响应超时&lt;/td&gt;
&lt;td&gt;慢接口、长任务、源站处理能力不足&lt;/td&gt;
&lt;td&gt;看源站接口耗时日志&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;525&lt;/td&gt;
&lt;td&gt;与源站的 SSL 握手失败&lt;/td&gt;
&lt;td&gt;源站证书过期/不完整、源站不支持相应的 TLS 版本或 SNI&lt;/td&gt;
&lt;td&gt;在源站本机测 TLS&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;526&lt;/td&gt;
&lt;td&gt;源站证书无效&lt;/td&gt;
&lt;td&gt;加密模式为&quot;完全（严格）&quot;而源站证书自签或过期&lt;/td&gt;
&lt;td&gt;换有效证书或调整加密模式&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;520：源站返回未知错误&lt;/h3&gt;
&lt;p&gt;520 是个&quot;兜底&quot;错误码：连接建立了，但源站返回了 Cloudflare 无法归类的响应——空响应、连接被意外重置、响应头过大或格式异常都可能触发。它通常意味着源站应用层出了问题（进程崩溃、反向代理配置错误、应用返回了畸形的响应）。排查入口只有一个：去源站看 Web 服务器和应用的错误日志，用前面 &lt;code&gt;--resolve&lt;/code&gt; 的方法直连复现，看源站自己报什么。&lt;/p&gt;
&lt;h3&gt;521：源站拒绝连接&lt;/h3&gt;
&lt;p&gt;521 表示 Cloudflare 连到源站 IP 的对应端口时，连接被明确拒绝（收到 RST）。翻译成人话就是：&lt;strong&gt;那个 IP 上的那个端口，没有服务在听，或者防火墙直接把连接拒了&lt;/strong&gt;。最常见的场景是 Web 服务挂了没拉起来、服务只监听了别的端口、或者源站防火墙规则把连接 DROP/REJECT 了。排查顺序：先 SSH 上源站，&lt;code&gt;ss -tlnp&lt;/code&gt; 看 80/443 是否在监听，再 &lt;code&gt;curl -I http://127.0.0.1/&lt;/code&gt; 在本机验证服务本身，最后查防火墙。&lt;/p&gt;
&lt;h3&gt;522：连接超时&lt;/h3&gt;
&lt;p&gt;522 和 521 只差一个字，含义完全不同：522 是连接请求发出去之后&lt;strong&gt;石沉大海&lt;/strong&gt;，在超时时间内既没连上也没被拒绝。现实中 522 最高频的成因是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;源站防火墙或云厂商安全组没有放行 Cloudflare 的 IP 段&amp;lt;/span&amp;gt;——源站把 Cloudflare 回源的连接默默丢弃了。Cloudflare 回源用的是它自己的一组官方 IP 段，源站防火墙如果做了来源 IP 白名单，必须把这组段加进去（文末有获取方式）。其次才是源站宕机、过载到无力响应、或者中间网络故障。本篇最后的完整剧本就是一个 522 的实例。&lt;/p&gt;
&lt;h3&gt;523：源站不可达&lt;/h3&gt;
&lt;p&gt;523 表示 Cloudflare 按 DNS 记录找到源站 IP 后，网络层根本到达不了。重点查两件事：一是 DNS 记录里的 IP 写错了（换了服务器忘了改记录、IP 抄错一位）；二是源站所在机房或云厂商的网络路由问题。前者自己改记录即可，后者只能等厂商恢复或切换源站。&lt;/p&gt;
&lt;h3&gt;524：源站响应超时&lt;/h3&gt;
&lt;p&gt;524 说明 TCP 连接和请求都成功了，但源站处理太久，超过了 Cloudflare 的等待时间（免费版默认 100 秒量级，以官方文档为准）。典型场景是慢 SQL、大报表导出、文件转码这类长任务接口。解法不在 Cloudflare 侧乱调，而在源站侧：把长任务改成异步（先返回任务 ID，后台跑完再查结果），或者把这类接口放到一个不经过 Cloudflare 代理的子域名上直连。&lt;/p&gt;
&lt;h3&gt;525：SSL 握手失败&lt;/h3&gt;
&lt;p&gt;当加密模式是&quot;完全&quot;或&quot;完全（严格）&quot;时，Cloudflare 回源要和源站做 TLS 握手，525 就是握手这一步失败了。常见成因：源站证书过期、证书链不完整、源站只支持过低的 TLS 版本、源站没有正确配置 SNI 对应的证书。排查时在源站上直接测：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 在源站本机验证 TLS 握手与证书
openssl s_client -connect 127.0.0.1:443 -servername example.com &amp;lt;/dev/null

# 直连源站 IP 并指定 SNI，看返回的证书是谁的、何时过期
curl -vk --resolve example.com:443:203.0.113.10 https://example.com/ 2&amp;gt;&amp;amp;1 | grep -A2 &quot;subject\|expire&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;加密模式各档位对源站证书的要求不同，这是 525/526 的总开关，先去 &lt;a href=&quot;/posts/cloudflare-ssl-tls/&quot;&gt;Cloudflare SSL/TLS 加密模式详解&lt;/a&gt; 把模式对照表看一遍再动手。&lt;/p&gt;
&lt;h3&gt;526：源站证书无效&lt;/h3&gt;
&lt;p&gt;526 只会出现在加密模式为&quot;完全（严格）&quot;时：握手能完成，但证书通不过严格校验——自签证书、过期、域名对不上，都会被判无效。它和 525 的区分非常实操：&lt;strong&gt;525 是&quot;手握不上&quot;，526 是&quot;手握上了但证件不合格&quot;&lt;/strong&gt;。解法二选一：给源站换一张正规 CA 签发的证书（或用 Cloudflare 的 Origin CA 源站证书），或者把加密模式降到&quot;完全&quot;。降模式只是绕过校验，治本还是换证书。&lt;/p&gt;
&lt;h2&gt;重定向死循环专节&lt;/h2&gt;
&lt;p&gt;表现：浏览器报 &lt;code&gt;ERR_TOO_MANY_REDIRECTS&lt;/code&gt;，页面根本打不开；用 curl 抓会看到 301/302 在两个地址之间来回跳：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 看重定向链，死循环时会刷出一长串互相跳转
curl -sIL https://example.com/ | grep -i &quot;^HTTP\|^location&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;成因九成是这个经典组合：&lt;strong&gt;Cloudflare 加密模式设为&quot;灵活&quot;，源站又配了强制 HTTP 跳 HTTPS&lt;/strong&gt;。灵活模式下 Cloudflare 回源走的是 HTTP，源站一看是 HTTP 就返回&quot;请跳 HTTPS&quot;，浏览器跳到 HTTPS 后 Cloudflare 又用 HTTP 回源……无限循环。&lt;code&gt;curl&lt;/code&gt; 抓包时能看到 Location 在 http 和 https 之间反复横跳，浏览器则直接放弃并报重定向过多。&lt;/p&gt;
&lt;p&gt;解法在 SSL 篇里已经讲透：把加密模式改成&quot;完全（严格）&quot;并给源站配好证书，让回源本身就是 HTTPS，循环立刻消失。临时救急可以先关掉源站的强制跳转，但&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要用&quot;把加密模式改回灵活 + 关掉源站 HTTPS&quot;这种方式长期凑合&amp;lt;/span&amp;gt;，那等于整段回源明文裸奔。详细对照见 &lt;a href=&quot;/posts/cloudflare-ssl-tls/&quot;&gt;Cloudflare SSL/TLS 加密模式详解&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;1xxx 系列：配置与解析类错误&lt;/h2&gt;
&lt;p&gt;1xxx 是 Cloudflare 的客户端错误系列，多半和 DNS 配置、账户设置有关，不涉及源站死活：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;错误码&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;定位与入口&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1000&lt;/td&gt;
&lt;td&gt;DNS 记录指向了被禁止的 IP&lt;/td&gt;
&lt;td&gt;记录指向了 Cloudflare 自己的 IP 或保留地址，改 A/AAAA 记录指向真实源站&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1001&lt;/td&gt;
&lt;td&gt;DNS 解析错误&lt;/td&gt;
&lt;td&gt;域名解析链异常，检查记录是否存在、CNAME 目标是否可解析&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1016&lt;/td&gt;
&lt;td&gt;源站 DNS 错误&lt;/td&gt;
&lt;td&gt;代理记录找不到源站：CNAME 目标不存在或记录配置残缺，去 DNS 页核对&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1033&lt;/td&gt;
&lt;td&gt;Cloudflare Tunnel 未运行&lt;/td&gt;
&lt;td&gt;域名绑了 Tunnel 但 &lt;code&gt;cloudflared&lt;/code&gt; 没在跑，去源站把隧道服务拉起来&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1101&lt;/td&gt;
&lt;td&gt;Worker 运行时异常&lt;/td&gt;
&lt;td&gt;部署的 Worker 代码抛了未捕获异常，去 Workers 控制台看日志改代码&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;其中 1033 在自建服务场景里很常见：域名走 Tunnel 发布，服务器重启后 &lt;code&gt;cloudflared&lt;/code&gt; 没自启，网站就报 1033。它的好处是定位极其明确——错误码直接告诉你隧道没在运行，SSH 上去 &lt;code&gt;systemctl status cloudflared&lt;/code&gt; 一看便知，拉起来即恢复。Tunnel 的部署与自启配置见 &lt;a href=&quot;/posts/cloudflare-tunnel/&quot;&gt;Cloudflare Tunnel：不暴露源站发布服务&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;1101 则是 Worker 的问题：请求命中了某个路由上的 Worker，代码运行时抛错。去 Cloudflare 控制台的 Workers 页面打开实时日志复现一次，异常堆栈会直接显示出来。&lt;/p&gt;
&lt;h2&gt;其他常见状况：不是 5xx 也要会认&lt;/h2&gt;
&lt;h3&gt;ERR_SSL_VERSION_OR_CIPHER_MISMATCH&lt;/h3&gt;
&lt;p&gt;浏览器报这个错且没有 Cloudflare 错误码，通常是 TLS 版本对不上：Cloudflare 侧设置的最低 TLS 版本高于访客浏览器/客户端支持的版本，或者边缘证书还没签发完成（刚接入的域名偶尔会短暂出现）。排查：去控制台 SSL/TLS → 边缘证书，确认证书状态是 Active；再看最低 TLS 版本设置，老旧客户端要访问就不能把下限抬到 TLS 1.3 only。&lt;/p&gt;
&lt;h3&gt;缓存导致的&quot;故障假象&quot;&lt;/h3&gt;
&lt;p&gt;改完源站页面，用户说&quot;还是旧的/还是坏的&quot;，十有八九是缓存里还留着旧版本甚至当时的错误页。验证方法：给 URL 随便加个参数绕开缓存，或者开无痕窗口访问：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 带随机参数请求，对比与正常请求的差异
curl -sI &quot;https://example.com/?_t=$(date +%s)&quot; | grep -i &quot;cf-cache-status\|HTTP&quot;
curl -sI https://example.com/ | grep -i &quot;cf-cache-status\|HTTP&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;响应头里的 &lt;code&gt;cf-cache-status: HIT&lt;/code&gt; 说明这份内容是从边缘缓存里出的。确认是缓存问题后，去控制台清除对应 URL 的缓存即可，别把好好的源站配置翻个底朝天。&lt;/p&gt;
&lt;h3&gt;被 WAF 拦截的 403&lt;/h3&gt;
&lt;p&gt;页面显示 403 并带 Ray ID、写着被安全规则拦截，这是 WAF 自定义规则或托管规则命中了请求，不是故障。去控制台的安全性 → 事件里按 Ray ID 或来源 IP 查，能看到命中的是哪条规则，再决定是放行这个 IP、给路径加例外还是修规则表达式。规则的写法与误伤处理见 &lt;a href=&quot;/posts/cloudflare-waf-security/&quot;&gt;WAF 与安全规则实战&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;源站侧配合清单&lt;/h2&gt;
&lt;p&gt;很多 5xx 的根子在源站侧的配合没做到位，集中列一份清单，部署时逐项核对：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;放行 Cloudflare 官方 IP 段&lt;/strong&gt;：源站防火墙和云安全组的入站规则里，80/443 端口要对 Cloudflare 公布的全部 IPv4/IPv6 段放行。这份段列表会更新，去 Cloudflare 官网的 IP Ranges 页面（cloudflare.com/ips）拿最新版，不要抄博客里的旧列表。反过来也可以利用这一点：源站只允许 Cloudflare 的段回源访问，其他来源一律拒绝，天然挡住绕过边缘直打源站的流量。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;学会看回源日志&lt;/strong&gt;：源站访问日志里，来自 Cloudflare 段 IP 的请求就是回源流量；故障时段去日志里搜对应时间点，看请求到底有没有到达源站、源站返回了什么状态码，这是判断&quot;请求死在哪一段&quot;的最硬证据。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;还原真实访客 IP&lt;/strong&gt;：经过代理后，源站日志里看到的全是 Cloudflare 的 IP。真实访客 IP 在 &lt;code&gt;CF-Connecting-IP&lt;/code&gt; 请求头里，Nginx/Apache 配置一行日志格式调整即可记录下来，做封禁和统计时要用它，别对着回源 IP 操作。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;完整剧本：一次 522 的定位全过程&lt;/h2&gt;
&lt;p&gt;背景：早上用户反馈&quot;网站打不开，显示 522&quot;。按流程走：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步，确认现象与错误页归属。&lt;/strong&gt; 自己打开网站，确实是 Cloudflare 品牌错误页，码是 522，页面三段状态图里 Host 标红。初步判断：回源连接超时，重点查源站连通性。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二步，二分定位。&lt;/strong&gt; 直连源站验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 直连源站，源站本身的服务是好的
curl -I --resolve example.com:443:203.0.113.10 https://example.com/
# 返回 HTTP/2 200 —— 源站服务正常
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再 SSH 上源站自查：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ss -tlnp | grep -E &apos;:80|:443&apos;   # 服务在正常监听
curl -I http://127.0.0.1/        # 本机访问正常
uptime                           # 负载正常，没被打满
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;源站一切正常，但 Cloudflare 连不上来——故障点锁定在&quot;源站入口对 Cloudflare 的流量做了拦截&quot;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三步，查防火墙。&lt;/strong&gt; 看源站的防火墙规则和云厂商安全组，发现昨晚做过一次安全加固，把 443 的入站来源改成了白名单模式，只放行了自家办公 IP 和监控 IP，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Cloudflare 的回源 IP 段不在白名单里，连接被默默丢弃，正是 522 的典型成因&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第四步，修复与验证。&lt;/strong&gt; 从官网拿到 Cloudflare 最新 IP 段列表，逐段加入安全组和防火墙的 80/443 放行规则。改完等一分钟，刷新网站恢复正常；再用第一节的命令复查解析与响应头，确认橙云代理状态正常。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第五步，留痕复盘。&lt;/strong&gt; 把&quot;源站防火墙白名单必须包含 Cloudflare IP 段&quot;写进运维备忘，并在监控里给网站加一条可用性探测——这次故障从发生到恢复全靠用户上报，说明缺的不是技术，是监控。&lt;/p&gt;
&lt;p&gt;整个过程没有动过 Cloudflare 侧任何设置。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;522 先查源站防火墙对 Cloudflare 段的放行，这是命中率最高的一条。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;预防清单：让故障少发生&lt;/h2&gt;
&lt;p&gt;排障能力决定下限，预防决定上限。收官之前给一份短清单，也是对整个系列的收束：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;可用性监控要独立于源站&lt;/strong&gt;：用外部探测服务盯网站的 HTTP 状态，挂了第一时间告警到手机，不要等用户上报。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;证书两头都盯到期时间&lt;/strong&gt;：边缘证书 Cloudflare 管，源站证书要自己盯；&quot;完全（严格）&quot;模式下源站证书过期就是 526 全站故障。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;改配置留痕&lt;/strong&gt;：DNS、规则、加密模式每次变更记一笔时间和内容，排障时能快速回答&quot;昨天动过什么&quot;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;重大变更先灰度&lt;/strong&gt;：规则和缓存策略先对单条路径或子域名生效，确认无误再铺全站。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;源站防火墙与 Cloudflare IP 段同步更新&lt;/strong&gt;：Cloudflare 的 IP 段有变动时，源站白名单要跟着更新，这条写进定期巡检。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;至此 Cloudflare 实战系列十篇全部完成：从接入、DNS、SSL、缓存、规则、WAF、Tunnel、Workers、R2 到排障，构成了一条从&quot;把域名搬进来&quot;到&quot;出事能自己修&quot;的完整链路。真遇到错误码时别慌——先二分，再对码，最后动手改一处验一处，基本都能收敛到根因。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;排障第一步不是改配置，而是用二分定位法分清故障在 Cloudflare 边缘还是源站：切灰云、curl --resolve 直连、看错误页归属，三种方法互为印证。&lt;/li&gt;
&lt;li&gt;5xx 是回源链路故障：521 查服务监听，522 查防火墙对 Cloudflare IP 段的放行，524 是源站慢，525/526 是源站 TLS 与证书问题，且与加密模式强相关。&lt;/li&gt;
&lt;li&gt;重定向死循环的元凶是&quot;灵活模式 + 源站强制 HTTPS&quot;，正解是改&quot;完全（严格）&quot;并配好源站证书。&lt;/li&gt;
&lt;li&gt;1xxx 多为配置问题：1000/1016 查 DNS 记录，1033 是 Tunnel 没运行，1101 是 Worker 代码异常。&lt;/li&gt;
&lt;li&gt;403 拦截、缓存旧页、TLS 版本报错这三类&quot;假象故障&quot;要会认，别误伤源站配置。&lt;/li&gt;
&lt;li&gt;源站侧三件套：放行 Cloudflare 官方 IP 段、会看回源日志、用 CF-Connecting-IP 还原真实访客 IP。&lt;/li&gt;
&lt;li&gt;预防胜于排障：外部监控、证书到期提醒、变更留痕、防火墙白名单与 Cloudflare IP 段同步更新。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>Cloudflare Tunnel：不暴露源站发布服务</title><link>https://www.anexns.cloudns.org/posts/cloudflare-tunnel/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-tunnel/</guid><description>源站一个入站端口都不用开：cloudflared 从内向外建隧道、访客经 Cloudflare 边缘进来，完整走通安装、建隧道、绑域名与服务自启，再讲清它与传统反向代理的取舍。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;把一个跑在自己服务器（甚至家里机器）上的 Web 服务发布到公网，传统做法绕不开三件事：在防火墙和安全组里开放 80/443 端口、在 DNS 里把域名解析到源站 IP、让全世界的请求直接打到你的机器上。这套做法本身没错，但它带来一个长期存在的暴露面：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;源站 IP 一旦被查到，攻击者就能绕过 Cloudflare 边缘直接打源站&amp;lt;/span&amp;gt;，你套在边缘上的 WAF、限速、质询规则全部失效，DDoS 更是直接灌进源站的带宽。历史上源站 IP 的泄露渠道太多了：历史 DNS 记录、证书透明度日志、邮件头、子域名遗漏，任何一个都能让你的&quot;藏 IP&quot;努力白费。&lt;/p&gt;
&lt;p&gt;Cloudflare Tunnel（隧道，原名 Argo Tunnel）换了个思路：不再等外面的人连进来，而是由源站上的一个小守护进程 cloudflared &lt;strong&gt;主动向外&lt;/strong&gt;与 Cloudflare 边缘建立长连接，访客的请求先到边缘，再顺着这条已经建好的连接&quot;塞&quot;回源站。整个过程里，源站不需要开放任何入站端口，DNS 里也不出现源站 IP。本篇以 Debian 为主线，完整走通本地配置型隧道的安装、创建、绑域名、多服务分发和系统服务自启，最后讲清它与 Nginx 反向代理各自的适用场景。&lt;/p&gt;
&lt;p&gt;主线先说清楚：理解原理 → 装 cloudflared → 登录授权 → 创建隧道 → 写 ingress 配置 → 绑定域名 → 试跑验证 → 装成系统服务 → 排障与选型。&lt;/p&gt;
&lt;h2&gt;传统发布方式的暴露面&lt;/h2&gt;
&lt;p&gt;先把问题摆全。用 Nginx 反向代理发布服务时（具体做法见 &lt;a href=&quot;/posts/docker-nginx-https/&quot;&gt;用 Docker 部署 Nginx 反向代理与自动 HTTPS&lt;/a&gt;），链路是这样的：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;环节&lt;/th&gt;
&lt;th&gt;传统反代发布&lt;/th&gt;
&lt;th&gt;带来的暴露面&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;入站端口&lt;/td&gt;
&lt;td&gt;源站开放 80/443&lt;/td&gt;
&lt;td&gt;端口扫描可探测，服务指纹可识别&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;DNS 记录&lt;/td&gt;
&lt;td&gt;A/AAAA 直接指向源站 IP（开橙云后由边缘代答）&lt;/td&gt;
&lt;td&gt;历史记录、旁路渠道可查到真实 IP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;流量路径&lt;/td&gt;
&lt;td&gt;访客 → 边缘 → 源站公网 IP&lt;/td&gt;
&lt;td&gt;知道 IP 即可绕过边缘直连源站&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;证书&lt;/td&gt;
&lt;td&gt;源站自己申请维护&lt;/td&gt;
&lt;td&gt;证书透明度日志里有域名与源站线索&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;家庭/内网机器&lt;/td&gt;
&lt;td&gt;需要公网 IP 或端口映射&lt;/td&gt;
&lt;td&gt;没有公网 IP 时根本发不出去&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;其中最要命的是第三条。很多人给域名开了橙云代理，以为源站就藏好了，实际上只要源站 IP 通过任何渠道泄露过一次，攻击者就可以用 Host 头直连源站，边缘的防护一层都用不上。Tunnel 要解决的正是这个问题：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;从架构上消灭入站连接——源站只出不进，DNS 里只剩隧道，真实 IP 没有任何公开记录可查。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;Tunnel 的工作原理&lt;/h2&gt;
&lt;p&gt;cloudflared 是 Cloudflare 官方的隧道守护进程，开源、单二进制、无运行时依赖。它启动后会主动向 Cloudflare 边缘发起并维持 &lt;strong&gt;4 条长连接&lt;/strong&gt;（连接到就近的多个边缘节点，协议默认走 QUIC，网络不支持时可回退到 HTTP/2）。这 4 条连接就是隧道的全部：任何一条活着，隧道就是通的；单条断开会自动重连，不影响其余连接上的流量。&lt;/p&gt;
&lt;p&gt;访客侧的路径是这样的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;访客浏览器
   │  ① DNS 查询 app.example.com，得到的是指向隧道的 CNAME
   ▼
Cloudflare 边缘节点
   │  ② 边缘发现这个域名绑定了一条隧道
   │  ③ 请求顺着 cloudflared 预先建好的长连接反向送回源站
   ▼
cloudflared（运行在源站上）
   │  ④ 按 ingress 规则把请求转给本机服务
   ▼
http://localhost:8080 上的实际应用
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意第 ③ 步的方向：连接是源站建的，请求是&quot;顺流而下&quot;的，源站的防火墙对入站方向可以全关。这带来几个直接结果：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;零入站端口&lt;/strong&gt;：源站防火墙、安全组不需要为这个服务开放任何端口，&lt;code&gt;ss -tlnp&lt;/code&gt; 里 cloudflared 只有出站连接。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;IP 不进 DNS&lt;/strong&gt;：域名解析的结果是 &lt;code&gt;&amp;lt;隧道ID&amp;gt;.cfargotunnel.com&lt;/code&gt; 的 CNAME，解析不到源站 IP。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;没有公网 IP 也能发布&lt;/strong&gt;：家里宽带、NAT 后的机器、云上只有内网 IP 的实例，只要能出站访问互联网，就能建隧道。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;边缘能力全保留&lt;/strong&gt;：WAF、缓存、限速、Access 登录墙都照常生效，因为流量本来就先过边缘。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;它和普通橙云代理的区别，很多人容易混，一张表分清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;橙云代理（普通模式）&lt;/th&gt;
&lt;th&gt;Cloudflare Tunnel&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;连接发起方&lt;/td&gt;
&lt;td&gt;边缘按需回源连接源站&lt;/td&gt;
&lt;td&gt;源站 cloudflared 主动建长连接&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;源站入站端口&lt;/td&gt;
&lt;td&gt;必须开放 80/443&lt;/td&gt;
&lt;td&gt;不需要开放任何端口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;DNS 记录内容&lt;/td&gt;
&lt;td&gt;A/AAAA 指向源站 IP&lt;/td&gt;
&lt;td&gt;CNAME 指向 cfargotunnel.com&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;源站 IP 泄露风险&lt;/td&gt;
&lt;td&gt;有（历史记录等渠道）&lt;/td&gt;
&lt;td&gt;无公开记录可查&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;源站要求&lt;/td&gt;
&lt;td&gt;有公网 IP&lt;/td&gt;
&lt;td&gt;只要能出站上网&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;源站组件&lt;/td&gt;
&lt;td&gt;Web 服务器/反代即可&lt;/td&gt;
&lt;td&gt;额外常驻 cloudflared&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;回源加密&lt;/td&gt;
&lt;td&gt;取决于 SSL 模式配置&lt;/td&gt;
&lt;td&gt;隧道连接本身加密，无需另配&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
Tunnel 不是&quot;套了 CDN 的内网穿透玩具&quot;。它改变的是连接方向与信任边界：以前你要防的是&quot;全世界连我的 80/443&quot;，现在你要守的是 cloudflared 的隧道凭据文件——&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;凭据 JSON 一旦泄露，别人可以用它在任意机器上把你的隧道跑起来接管流量&amp;lt;/span&amp;gt;，所以这个文件要按私钥级别保管，权限收紧、不进 Git、不随手拷贝。
:::&lt;/p&gt;
&lt;h2&gt;两种建法：先选路线&lt;/h2&gt;
&lt;p&gt;官方提供两种管理方式，先选一条，别混着来：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;建法&lt;/th&gt;
&lt;th&gt;配置存放位置&lt;/th&gt;
&lt;th&gt;操作入口&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;控制台远程管理型（Dashboard-managed）&lt;/td&gt;
&lt;td&gt;Cloudflare 后台&lt;/td&gt;
&lt;td&gt;Zero Trust 控制台网页点选&lt;/td&gt;
&lt;td&gt;多人协作、不想碰配置文件、要配合 Access 策略&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本地配置文件型（Locally-managed）&lt;/td&gt;
&lt;td&gt;源站本机 config.yml&lt;/td&gt;
&lt;td&gt;命令行 tunnel 子命令&lt;/td&gt;
&lt;td&gt;单人运维、配置要进版本管理、服务器上批量操作&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;两者跑的是同一个 cloudflared、同一套隧道协议，区别只在&quot;配置从哪来&quot;：远程管理型把配置存在 Cloudflare 那边，cloudflared 启动时拉取；本地型读本机文件。&lt;strong&gt;本篇主线走本地配置文件型&lt;/strong&gt;，因为它全程命令行完成、配置可审计、和本系列的操作习惯一致。远程管理型的流程梗概是：登录 Zero Trust 控制台 → Networks → Tunnels → Create a tunnel → 选 Cloudflared → 给隧道起名 → 控制台会生成一条带 Token 的安装/运行命令，在源站执行 → 回到控制台添加 Public Hostname（子域名 + 本地服务地址）→ 保存即生效。它的凭据形态是 Token 而不是 JSON 文件，服务安装命令控制台会直接给全，后面&quot;装成系统服务&quot;一节的思路相通，遇到时对照官方文档操作即可（细节以官方文档为准）。&lt;/p&gt;
&lt;h2&gt;安装 cloudflared&lt;/h2&gt;
&lt;p&gt;Debian 上推荐走 Cloudflare 官方软件包仓库，版本跟得上、升级走 apt。依次执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 添加官方仓库的签名密钥
sudo mkdir -p --mode=0755 /usr/share/keyrings
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg &amp;gt;/dev/null

# 添加 cloudflared 仓库源
echo &apos;deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main&apos; | sudo tee /etc/apt/sources.list.d/cloudflared.list

# 安装
sudo apt update
sudo apt install cloudflared

# 确认版本
cloudflared --version
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;能输出形如 &lt;code&gt;cloudflared version 2025.x.x (built ...)&lt;/code&gt; 的版本号即安装成功。不想加仓库也可以去官方发布渠道下载对应架构的 &lt;code&gt;.deb&lt;/code&gt; 包用 &lt;code&gt;dpkg -i&lt;/code&gt; 安装，两种方式装的是同一个程序；但仓库方式后续 &lt;code&gt;apt upgrade&lt;/code&gt; 能一起升级，长期运维更省事。包名、仓库地址这类细节若与你看到的不一致，以官方文档为准。&lt;/p&gt;
&lt;p&gt;:::warning
cloudflared 只能从 Cloudflare 官方渠道下载。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要从来路不明的镜像站或网盘下载 cloudflared 二进制&amp;lt;/span&amp;gt;——它手里握着你的隧道凭据，又是常驻进程，被人动过手脚等于把源站大门钥匙送出去。
:::&lt;/p&gt;
&lt;h2&gt;全流程实战：建第一条隧道&lt;/h2&gt;
&lt;p&gt;假设我们要发布的服务是源站本机 8080 端口上的一个应用，域名用 &lt;code&gt;app.example.com&lt;/code&gt;（请换成你自己的、已托管在 Cloudflare 的域名）。整个流程五步。&lt;/p&gt;
&lt;h3&gt;第一步：登录授权&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;cloudflared tunnel login
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这条命令会给出一个授权链接（在终端里能直接打开的话会自动拉起浏览器；纯 SSH 环境就把链接复制到本地浏览器打开）。登录你的 Cloudflare 账号后，选择要授权的域名，确认后浏览器会把证书下载回来，命令执行完毕会在 &lt;code&gt;~/.cloudflared/&lt;/code&gt; 目录下生成 &lt;code&gt;cert.pem&lt;/code&gt;。验证一下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ls -l ~/.cloudflared/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;能看到 &lt;code&gt;cert.pem&lt;/code&gt; 就说明授权完成。这个证书是你的&lt;strong&gt;账号级凭据&lt;/strong&gt;，用它可以创建和管理该账号下的隧道，同样按私钥对待。&lt;/p&gt;
&lt;p&gt;无头服务器上浏览器不在同一台机器完全没问题：链接在哪台设备上打开都行，授权结果会通过回调落回执行命令的这台机器。如果命令长时间等不到授权结果，多半是网络到 Cloudflare 的出站不通，先排查出站连通性而不是反复重试。&lt;/p&gt;
&lt;h3&gt;第二步：创建隧道&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;cloudflared tunnel create my-tunnel
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;my-tunnel&lt;/code&gt; 是隧道名，自己起个好认的。命令成功后输出大致如下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Tunnel credentials written to /home/yourname/.cloudflared/3f8a1c2e-xxxx-xxxx-xxxx-xxxxxxxxxxxx.json.
Created tunnel my-tunnel with id 3f8a1c2e-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个信息记好：&lt;strong&gt;隧道 ID&lt;/strong&gt;（那串 UUID）和&lt;strong&gt;凭据文件路径&lt;/strong&gt;（&lt;code&gt;~/.cloudflared/&amp;lt;隧道ID&amp;gt;.json&lt;/code&gt;）。凭据文件是这条隧道独一份的钥匙，下一步写配置要用。随时可以用下面的命令查看已有隧道：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cloudflared tunnel list
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第三步：写配置文件&lt;/h3&gt;
&lt;p&gt;在 &lt;code&gt;~/.cloudflared/config.yml&lt;/code&gt; 写入：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;tunnel: 3f8a1c2e-xxxx-xxxx-xxxx-xxxxxxxxxxxx
credentials-file: /home/yourname/.cloudflared/3f8a1c2e-xxxx-xxxx-xxxx-xxxxxxxxxxxx.json

ingress:
  - hostname: app.example.com
    service: http://localhost:8080
  - service: http_status:404
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐行讲清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;配置项&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;tunnel&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;隧道 ID，指明这个进程跑的是哪条隧道&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;credentials-file&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;凭据 JSON 的&lt;strong&gt;绝对路径&lt;/strong&gt;，写相对路径是常见翻车点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ingress&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;分发规则列表，从上到下依次匹配&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;hostname&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;访客访问的主机名，命中后走这条规则&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;service&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;命中后转发到的本地服务地址&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;最后一条 &lt;code&gt;http_status:404&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;兜底规则：前面全没命中的请求直接由 cloudflared 返回 404&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;service&lt;/code&gt; 不只能写 HTTP 地址，也支持 &lt;code&gt;https://localhost:8443&lt;/code&gt;（回源不校验证书等细节参数以官方文档为准）、&lt;code&gt;tcp://&lt;/code&gt;、&lt;code&gt;ssh://&lt;/code&gt; 等协议，但不同协议的访客侧接入方式差别很大，本篇主线只走最顺的 HTTP 类服务，非 HTTP 的情况在&quot;适用边界&quot;一节说明。&lt;/p&gt;
&lt;h3&gt;第四步：绑定域名&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;cloudflared tunnel route dns my-tunnel app.example.com
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这条命令会在 &lt;code&gt;example.com&lt;/code&gt; 的 DNS 里自动建一条 CNAME 记录：&lt;code&gt;app&lt;/code&gt; 指向 &lt;code&gt;&amp;lt;隧道ID&amp;gt;.cfargotunnel.com&lt;/code&gt; 并开启代理。这一步也可以手动去控制台 DNS 页面加同样的 CNAME，效果一致。注意：如果这个子域名&lt;strong&gt;已经有&lt;/strong&gt; A 记录或其他记录占着，命令会报错，先删掉旧记录再执行；绑完去控制台确认记录存在、CNAME 目标正确。&lt;/p&gt;
&lt;h3&gt;第五步：前台试跑验证&lt;/h3&gt;
&lt;p&gt;先别急着装服务，前台跑一遍看日志最稳妥：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cloudflared tunnel run my-tunnel
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;正常日志里会出现 4 条连接注册成功的记录，形如 &lt;code&gt;Registered tunnel connection&lt;/code&gt;，并标注连接走的协议（quic 或 http2）和边缘位置。这时在浏览器打开 &lt;code&gt;https://app.example.com&lt;/code&gt;，应该直接看到本机 8080 应用的页面。用 &lt;code&gt;curl -I https://app.example.com&lt;/code&gt; 也能验证状态码。确认无误后 &lt;code&gt;Ctrl+C&lt;/code&gt; 停掉，下一节把它变成常驻服务。&lt;/p&gt;
&lt;p&gt;到这一步可以停下来体会一下成果：你的源站没有开任何新端口，&lt;code&gt;app.example.com&lt;/code&gt; 的 DNS 里也没有你的 IP，但服务已经在公网可达了。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;这就是 Tunnel 的核心价值：发布与暴露被彻底解耦。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;一个隧道分发多个服务：ingress 详解&lt;/h2&gt;
&lt;p&gt;一条隧道可以承载同一台机器上的多个服务，靠的就是 ingress 规则按主机名分发。比如同一台机器上还跑着博客（3000 端口）和一个状态面板（9000 端口），配置扩成：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;tunnel: 3f8a1c2e-xxxx-xxxx-xxxx-xxxxxxxxxxxx
credentials-file: /home/yourname/.cloudflared/3f8a1c2e-xxxx-xxxx-xxxx-xxxxxxxxxxxx.json

ingress:
  - hostname: app.example.com
    service: http://localhost:8080
  - hostname: blog.example.com
    service: http://localhost:3000
  - hostname: status.example.com
    service: http://localhost:9000
  - service: http_status:404
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;要点有三条：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;顺序即优先级&lt;/strong&gt;：请求从上往下匹配，第一条命中就走，不再往下看。带 &lt;code&gt;path&lt;/code&gt; 限定的规则（如只匹配某个路径前缀）要放在同主机名的通用规则前面。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;兜底规则必须存在&lt;/strong&gt;：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;ingress 列表最后一条必须是没有任何匹配条件的收尾规则（通常写 http_status:404）&amp;lt;/span&amp;gt;，缺了它配置校验直接不过，隧道起不来。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;每个子域名都要单独绑 DNS&lt;/strong&gt;：新增一个主机名，就多执行一次 &lt;code&gt;cloudflared tunnel route dns my-tunnel blog.example.com&lt;/code&gt;，或者在控制台手动加指向同一个 &lt;code&gt;&amp;lt;隧道ID&amp;gt;.cfargotunnel.com&lt;/code&gt; 的 CNAME。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;改完配置先校验再重启，别拿线上流量试错：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 校验 ingress 配置语法与规则完整性
cloudflared tunnel ingress validate

# 测试某个 URL 实际会命中哪条规则
cloudflared tunnel ingress rule https://blog.example.com/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第二条命令会告诉你这个 URL 命中的是第几条规则、转发到哪个 service，排查&quot;为什么这个域名进错了服务&quot;时非常好用。&lt;/p&gt;
&lt;h2&gt;装成系统服务&lt;/h2&gt;
&lt;p&gt;试跑通过后，把它交给 systemd 常驻：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo cloudflared service install
sudo systemctl status cloudflared
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;service install&lt;/code&gt; 会把当前用户的隧道配置与凭据复制到系统位置（&lt;code&gt;/etc/cloudflared/&lt;/code&gt;），生成 systemd 单元并设为开机自启。注意这意味着服务以 root 身份读取的是 &lt;code&gt;/etc/cloudflared/config.yml&lt;/code&gt; 那份拷贝，&lt;strong&gt;之后你改 &lt;code&gt;~/.cloudflared/config.yml&lt;/code&gt; 不会同步过去&lt;/strong&gt;——改配置后要同步更新系统目录下的那份，再 &lt;code&gt;sudo systemctl restart cloudflared&lt;/code&gt;。这是本地配置型最容易踩的运维坑，记住&quot;运行的那份在 /etc 里&quot;。&lt;/p&gt;
&lt;p&gt;日常运维命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 查看运行状态与最近日志
sudo systemctl status cloudflared
sudo journalctl -u cloudflared -f

# 改完配置后重启
sudo systemctl restart cloudflared

# 确认隧道在线（在账号层面看连接状态）
cloudflared tunnel info my-tunnel
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;tunnel info&lt;/code&gt; 能看到当前有几个 cloudflared 连接器在线、分别连到哪些边缘节点。多机冗余也是基于这个机制：同一条隧道可以在第二台机器上用同一份凭据再跑一个 cloudflared，边缘会自动在多个连接器之间分发，单机宕机不影响服务——但凭据多一份拷贝就多一份泄露风险，权衡着来。&lt;/p&gt;
&lt;h2&gt;适用边界：先把预期放对&lt;/h2&gt;
&lt;p&gt;Tunnel 很好用，但不是万能发布器，边界要先认清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;实际情况&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;HTTP/HTTPS 类服务&lt;/td&gt;
&lt;td&gt;最顺，浏览器直达，本篇主线场景&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;WebSocket&lt;/td&gt;
&lt;td&gt;支持，隧道原生透传&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SSH、TCP 等非 HTTP 协议&lt;/td&gt;
&lt;td&gt;访客侧需配合 Cloudflare Access 或 WARP 客户端，不是浏览器输个域名就能连，配置方式另成一套（以官方文档为准）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;UDP 类服务&lt;/td&gt;
&lt;td&gt;常规隧道不面向公网 UDP 发布，别拿它套游戏/语音服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;性能&lt;/td&gt;
&lt;td&gt;流量绕边缘一跳，延迟取决于机器到边缘的距离；静态资源可叠加边缘缓存抵消&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;稳定性&lt;/td&gt;
&lt;td&gt;依赖源站出站网络与 cloudflared 进程存活，进程要交给 systemd 并开自启&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;费用&lt;/td&gt;
&lt;td&gt;Tunnel 本身免费可用，不按流量另收费（以官方现行政策为准）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一句话总结适用面：&lt;strong&gt;发布 Web 服务是它的主场；要发布任意 TCP/UDP，先想清楚访客侧怎么接入，再决定用不用它。&lt;/strong&gt;&lt;/p&gt;
&lt;h2&gt;与 Nginx 反代的分工&lt;/h2&gt;
&lt;p&gt;已经有公网服务器、Nginx 反代跑得好好的（见 &lt;a href=&quot;/posts/docker-nginx-https/&quot;&gt;Docker 部署 Nginx 反向代理篇&lt;/a&gt;），还要不要 Tunnel？按场景分：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;推荐&lt;/th&gt;
&lt;th&gt;理由&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;公网服务器，源站 IP 暴露无所谓&lt;/td&gt;
&lt;td&gt;继续 Nginx 反代&lt;/td&gt;
&lt;td&gt;链路短、延迟低、不依赖第三方进程&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;公网服务器，但被绕过边缘直打过源站&lt;/td&gt;
&lt;td&gt;Nginx 前面叠 Tunnel&lt;/td&gt;
&lt;td&gt;反代配置不用动，源站关掉 80/443 入站，只留隧道出站&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;机器没有公网 IP（家里宽带、NAT 后）&lt;/td&gt;
&lt;td&gt;Tunnel&lt;/td&gt;
&lt;td&gt;传统反代根本无从发布，隧道是少数可行解&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;临时给人演示内网服务&lt;/td&gt;
&lt;td&gt;Tunnel（或一次性快速隧道）&lt;/td&gt;
&lt;td&gt;不用改防火墙、不用备案域名解析折腾&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;对延迟极度敏感的接口&lt;/td&gt;
&lt;td&gt;Nginx 直连&lt;/td&gt;
&lt;td&gt;少一跳是一跳&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;两者叠用的姿势很常见：cloudflared 的 ingress 直接指向本机 Nginx 的端口，Nginx 继续管它的虚拟主机、限流和静态文件，Tunnel 只负责&quot;把流量安全地送进来&quot;。这时源站防火墙把 80/443 的入站全关掉，Nginx 只听本机回环或只接受 cloudflared 的转发，边缘防护再也绕不过去。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;h3&gt;1033：Cloudflare Tunnel error&lt;/h3&gt;
&lt;p&gt;浏览器报 1033，意思是边缘找不到这条隧道的在线连接。九成是 &lt;strong&gt;cloudflared 没在运行&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl status cloudflared
sudo journalctl -u cloudflared -n 50
cloudflared tunnel info my-tunnel
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;进程不在就先拉起来；进程在但 info 显示无连接，查源站出站网络（到 Cloudflare 边缘的连接被防火墙出站规则或代理干扰最常见）。&lt;/p&gt;
&lt;h3&gt;502 Bad Gateway&lt;/h3&gt;
&lt;p&gt;边缘或 cloudflared 返回 502，通常是&lt;strong&gt;隧道通了、但最后一米没通&lt;/strong&gt;：本地服务没起、端口写错、或者服务只监听了某个网卡而 ingress 写的是 localhost 对不上。在源站本机直接验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -v http://localhost:8080
ss -tlnp | grep 8080
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;本机 curl 不通就先修应用本身，别在隧道上瞎折腾。&lt;/p&gt;
&lt;h3&gt;ingress 不匹配：域名进了错的服务或吃 404&lt;/h3&gt;
&lt;p&gt;先跑 &lt;code&gt;cloudflared tunnel ingress validate&lt;/code&gt; 排除语法与兜底缺失，再用 &lt;code&gt;cloudflared tunnel ingress rule &amp;lt;出问题的URL&amp;gt;&lt;/code&gt; 看实际命中哪条。常见原因：规则顺序写反（通用规则把细分规则挡在前面）、主机名拼写和 DNS 绑定的不一致、改的是家目录配置而服务跑的是 &lt;code&gt;/etc/cloudflared/&lt;/code&gt; 那份。&lt;/p&gt;
&lt;h3&gt;服务正常但域名打不开/解析不生效&lt;/h3&gt;
&lt;p&gt;按链路顺序查：控制台 DNS 里确认 CNAME 存在且指向 &lt;code&gt;&amp;lt;隧道ID&amp;gt;.cfargotunnel.com&lt;/code&gt;；&lt;code&gt;dig app.example.com&lt;/code&gt; 看解析结果是否为 Cloudflare 的地址段；刚绑定的记录等一两分钟再试，别在生效窗口里反复改配置。如果这个子域名之前有其他记录，先确认旧记录已删除——同名记录冲突时 route dns 会失败，页面上也会互相打架。&lt;/p&gt;
&lt;h3&gt;改完配置重启不生效&lt;/h3&gt;
&lt;p&gt;十有八九是改错了文件：服务化之后生效的是 &lt;code&gt;/etc/cloudflared/config.yml&lt;/code&gt;。把新配置同步过去再 &lt;code&gt;systemctl restart cloudflared&lt;/code&gt;，并用 &lt;code&gt;journalctl -u cloudflared&lt;/code&gt; 看重启后的连接注册日志确认。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;传统反代发布的暴露面在源站 IP：IP 一泄露，边缘防护可被整体绕过；Tunnel 用&quot;源站主动外连&quot;的架构把这个面从根上消掉。&lt;/li&gt;
&lt;li&gt;cloudflared 维持 4 条长连接，DNS 里只有指向 cfargotunnel.com 的 CNAME，源站零入站端口、IP 不公开。&lt;/li&gt;
&lt;li&gt;本地配置型的完整链路是：&lt;code&gt;tunnel login&lt;/code&gt; 授权 → &lt;code&gt;tunnel create&lt;/code&gt; 拿凭据 → 写 &lt;code&gt;config.yml&lt;/code&gt; 的 ingress → &lt;code&gt;tunnel route dns&lt;/code&gt; 绑域名 → 前台试跑 → &lt;code&gt;service install&lt;/code&gt; 交给 systemd。&lt;/li&gt;
&lt;li&gt;ingress 从上往下匹配，最后一条必须是无条件兜底规则；多服务靠多主机名规则加多条 DNS 绑定扩展。&lt;/li&gt;
&lt;li&gt;服务化后真正生效的配置在 &lt;code&gt;/etc/cloudflared/&lt;/code&gt;，改配置别改错地方。&lt;/li&gt;
&lt;li&gt;选型上：无公网 IP、怕源站被直打，用 Tunnel；链路越短越好的公网服务，Nginx 反代依然是正解，两者也可以叠用。&lt;/li&gt;
&lt;li&gt;凭据 JSON 和 cert.pem 是整套体系的钥匙，按私钥级别保管。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>Turnstile：给表单加无感人机验证</title><link>https://www.anexns.cloudns.org/posts/cloudflare-turnstile/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-turnstile/</guid><description>挡机器人不折磨真人：Turnstile 的前端组件嵌入与后端 siteverify 校验全流程、三种小部件模式的区别、测试密钥的用法，以及最常见的几个接入坑。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;上一篇聊了域名转入 Cloudflare 的省钱门道，省钱之外，Cloudflare 还有一件更实用的免费武器没动过：Turnstile。这一篇把它接进你自己的网站——从控制台建站点、拿密钥，到前端嵌组件、后端调 siteverify 校验，一条龙走完，最后再把接入时最容易踩的几个坑逐个拆掉。&lt;/p&gt;
&lt;p&gt;先说清楚它解决什么问题。只要你的网站有一个能提交东西的入口——注册、登录、留言、评论、找回密码、领券、调接口——机器人就会找上门。它们不是来参观的，是来批量干活的：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;注册机&lt;/strong&gt;：一夜之间给你灌几万个僵尸账号，数据库里全是垃圾，后续清理比接入验证麻烦十倍；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;撞库与爆破&lt;/strong&gt;：拿着泄露的账号密码库往你的登录口上撞，或者对着弱口令一个个试；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;灌水与刷量&lt;/strong&gt;：留言区、评论区被广告和垃圾链接淹没，人工审核根本审不过来；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;薅接口&lt;/strong&gt;：短信验证码接口、优惠券接口、免费额度接口，被脚本当成免费资源往死里薅，薅走的都是真金白银。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这些流量的共同点是：量大、重复、不创造任何价值，还实打实地消耗你的服务器资源和第三方接口费用。人机验证就是在提交入口加一道判断题：&lt;strong&gt;你到底是人，还是脚本？&lt;/strong&gt;&lt;/p&gt;
&lt;h2&gt;传统验证码为什么惹人烦&lt;/h2&gt;
&lt;p&gt;最早的办法是扭曲字符图片，让用户把图里的字母敲出来。机器人 OCR 水平水涨船高，字符就扭得越来越离谱，最后变成了人看不清、机器反而看得清的笑话。&lt;/p&gt;
&lt;p&gt;后来流行的是行为勾选加图片挑战：先勾一个「我不是机器人」，运气不好就开始选图——「请选出所有包含红绿灯的图片」「请选出所有公交车」。一格选错，推倒重来。跨海象、消防栓、自行车这类题对不熟悉当地街景的用户尤其不友好，选到第三轮还在怀疑人生。&lt;/p&gt;
&lt;p&gt;体验差只是表面问题，更深一层的是代价：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;问题&lt;/th&gt;
&lt;th&gt;具体表现&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;用户流失&lt;/td&gt;
&lt;td&gt;每多一道图片挑战，注册和下单的完成率就掉一截，移动端掉得更狠&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;无障碍缺失&lt;/td&gt;
&lt;td&gt;视障用户靠读屏根本没法完成图片题，直接被挡在门外&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;隐私代价&lt;/td&gt;
&lt;td&gt;主流验证码靠在全网埋点收集行为数据来判断风险，你的用户数据成了它的养料&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;对抗军备竞赛&lt;/td&gt;
&lt;td&gt;打码平台几分钱一张图人工代答，验证强度被迫越加越高，真人越来越难过&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;验证的理想状态是：真人无感通过，机器人过不去，而不是把所有人拉去做题。&amp;lt;/span&amp;gt;Turnstile 就是奔着这个目标设计的。&lt;/p&gt;
&lt;h2&gt;Turnstile 的不同之处&lt;/h2&gt;
&lt;p&gt;Turnstile 是 Cloudflare 推出的人机验证服务，2022 年发布，后来转为正式免费提供。它的工作方式和传统验证码完全不同：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;多数真人无感通过&lt;/strong&gt;：小部件在页面上运行时，会在浏览器里跑一系列非交互式的检测——浏览器环境特征、行为信号、硬件与网络侧的若干挑战（比如工作量证明类的小计算），综合判断这次访问像不像真人。判断通过，直接发令牌，用户最多看到一个转瞬即逝的勾，全程不用点任何图片。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;不靠出题&lt;/strong&gt;：没有选红绿灯，没有拼图滑块。只有当信号明显可疑时，托管模式下才可能弹出一个需要点一下的复选框，连这一步都远比图片题轻。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;不拿用户数据做广告追踪&lt;/strong&gt;：Cloudflare 对 Turnstile 的定位说得很明确——它不为了广告目的收集和留存访客数据，这也是很多站点从 reCAPTCHA 迁移过来的直接原因。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;免费且不限量&lt;/strong&gt;：Turnstile 本身免费，调用量没有像样的门槛，对个人站点和小项目非常友好。具体配额与条款以官方文档为准。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;当然，它不是银弹。Turnstile 挡的是自动化脚本和低成本批量行为，挡不住真人肉身操作的水军，也挡不住专门针对它做逆向的高成本攻击。但把门槛从「零」抬到「要专门花钱花时间绕过」，就已经能过滤掉绝大多数 opportunistic 的垃圾流量了。&lt;/p&gt;
&lt;p&gt;:::warning
人机验证只是入口防线的一层，不能替代后端的限流、风控和业务校验。登录口该有的失败次数限制照样要有，接口该有的权限检查一点都不能省。
:::&lt;/p&gt;
&lt;h2&gt;准备工作：建站点，拿两把钥匙&lt;/h2&gt;
&lt;p&gt;接入 Turnstile 不用写一行代码就能开始，全部在 Cloudflare 控制台完成：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;登录 Cloudflare 控制台，左侧进入 &lt;strong&gt;Turnstile&lt;/strong&gt; 页面；&lt;/li&gt;
&lt;li&gt;点 &lt;strong&gt;Add widget&lt;/strong&gt;（添加小部件），填一个好认的名字，比如站点名加用途，如 &lt;code&gt;blog-login&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;在 &lt;strong&gt;Hostname management&lt;/strong&gt;（域名清单）里填入要使用验证的域名，支持添加多个，子域名按需逐个加；&lt;/li&gt;
&lt;li&gt;选择小部件模式（下一节细讲，先选默认的 Managed 即可）；&lt;/li&gt;
&lt;li&gt;创建完成后，控制台会给出两把钥匙：&lt;strong&gt;Site Key&lt;/strong&gt;（站点密钥）和 &lt;strong&gt;Secret Key&lt;/strong&gt;（秘密密钥）。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;一个域名可以建多个小部件，建议一个用途一个：登录一个、注册一个、留言一个。这样将来某个入口要单独换模式、看统计、轮换密钥时互不牵连。&lt;/p&gt;
&lt;p&gt;两把钥匙的性质完全不同，这是整个接入里最重要的安全常识：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;钥匙&lt;/th&gt;
&lt;th&gt;出现位置&lt;/th&gt;
&lt;th&gt;公开性&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Site Key&lt;/td&gt;
&lt;td&gt;前端页面 HTML / JavaScript 里&lt;/td&gt;
&lt;td&gt;可以公开，本来就是给浏览器看的&lt;/td&gt;
&lt;td&gt;标识「这是哪个站点的验证」，用来渲染小部件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Secret Key&lt;/td&gt;
&lt;td&gt;只存在于你的后端服务器&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不能出现在前端、不能写进代码仓库、不能打进日志&amp;lt;/span&amp;gt;&lt;/td&gt;
&lt;td&gt;后端向 Cloudflare 校验令牌真伪时证明身份&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Secret Key 一旦泄露，任何人都能拿它调用校验接口，你的验证等于被人握住了后门钥匙。&amp;lt;/span&amp;gt;正确做法是把它放在服务器的环境变量或密钥管理里，和数据库密码同级对待。真泄露了也别慌，控制台里可以重新生成（roll），换掉之后旧的立刻失效。&lt;/p&gt;
&lt;h2&gt;三种小部件模式怎么选&lt;/h2&gt;
&lt;p&gt;创建小部件时要选模式，这是 Turnstile 和老式验证码在体验上拉开差距的关键设置：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;模式&lt;/th&gt;
&lt;th&gt;用户看到什么&lt;/th&gt;
&lt;th&gt;何时可能交互&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Managed（托管）&lt;/td&gt;
&lt;td&gt;一个带 Cloudflare 标识的小部件框&lt;/td&gt;
&lt;td&gt;Cloudflare 判断风险高时，框里出现需要勾选的复选框；低风险直接打勾通过&lt;/td&gt;
&lt;td&gt;绝大多数表单，官方推荐的默认选择&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Non-interactive（非交互）&lt;/td&gt;
&lt;td&gt;一个小部件框，全程只展示状态&lt;/td&gt;
&lt;td&gt;永不要求用户操作，验证不过就直接失败&lt;/td&gt;
&lt;td&gt;不希望任何交互打断流程、且能接受少量误杀的场景&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Invisible（隐形）&lt;/td&gt;
&lt;td&gt;什么都看不到，没有任何可见元素&lt;/td&gt;
&lt;td&gt;永不要求用户操作，在后台默默执行&lt;/td&gt;
&lt;td&gt;对页面美观和流程完整性要求极高的关键转化页&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选型的经验法则：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;拿不准就用 Managed&lt;/strong&gt;。它在「通过率」和「拦截率」之间自动权衡，低风险用户无感、高风险用户多点一下，是绝大多数站点的最优解。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Non-interactive 适合内部或低风险入口&lt;/strong&gt;，比如站内搜索、订阅邮箱提交。它绝不打扰用户，代价是判定更保守，个别环境特殊的真人可能直接失败，要有兜底提示。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Invisible 适合注册、下单这类寸土寸金的转化页&lt;/strong&gt;，页面上干干净净，但因为完全没有可见元素，排查问题和向用户解释「为什么提交失败」会更麻烦一些。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;三种模式的后端校验流程完全一致，切换模式只是改小部件设置或前端渲染参数，不影响后端代码。&lt;/p&gt;
&lt;h2&gt;前端接入：把小部件嵌进表单&lt;/h2&gt;
&lt;p&gt;前端要做两件事：引入官方脚本，再在表单里放一个小部件容器。&lt;/p&gt;
&lt;p&gt;官方脚本的地址是现行固定口径：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;script src=&quot;https://challenges.cloudflare.com/turnstile/v0/api.js&quot; async defer&amp;gt;&amp;lt;/script&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意脚本域名是 &lt;code&gt;challenges.cloudflare.com&lt;/code&gt;，如果你的站点配了严格的 CSP（Content Security Policy），需要把这个域名加进 &lt;code&gt;script-src&lt;/code&gt; 和 &lt;code&gt;frame-src&lt;/code&gt; 的白名单，否则小部件会被浏览器拦下来，后面排障一节还会提到。&lt;/p&gt;
&lt;p&gt;最简的隐式渲染写法，是在表单里加一个带 &lt;code&gt;cf-turnstile&lt;/code&gt; 类名的容器，把 Site Key 写进 &lt;code&gt;data-sitekey&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;form action=&quot;/login&quot; method=&quot;POST&quot;&amp;gt;
  &amp;lt;input type=&quot;text&quot; name=&quot;username&quot; placeholder=&quot;用户名&quot; /&amp;gt;
  &amp;lt;input type=&quot;password&quot; name=&quot;password&quot; placeholder=&quot;密码&quot; /&amp;gt;

  &amp;lt;!-- Turnstile 小部件容器 --&amp;gt;
  &amp;lt;div class=&quot;cf-turnstile&quot; data-sitekey=&quot;你的SiteKey&quot;&amp;gt;&amp;lt;/div&amp;gt;

  &amp;lt;button type=&quot;submit&quot;&amp;gt;登录&amp;lt;/button&amp;gt;
&amp;lt;/form&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;脚本加载后会自动扫描这类容器并渲染小部件。验证通过时，小部件会在表单里悄悄塞入一个隐藏字段，字段名是固定的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cf-turnstile-response
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;用户点提交时，这个字段的值——也就是&lt;strong&gt;令牌（token）&lt;/strong&gt;——会随着表单其他字段一起发到你的后端。后端什么都不用猜，取这个字段就行。&lt;/p&gt;
&lt;p&gt;几个必须知道的令牌性质：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;有效期约 5 分钟（300 秒）&lt;/strong&gt;：令牌生成后要尽快随表单提交，用户在页面上磨蹭太久，令牌过期，校验必然失败；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;只能使用一次&lt;/strong&gt;：同一个令牌拿去校验第二次，会返回已使用过的错误。这意味着表单校验失败让用户「改个字段重新提交」时，必须刷新令牌，不能复用旧的；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;令牌长度上限 2048 字符&lt;/strong&gt;：后端接收字段时别给它设太短的长度限制。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;如果表单是单页应用里动态出现的（比如点按钮才弹出的登录框），隐式渲染扫不到后出现的新容器，这时用显式渲染：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;script src=&quot;https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit&quot; async defer&amp;gt;&amp;lt;/script&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;// 在容器元素出现之后手动渲染
const widgetId = turnstile.render(&apos;#turnstile-box&apos;, {
  sitekey: &apos;你的SiteKey&apos;,
  callback: function (token) {
    // 验证通过，token 就在这里，也可以等提交时从隐藏字段取
    console.log(&apos;验证通过&apos;);
  },
  &apos;expired-callback&apos;: function () {
    // 令牌过期时触发，提示用户或自动重置
    turnstile.reset(widgetId);
  },
  &apos;error-callback&apos;: function () {
    // 小部件本身出错时触发
    console.log(&apos;验证组件加载失败&apos;);
  },
});
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;常用回调有三个：&lt;code&gt;callback&lt;/code&gt; 是通过时触发，&lt;code&gt;expired-callback&lt;/code&gt; 是令牌过期时触发，&lt;code&gt;error-callback&lt;/code&gt; 是组件出错时触发。提交失败需要让用户重试时，调用 &lt;code&gt;turnstile.reset(widgetId)&lt;/code&gt; 把小部件重置、生成新令牌，这是处理「令牌只能用一次」最稳妥的姿势。&lt;/p&gt;
&lt;p&gt;小部件还支持一批 &lt;code&gt;data-&lt;/code&gt; 配置，隐式渲染时直接写在容器上：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;属性&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;常用取值&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;data-sitekey&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Site Key，必填&lt;/td&gt;
&lt;td&gt;控制台给的那串&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;data-theme&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;外观主题&lt;/td&gt;
&lt;td&gt;&lt;code&gt;auto&lt;/code&gt; / &lt;code&gt;light&lt;/code&gt; / &lt;code&gt;dark&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;data-size&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;尺寸&lt;/td&gt;
&lt;td&gt;&lt;code&gt;normal&lt;/code&gt; / &lt;code&gt;compact&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;data-action&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;自定义动作标签，校验结果里会带回&lt;/td&gt;
&lt;td&gt;如 &lt;code&gt;login&lt;/code&gt;、&lt;code&gt;register&lt;/code&gt;，便于后端区分来源&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;data-cdata&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;自定义数据，校验结果里原样带回&lt;/td&gt;
&lt;td&gt;业务侧的关联 ID 等&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;深色主题的站点记得把 &lt;code&gt;data-theme&lt;/code&gt; 设成 &lt;code&gt;dark&lt;/code&gt; 或 &lt;code&gt;auto&lt;/code&gt;，不然白色小部件框在深色页面上会非常扎眼。&lt;/p&gt;
&lt;h2&gt;后端校验：siteverify 这一关不能省&lt;/h2&gt;
&lt;p&gt;前端小部件只是「出题和收卷」，真正的判卷在后端。&lt;strong&gt;只嵌前端、不做后端校验，等于装了道没有锁的门&lt;/strong&gt;——机器人完全可以跳过浏览器，直接构造请求打你的接口，连小部件都不用看。&lt;/p&gt;
&lt;p&gt;校验端点是现行固定口径：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;POST https://challenges.cloudflare.com/turnstile/v0/siteverify
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;请求体带三个参数，后端拿到表单后立刻调用：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;必填&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;secret&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;是&lt;/td&gt;
&lt;td&gt;你的 Secret Key，只在后端出现&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;response&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;是&lt;/td&gt;
&lt;td&gt;表单里 &lt;code&gt;cf-turnstile-response&lt;/code&gt; 字段的值&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;remoteip&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;否，但强烈建议带&lt;/td&gt;
&lt;td&gt;提交者的真实 IP，能显著提升判定准确性&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;以 Node.js 为例，用表单编码提交：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;async function verifyTurnstile(token, ip) {
  const formData = new URLSearchParams();
  formData.append(&apos;secret&apos;, process.env.TURNSTILE_SECRET_KEY);
  formData.append(&apos;response&apos;, token);
  if (ip) formData.append(&apos;remoteip&apos;, ip);

  const res = await fetch(
    &apos;https://challenges.cloudflare.com/turnstile/v0/siteverify&apos;,
    { method: &apos;POST&apos;, body: formData }
  );
  const data = await res.json();
  return data;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回的 JSON 长这样，核心就看 &lt;code&gt;success&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;success&quot;: true,
  &quot;challenge_ts&quot;: &quot;2026-11-15T01:23:45.678Z&quot;,
  &quot;hostname&quot;: &quot;example.com&quot;,
  &quot;error-codes&quot;: [],
  &quot;action&quot;: &quot;login&quot;,
  &quot;cdata&quot;: &quot;&quot;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;各字段的含义：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;success&lt;/code&gt;：校验是否通过，&lt;code&gt;true&lt;/code&gt; 才放行，这是唯一的放行依据；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;challenge_ts&lt;/code&gt;：这次验证完成的时间戳；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;hostname&lt;/code&gt;：令牌是在哪个域名上生成的，&lt;strong&gt;建议后端核对它等于你预期的域名&lt;/strong&gt;，防止有人拿别的站点（甚至他自己站点）的令牌来你这儿复用；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;action&lt;/code&gt; / &lt;code&gt;cdata&lt;/code&gt;：前端设置了 &lt;code&gt;data-action&lt;/code&gt; / &lt;code&gt;data-cdata&lt;/code&gt; 时原样带回，可用来核对「这个令牌确实是登录表单发的，不是留言表单发的」；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;error-codes&lt;/code&gt;：失败时给出的原因码，排障全靠它。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;常见错误码对照：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;错误码&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;missing-input-secret&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;没传 secret 参数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;invalid-input-secret&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;secret 不对，最常见是把 Site Key 当 Secret Key 用了&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;missing-input-response&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;没传令牌&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;invalid-input-response&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;令牌无效、格式不对或已过期&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;timeout-or-duplicate&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;令牌超时，或已经被校验过一次（重复提交）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;bad-request&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;请求本身格式错误&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;internal-error&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Cloudflare 侧内部错误，可重试&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;校验环节有两条纪律：&lt;/p&gt;
&lt;p&gt;第一，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;code&gt;success&lt;/code&gt; 不为 &lt;code&gt;true&lt;/code&gt;，就坚决拒绝这次提交，没有例外通道。&amp;lt;/span&amp;gt;不要写「校验没过但看起来像正常用户就先放行」这种代码，机器人第一个找到的就是这种后门。&lt;/p&gt;
&lt;p&gt;第二，要想清楚&lt;strong&gt;校验请求本身失败时怎么办&lt;/strong&gt;。如果你的服务器到 Cloudflare 的网络断了、siteverify 超时了，这时候是拒绝所有提交（fail-closed，安全优先，可能误伤全部真人），还是先放行并记录日志（fail-open，可用性优先，短暂失去防护）？没有标准答案：登录、支付类入口建议 fail-closed 并给用户明确报错；留言、订阅这类低风险入口可以 fail-open 加事后风控。这个权衡必须在写代码时主动做，而不是等出事了才发现默认行为不是你想要的。&lt;/p&gt;
&lt;h2&gt;一个完整小例子：留言表单全闭环&lt;/h2&gt;
&lt;p&gt;把前后端拼起来，一个最小可用的留言板是这样的。前端：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;!DOCTYPE html&amp;gt;
&amp;lt;html lang=&quot;zh-CN&quot;&amp;gt;
&amp;lt;head&amp;gt;
  &amp;lt;meta charset=&quot;UTF-8&quot; /&amp;gt;
  &amp;lt;title&amp;gt;留言板&amp;lt;/title&amp;gt;
  &amp;lt;script src=&quot;https://challenges.cloudflare.com/turnstile/v0/api.js&quot; async defer&amp;gt;&amp;lt;/script&amp;gt;
&amp;lt;/head&amp;gt;
&amp;lt;body&amp;gt;
  &amp;lt;form id=&quot;comment-form&quot; action=&quot;/api/comments&quot; method=&quot;POST&quot;&amp;gt;
    &amp;lt;input type=&quot;text&quot; name=&quot;nickname&quot; placeholder=&quot;昵称&quot; required /&amp;gt;
    &amp;lt;textarea name=&quot;content&quot; placeholder=&quot;说点什么…&quot; required&amp;gt;&amp;lt;/textarea&amp;gt;

    &amp;lt;div class=&quot;cf-turnstile&quot;
         data-sitekey=&quot;你的SiteKey&quot;
         data-action=&quot;comment&quot;
         data-theme=&quot;auto&quot;&amp;gt;&amp;lt;/div&amp;gt;

    &amp;lt;button type=&quot;submit&quot;&amp;gt;提交留言&amp;lt;/button&amp;gt;
  &amp;lt;/form&amp;gt;
&amp;lt;/body&amp;gt;
&amp;lt;/html&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;后端（Node.js + Express，逻辑部分抽出来，任何语言都是同样的三步）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;app.post(&apos;/api/comments&apos;, async (req, res) =&amp;gt; {
  const token = req.body[&apos;cf-turnstile-response&apos;];
  const ip = req.ip;

  // 第一步：令牌字段根本不存在，直接拒绝
  if (!token) {
    return res.status(400).json({ ok: false, msg: &apos;缺少人机验证信息&apos; });
  }

  // 第二步：调 siteverify 校验
  let verify;
  try {
    const formData = new URLSearchParams();
    formData.append(&apos;secret&apos;, process.env.TURNSTILE_SECRET_KEY);
    formData.append(&apos;response&apos;, token);
    if (ip) formData.append(&apos;remoteip&apos;, ip);

    const resp = await fetch(
      &apos;https://challenges.cloudflare.com/turnstile/v0/siteverify&apos;,
      { method: &apos;POST&apos;, body: formData }
    );
    verify = await resp.json();
  } catch (e) {
    // 校验服务不可达：低风险留言入口选择放行并记录，登录类入口应改为拒绝
    console.error(&apos;Turnstile 校验请求失败&apos;, e);
    verify = { success: true, degraded: true };
  }

  // 第三步：校验不过或域名对不上，拒绝提交
  if (!verify.success || verify.hostname !== &apos;example.com&apos;) {
    return res.status(403).json({ ok: false, msg: &apos;人机验证未通过，请刷新页面重试&apos; });
  }

  // 校验通过，才真正处理业务
  const { nickname, content } = req.body;
  await saveComment({ nickname, content, ip });
  return res.json({ ok: true, msg: &apos;留言已提交&apos; });
});
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这个闭环里把前面讲的点都用上了：令牌从固定字段取、secret 从环境变量读、带上 &lt;code&gt;remoteip&lt;/code&gt;、核对 &lt;code&gt;hostname&lt;/code&gt;、校验不过坚决拒绝、校验服务异常时按业务风险做了明确策略。换成 PHP、Python、Go 也只是换个发 HTTP 请求的写法，参数和判断逻辑一字不用改。&lt;/p&gt;
&lt;h2&gt;测试密钥：本地调试别拿生产钥匙硬扛&lt;/h2&gt;
&lt;p&gt;开发阶段有个高频痛点：本地用 &lt;code&gt;localhost&lt;/code&gt; 调试，域名不在小部件的域名清单里，小部件压根不渲染。Cloudflare 官方提供了一整套&lt;strong&gt;测试专用密钥&lt;/strong&gt;解决这个问题，它们的行为是写死的、完全可预测：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;密钥&lt;/th&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;th&gt;行为&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;测试 Site Key（以 &lt;code&gt;1x0000&lt;/code&gt; 开头那把）&lt;/td&gt;
&lt;td&gt;前端渲染&lt;/td&gt;
&lt;td&gt;永远显示为验证通过&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;测试 Site Key（以 &lt;code&gt;2x0000&lt;/code&gt; 开头那把）&lt;/td&gt;
&lt;td&gt;前端渲染&lt;/td&gt;
&lt;td&gt;永远显示为验证失败&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;测试 Site Key（以 &lt;code&gt;3x0000&lt;/code&gt; 开头那把）&lt;/td&gt;
&lt;td&gt;前端渲染&lt;/td&gt;
&lt;td&gt;永远强制弹出交互质询&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;测试 Secret Key（以 &lt;code&gt;1x0000&lt;/code&gt; 开头那把）&lt;/td&gt;
&lt;td&gt;后端校验&lt;/td&gt;
&lt;td&gt;siteverify 永远返回 &lt;code&gt;success: true&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;测试 Secret Key（以 &lt;code&gt;2x0000&lt;/code&gt; 开头那把）&lt;/td&gt;
&lt;td&gt;后端校验&lt;/td&gt;
&lt;td&gt;siteverify 永远返回 &lt;code&gt;success: false&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;测试 Secret Key（以 &lt;code&gt;3x0000&lt;/code&gt; 开头那把）&lt;/td&gt;
&lt;td&gt;后端校验&lt;/td&gt;
&lt;td&gt;永远返回 &lt;code&gt;timeout-or-duplicate&lt;/code&gt; 错误&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;具体的完整密钥字符串以官方文档为准，写代码时从文档里复制，别凭记忆手敲。用测试密钥时，令牌字段的值是固定的 &lt;code&gt;XXXX.DUMMY.TOKEN.XXXX&lt;/code&gt;，不依赖真实的 Cloudflare 交互，断网环境都能调通前后端逻辑。&lt;/p&gt;
&lt;p&gt;使用纪律就一条：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;测试密钥只能出现在本地和测试环境，绝不能带上生产。&amp;lt;/span&amp;gt;生产环境如果误用了「永远通过」的测试 Secret Key，你的验证就是敞开的摆设，而且从界面上完全看不出来——用户能正常提交、日志里全是 success，直到垃圾流量灌进来才发现。上线检查清单里务必加一项：确认环境变量里是生产密钥。&lt;/p&gt;
&lt;p&gt;另外，正式密钥也可以在本地用：把 &lt;code&gt;localhost&lt;/code&gt; 加进小部件的域名清单即可（官方明确支持 localhost 调试）。两种方式任选其一，测试密钥胜在能稳定复现失败、超时等各种边界情况，写自动化测试时尤其顺手。&lt;/p&gt;
&lt;h2&gt;排障：接入最常见的几个坑&lt;/h2&gt;
&lt;h3&gt;小部件不显示，一片空白&lt;/h3&gt;
&lt;p&gt;按这个顺序查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;域名没加进清单&lt;/strong&gt;：打开页面域名和小部件 Hostname 清单逐字对照，&lt;code&gt;www.example.com&lt;/code&gt; 和 &lt;code&gt;example.com&lt;/code&gt; 是两个条目，别想当然；本地调试则确认清单里有 &lt;code&gt;localhost&lt;/code&gt; 或改用测试 Site Key。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;脚本被拦截&lt;/strong&gt;：浏览器控制台看有没有 &lt;code&gt;challenges.cloudflare.com&lt;/code&gt; 的请求报错；站点有 CSP 就把该域名加进 &lt;code&gt;script-src&lt;/code&gt; 与 &lt;code&gt;frame-src&lt;/code&gt;；某些广告拦截插件也会误伤验证脚本，可以无痕窗口复测排除。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;脚本加载方式冲突&lt;/strong&gt;：用了显式渲染参数 &lt;code&gt;?render=explicit&lt;/code&gt; 却没调 &lt;code&gt;turnstile.render()&lt;/code&gt;，小部件永远不会出现；反过来，隐式渲染时容器要在脚本执行前存在于 DOM 中。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Site Key 写错&lt;/strong&gt;：多一位少一位都会渲染失败，控制台通常有明确报错，从控制台重新复制一遍。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;用户反馈一直验证失败或转圈&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;令牌过期&lt;/strong&gt;：用户打开页面挂了十分钟才提交，令牌早过了 5 分钟有效期。解法是监听 &lt;code&gt;expired-callback&lt;/code&gt; 自动 &lt;code&gt;reset&lt;/code&gt; 刷新，或在点提交前检查并刷新。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;令牌被重复提交&lt;/strong&gt;：表单校验失败后原地重提、或者前端做了自动重试，第二次提交带着已用过的令牌，返回 &lt;code&gt;timeout-or-duplicate&lt;/code&gt;。每次提交失败都要重置小部件拿新令牌。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;系统时钟不准&lt;/strong&gt;：用户设备时间偏差过大可能影响验证过程，报错话术里可以提示检查系统时间，这是小概率但真实存在的原因。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;网络环境特殊&lt;/strong&gt;：极少数网络下到 Cloudflare 挑战域名的连通性有问题，真人会卡住。给失败提示留一个「重试」入口，实在过不去的用户要有人工兜底通道。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;后端校验总是返回 invalid&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;两把钥匙用混了&lt;/strong&gt;：最高频的错误，没有之一。&lt;code&gt;invalid-input-secret&lt;/code&gt; 基本就是 secret 传错——把 Site Key 填进了 secret，或者把 A 小部件的 Secret 用到了 B 小部件的令牌上。密钥是按小部件成对的，逐个核对。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;令牌字段取错&lt;/strong&gt;：后端取的字段名不是 &lt;code&gt;cf-turnstile-response&lt;/code&gt;，或者前端表单根本没把隐藏字段带上（比如用 JavaScript 手动拼请求体时漏了它）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;重复校验&lt;/strong&gt;：同一个请求被中间件和业务代码各校验了一次，第二次必然 &lt;code&gt;timeout-or-duplicate&lt;/code&gt;。全站只保留一个校验入口。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;secret 里混入空格或引号&lt;/strong&gt;：环境变量从控制台复制时带了首尾空白，在配置里肉眼很难看出来，打印长度或做一次 trim 就能定位。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
排障时最有效的动作是把 siteverify 的完整返回 JSON 打进日志（error-codes 尤其要留），九成问题看错误码就能定位。唯独注意：日志里可以记令牌的前几位用于关联，但不要记 Secret Key 本身。
:::&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Turnstile 的核心价值是&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;让验证对真人隐形、对机器人收费&amp;lt;/span&amp;gt;：不用做题、不用交隐私数据、服务本身免费；&lt;/li&gt;
&lt;li&gt;接入是前后端两半活：前端引入 &lt;code&gt;api.js&lt;/code&gt; 并渲染小部件拿到令牌，后端调 siteverify 校验，&lt;strong&gt;缺了后端校验等于没接&lt;/strong&gt;；&lt;/li&gt;
&lt;li&gt;两把钥匙分工明确：Site Key 放前端随便看，Secret Key 只进后端环境变量，泄露就立刻重新生成；&lt;/li&gt;
&lt;li&gt;模式选择默认 Managed，转化关键页可用 Invisible，只求零打扰可用 Non-interactive；&lt;/li&gt;
&lt;li&gt;令牌的两个脾气要记牢：约 5 分钟过期、只能用一次，重试流程必须设计成自动刷新令牌；&lt;/li&gt;
&lt;li&gt;测试密钥是本地调试和自动化测试的好帮手，但上线前必须确认生产环境用的是真密钥。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;下一篇进入 Cloudflare Registrar：把域名转进来，按批发价续费，能省则省。&lt;/p&gt;
</content:encoded></item><item><title>WAF 与安全规则实战</title><link>https://www.anexns.cloudns.org/posts/cloudflare-waf-security/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-waf-security/</guid><description>把不怀好意的流量挡在源站之外：WAF 自定义规则的表达式与动作、速率限制、Bot 对抗、IP 与地区封锁的写法，以及规则顺序与误伤正常用户时的排查方法。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;源站一上公网，扫描器、爆破脚本和爬虫大军就没停过。看一眼源站的访问日志就知道：找 &lt;code&gt;.env&lt;/code&gt; 的、试 &lt;code&gt;/.git/config&lt;/code&gt; 的、往登录接口撞密码的，一天几千条起步。这些流量如果全靠源站自己扛，不仅浪费带宽和 CPU，更麻烦的是只要有一条防线漏了，事情就大条。&lt;/p&gt;
&lt;p&gt;本篇的主线是把拦截尽量往前推：&lt;strong&gt;在 Cloudflare 边缘先挡掉一层，剩下的再交给源站防火墙&lt;/strong&gt;。具体讲五件事：WAF 自定义规则怎么写、速率限制怎么配、Bot 怎么管、IP 与地区封锁怎么下手、规则误伤了怎么查。全部以控制台现行界面为准，规则条数这类配额数字以控制台显示为准，不背死数。&lt;/p&gt;
&lt;h2&gt;先立分层观：边缘挡一层，源站再挡一层&lt;/h2&gt;
&lt;p&gt;WAF 不是源站防火墙的替代品，两者分工不同：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;层&lt;/th&gt;
&lt;th&gt;位置&lt;/th&gt;
&lt;th&gt;挡什么&lt;/th&gt;
&lt;th&gt;特点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Cloudflare WAF&lt;/td&gt;
&lt;td&gt;边缘节点，流量进源站之前&lt;/td&gt;
&lt;td&gt;按 IP、地区、UA、路径特征匹配的 HTTP 层攻击与扫描&lt;/td&gt;
&lt;td&gt;拦得早、不耗源站资源，但只看得见 HTTP 流量&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;源站防火墙&lt;/td&gt;
&lt;td&gt;服务器本机（UFW/nftables）&lt;/td&gt;
&lt;td&gt;非 HTTP 端口、直连源站 IP 的流量、端口扫描&lt;/td&gt;
&lt;td&gt;兜底防线，规则细节见 &lt;a href=&quot;/posts/linux-firewall-ufw-nftables/&quot;&gt;Linux 防火墙实战&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;应用自身&lt;/td&gt;
&lt;td&gt;程序内部&lt;/td&gt;
&lt;td&gt;账号级爆破、业务逻辑滥用&lt;/td&gt;
&lt;td&gt;看得最细，但成本最高&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;为什么要分层？因为 WAF 有个天然盲区：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;攻击者一旦拿到源站真实 IP，就可以绕过 Cloudflare 直连源站&amp;lt;/span&amp;gt;，这时候 WAF 写得再好也拦不到。所以正确的姿势是两边都设防：边缘用 WAF 做粗筛和特征拦截，源站防火墙只放行必要的端口，有条件的话源站只接受 Cloudflare 回源 IP 段的连接。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;WAF 的价值是把 90% 的噪音流量挡在门外，让源站防线只需要对付漏网的少数。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;本篇默认你的域名已经接入 Cloudflare 并且目标记录开了橙云（代理状态）。灰云（仅 DNS 解析）模式下流量不经过 Cloudflare，WAF 规则一条都不会生效，这是后面排障部分的高频坑。&lt;/p&gt;
&lt;h2&gt;WAF 自定义规则的结构&lt;/h2&gt;
&lt;p&gt;进入控制台：选站点 →「安全性」→「WAF」→「自定义规则」→「创建规则」。一条规则就两部分：&lt;strong&gt;表达式&lt;/strong&gt;（匹配什么流量）加&lt;strong&gt;动作&lt;/strong&gt;（匹配后怎么办）。&lt;/p&gt;
&lt;h3&gt;常用表达式字段&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;表达式写法&lt;/th&gt;
&lt;th&gt;典型用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;来源 IP&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ip.src&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;封单个 IP、放行自己的出口 IP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ASN（运营商/机房编号）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ip.geoip.asnum&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;整段封某个云厂商的机房流量&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;国家/地区&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ip.geoip.country&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只允许特定地区访问、封高风险地区&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;User-Agent&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http.user_agent&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;拦扫描器、空 UA、异常客户端&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;请求路径&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http.request.uri.path&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;保护后台、登录页等敏感路径&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;完整 URI&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http.request.uri&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;连查询参数一起匹配&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;请求方法&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http.request.method&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;限制某些路径只允许 GET/POST&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;主机名&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http.host&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;一个账号多站点时区分规则作用域&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;字段之间用 &lt;code&gt;and&lt;/code&gt;、&lt;code&gt;or&lt;/code&gt;、&lt;code&gt;not&lt;/code&gt; 组合，字符串匹配有三件套要分清：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;eq&lt;/code&gt; / &lt;code&gt;ne&lt;/code&gt;：完全相等 / 不相等，适合国家代码、方法这种短字段；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;contains&lt;/code&gt;：包含子串，适合在 UA 和路径里找关键词；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;matches&lt;/code&gt;：正则匹配，强大但写错代价高，新手慎用。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;五种动作的强度与适用&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;动作&lt;/th&gt;
&lt;th&gt;做什么&lt;/th&gt;
&lt;th&gt;强度&lt;/th&gt;
&lt;th&gt;适用场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;跳过（Skip）&lt;/td&gt;
&lt;td&gt;跳过后续若干规则或安全功能直接放行&lt;/td&gt;
&lt;td&gt;放行类&lt;/td&gt;
&lt;td&gt;放行自己的 IP、放行可信合作方接口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;记录（Log）&lt;/td&gt;
&lt;td&gt;只记录不拦截（付费版功能为主）&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;上线新规则前先观察命中情况&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;JS 质询（JS Challenge）&lt;/td&gt;
&lt;td&gt;让浏览器跑一段 JS 验证&lt;/td&gt;
&lt;td&gt;中&lt;/td&gt;
&lt;td&gt;疑似自动化的可疑流量&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;托管质询（Managed Challenge）&lt;/td&gt;
&lt;td&gt;Cloudflare 综合判断后决定放行、验证还是拦截&lt;/td&gt;
&lt;td&gt;中高&lt;/td&gt;
&lt;td&gt;通用防护的首选动作，误伤率最低&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;阻止（Block）&lt;/td&gt;
&lt;td&gt;直接返回 403，连接都不给&lt;/td&gt;
&lt;td&gt;最高&lt;/td&gt;
&lt;td&gt;明确恶意的特征、封 IP/地区&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选动作的原则：&lt;strong&gt;特征越确定，动作越狠&lt;/strong&gt;。命中自己 IP 黑名单的直接 Block；只是「UA 有点怪」的流量用 Managed Challenge 让它证明自己是真人，上来就 Block 很容易误伤。&lt;/p&gt;
&lt;h2&gt;表达式写法入门：编辑器与手写对照&lt;/h2&gt;
&lt;p&gt;控制台提供两种编辑方式：可视化的「字段—运算符—值」下拉拼装，以及直接写表达式的「编辑表达式」。两者生成的是同一种规则语言，下拉拼出来的可以在编辑表达式视图里看到原文，反过来手写时也可以先拼个大概再改。&lt;/p&gt;
&lt;p&gt;下面三个例子都是可以直接套用的真实写法。&lt;/p&gt;
&lt;h3&gt;例子一：后台只允许国内访问&lt;/h3&gt;
&lt;p&gt;假设后台路径是 &lt;code&gt;/admin&lt;/code&gt;，只允许中国大陆 IP 访问，其余一律拦截：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;(http.request.uri.path starts_with &quot;/admin&quot; and ip.geoip.country ne &quot;CN&quot;)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;动作选 Block。注意国家代码是两位大写字母，中国大陆是 &lt;code&gt;CN&lt;/code&gt;。这条规则的意思是：路径以 &lt;code&gt;/admin&lt;/code&gt; 开头&lt;strong&gt;且&lt;/strong&gt;国家不是 CN，才命中拦截——国内用户访问后台不受影响，国内用户访问前台也不受影响。&lt;/p&gt;
&lt;h3&gt;例子二：拦截空 UA 与常见扫描器 UA&lt;/h3&gt;
&lt;p&gt;正常浏览器和正经客户端都会带 User-Agent，空 UA 绝大多数是脚本；扫描器的 UA 更是自报家门：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;(http.user_agent eq &quot;&quot; or http.user_agent contains &quot;sqlmap&quot; or http.user_agent contains &quot;nikto&quot; or http.user_agent contains &quot;nmap&quot; or http.user_agent contains &quot;masscan&quot;)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;动作选 Block 没什么争议。这一条能消掉日志里相当大比例的噪音。写的时候注意：&lt;code&gt;contains&lt;/code&gt; 是子串匹配，别写太短的关键词，比如写 &lt;code&gt;contains &quot;bot&quot;&lt;/code&gt; 会把 Googlebot 之类正经爬虫一起带走。&lt;/p&gt;
&lt;h3&gt;例子三：保护敏感路径&lt;/h3&gt;
&lt;p&gt;登录页、配置文件探测路径单独拎出来加重防护。这里用通用路径举例（WordPress 的 &lt;code&gt;wp-login.php&lt;/code&gt; 同理）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;(http.request.uri.path contains &quot;/login&quot; or http.request.uri.path contains &quot;/.env&quot; or http.request.uri.path contains &quot;/.git/&quot;)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;对这类路径建议分两条规则：&lt;code&gt;/.env&lt;/code&gt;、&lt;code&gt;/.git/&lt;/code&gt; 这种正常用户永远不会访问的路径，命中直接 Block；&lt;code&gt;/login&lt;/code&gt; 是真人要用的，动作用 Managed Challenge，把爆破脚本挡掉又不挡真人登录。&lt;/p&gt;
&lt;p&gt;:::warning
路径匹配是&lt;strong&gt;区分大小写&lt;/strong&gt;的，&lt;code&gt;/Admin&lt;/code&gt; 和 &lt;code&gt;/admin&lt;/code&gt; 不是一回事。表达式写完先用低强度动作（质询）跑一两天，去安全性事件日志里看命中记录，确认没有误伤再升级到 Block。
:::&lt;/p&gt;
&lt;h2&gt;速率限制：给接口装一个闸门&lt;/h2&gt;
&lt;p&gt;WAF 自定义规则管的是「像不像坏人」，速率限制（Rate Limiting）管的是「来得有多快」。入口在「安全性」→「WAF」→「速率限制规则」。一条速率限制规则由四部分组成：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;配置项&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;登录防爆破的参考值&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;匹配表达式&lt;/td&gt;
&lt;td&gt;对哪部分流量计数，如登录路径&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http.request.uri.path eq &quot;/login&quot;&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;计数特征&lt;/td&gt;
&lt;td&gt;按什么维度分别计数，通常是 IP&lt;/td&gt;
&lt;td&gt;按 IP 计数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;周期&lt;/td&gt;
&lt;td&gt;统计窗口&lt;/td&gt;
&lt;td&gt;10 秒或 1 分钟&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;阈值&lt;/td&gt;
&lt;td&gt;窗口内允许的最大请求数&lt;/td&gt;
&lt;td&gt;1 分钟内 5~10 次&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;动作&lt;/td&gt;
&lt;td&gt;超限后怎么办&lt;/td&gt;
&lt;td&gt;Block 或 Managed Challenge&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;持续时间&lt;/td&gt;
&lt;td&gt;处罚时长&lt;/td&gt;
&lt;td&gt;10 分钟起步&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一个完整的登录接口防爆破配置长这样：表达式匹配登录路径且方法为 POST，同一 IP 在 1 分钟内提交超过 5 次，就 Block 10 分钟。真人输错密码重试，五次一分钟足够宽松；爆破脚本一分钟要试几百次，必然触发。&lt;/p&gt;
&lt;p&gt;:::warning
速率限制千万不要对全站一刀切。图片、CSS、JS 等静态资源一个页面就要请求几十个，阈值按页面访问量估算很容易把正常用户锁在门外。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;限速只加在登录、注册、短信验证码、搜索这类真正敏感的接口上。&amp;lt;/span&amp;gt;
:::&lt;/p&gt;
&lt;p&gt;另外注意，免费版速率限制的可用条数和周期选项有限（以控制台为准），但给一两个关键接口防爆破已经够用。更细粒度的需求（按账号、按 Cookie 计数）是付费版的范畴。&lt;/p&gt;
&lt;h2&gt;Bot 管理：和自动化流量斗智斗勇&lt;/h2&gt;
&lt;p&gt;「安全性」→「Bots」里能开 &lt;strong&gt;Bot Fight Mode&lt;/strong&gt;（机器人对抗模式），免费版就可以用。开启后 Cloudflare 会对识别出的自动化流量自动发起质询。它适合对付低水平爬虫和扫描脚本，成本为零，先开着没坏处。&lt;/p&gt;
&lt;p&gt;几个边界要心里有数：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Bot Fight Mode 是个总开关，粒度粗，不能自己定义「放行哪个、拦哪个」；&lt;/li&gt;
&lt;li&gt;更精细的 Super Bot Fight Mode（区分已知机器人、疑似自动化、确定自动化并分别处置）是付费版功能；&lt;/li&gt;
&lt;li&gt;经 Cloudflare 验证的正经爬虫（搜索引擎、监控服务）走的是 Verified Bots 通道，不会被 Bot Fight Mode 误伤，前提是它们确实在验证名单里——自己写的定时脚本如果伪装成浏览器 UA 又行为异常，被质询了不要意外。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;对付 Bot 的顺序是：先开 Bot Fight Mode 兜底，再用自定义规则对漏网的具体特征定点打击。&amp;lt;/span&amp;gt;不要指望一个开关解决所有问题。&lt;/p&gt;
&lt;h2&gt;IP 访问规则与地区封锁&lt;/h2&gt;
&lt;p&gt;比 WAF 规则更简单粗暴的工具是「安全性」→「WAF」→「工具」里的 &lt;strong&gt;IP 访问规则&lt;/strong&gt;（IP Access Rules）：填一个 IP、IP 段或国家，选阻止/允许/质询即可，适合临时封一个正在打你的 IP，不用写表达式。&lt;/p&gt;
&lt;p&gt;三个常用手法：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;封单个 IP / 段&lt;/strong&gt;：日志里发现某个 IP 在猛扫，直接填进去 Block；支持 &lt;code&gt;/24&lt;/code&gt; 这类网段写法；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;封 ASN&lt;/strong&gt;：某个机房整段都在发扫描流量时，在 WAF 自定义规则里用 &lt;code&gt;ip.geoip.asnum&lt;/code&gt; 按 ASN 拦截，比一个个封 IP 省事得多。ASN 可以在安全性事件日志或 IP 查询站里查到；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;地区封锁&lt;/strong&gt;：面向国内用户的站点，可以把主要攻击来源地区整段拦掉，世界立刻清净大半。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::warning
封地区之前先想清楚目标用户在哪。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把用户真实所在的地区封掉，等于把大门焊死在自己脸上&amp;lt;/span&amp;gt;；另外人在境外旅行、出差的国内用户，以及走境外节点访问的正常流量，也会一并被误伤。真要封，先从质询动作开始，别直接 Block。
:::&lt;/p&gt;
&lt;p&gt;白名单同理：把自己家的出口 IP、公司 IP 用 Skip 或 IP 访问规则的「允许」先放行，这是后面所有拦截规则的安全绳。&lt;/p&gt;
&lt;h2&gt;托管规则集：一句带过&lt;/h2&gt;
&lt;p&gt;除了自己写的规则，Cloudflare 还有官方维护的&lt;strong&gt;托管规则集&lt;/strong&gt;（Managed Ruleset），覆盖 OWASP 核心规则、已知 CMS 漏洞利用特征等。免费版包含一套基础的 Cloudflare 托管规则集，可以在 WAF 里开启；付费版的规则更全、更新更快，还能按单条规则调动作。定位很明确：托管规则集负责「已知的通用攻击」，自定义规则负责「你自己站点的具体情况」，两者是叠加关系，不是二选一。&lt;/p&gt;
&lt;h2&gt;规则顺序与优先级&lt;/h2&gt;
&lt;p&gt;自定义规则是&lt;strong&gt;从上往下依次执行&lt;/strong&gt;的，顺序直接决定结果：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;放行类规则（Skip）要排在拦截规则&lt;strong&gt;前面&lt;/strong&gt;。先放行自己人，后面的拦截规则就不会误伤到你；&lt;/li&gt;
&lt;li&gt;越具体的规则越靠前，越宽泛的兜底规则越靠后；&lt;/li&gt;
&lt;li&gt;一条流量命中 Block 就直接结束，不会继续往下走；命中质询并通过后，也可能再撞上下一条规则。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Skip 动作的细节：它可以配置跳过「后续所有自定义规则」，或只跳过某些安全产品。给合作方 API、支付回调这类不能被质询的流量做放行时，用 Skip 指定跳过 WAF 和速率限制，比直接关掉防护安全得多。&lt;/p&gt;
&lt;p&gt;:::warning
改规则之前，先确认已有一条放行自己 IP 的规则在最上面。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;没有这条安全绳，一条写错的拦截规则就能把你自己锁在后台外面&amp;lt;/span&amp;gt;，只能靠换网络、换 IP 才能再进控制台改回来。
:::&lt;/p&gt;
&lt;h2&gt;排障：误伤与失效怎么查&lt;/h2&gt;
&lt;h3&gt;正常用户被拦&lt;/h3&gt;
&lt;p&gt;不要猜，去看证据：「安全性」→「事件」（安全性事件日志）里每条拦截都有记录，包含命中的规则名、来源 IP、路径、动作。让被拦的用户提供&lt;strong&gt;发生时间&lt;/strong&gt;和页面上显示的 &lt;strong&gt;Ray ID&lt;/strong&gt;，按这两个条件一筛就定位到是哪条规则干的。处理分三步：确认是误伤 → 看表达式哪部分匹配宽了 → 收窄条件（比如给路径匹配加上方法限制），而不是直接删规则。&lt;/p&gt;
&lt;h3&gt;规则不生效&lt;/h3&gt;
&lt;p&gt;按顺序排查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;目标记录是不是橙云？灰云流量根本不经过 WAF；&lt;/li&gt;
&lt;li&gt;规则是不是启用状态，顺序是不是被前面的 Skip 规则跳过了；&lt;/li&gt;
&lt;li&gt;表达式字段选错：想匹配带参数的完整地址却用了 &lt;code&gt;http.request.uri.path&lt;/code&gt;（它不含查询字符串，要用 &lt;code&gt;http.request.uri&lt;/code&gt;）；&lt;/li&gt;
&lt;li&gt;大小写与路径写法：路径漏了开头的 &lt;code&gt;/&lt;/code&gt;、结尾斜杠有无，都会影响匹配；&lt;/li&gt;
&lt;li&gt;刚建的规则等一分钟再测，边缘配置下发不是实时的。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;把自己锁在外面&lt;/h3&gt;
&lt;p&gt;症状是后台进不去、页面显示被拦截。补救路径：换一个网络（手机流量）访问控制台，把放行自己 IP 的规则补上或临时停用那条拦截规则；如果连控制台都进不去，说明你封的是整个站而不是后台路径，先用其他 IP 登录 Cloudflare 把规则顺序和范围改对。事后复盘：以后任何拦截规则上线前，先放行规则、再低强度观察、最后才升级动作。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;防护要分层：Cloudflare WAF 在边缘做特征粗筛，源站防火墙兜底，两边都不能缺；&lt;/li&gt;
&lt;li&gt;自定义规则 = 表达式 + 动作，特征越确定动作越狠，不确定的先质询、看日志、再升级；&lt;/li&gt;
&lt;li&gt;速率限制只保护登录、验证码这类敏感接口，阈值按真人行为留足余量；&lt;/li&gt;
&lt;li&gt;Bot Fight Mode 先开着兜底，漏网的用自定义规则定点处理；&lt;/li&gt;
&lt;li&gt;规则从上往下执行，放行自己 IP 的规则永远排第一；&lt;/li&gt;
&lt;li&gt;出问题先查安全性事件日志，Ray ID 和时间是最快的定位线索。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>Web Analytics：不用 GA 的免费站点统计</title><link>https://www.anexns.cloudns.org/posts/cloudflare-web-analytics/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-web-analytics/</guid><description>受够了又重又要弹 Cookie 横幅的统计工具？Cloudflare Web Analytics 免费、不用 Cookie、一段代码或后台点一下就能接入，本文讲清它统计什么、怎么接入、数据怎么看，以及它诚实的边界在哪。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h1&gt;Web Analytics：不用 GA 的免费站点统计&lt;/h1&gt;
&lt;p&gt;说真的，给个人站点装个统计，能把人折腾出心理阴影。Google Analytics 的脚本塞进来，页面凭空多出几百 KB 的加载；欧盟访客一来，还得先弹一个 Cookie 同意横幅，人家还没看正文先被问一遍「你同意吗」；好不容易装上了，一半访客的广告拦截插件直接把统计脚本拦在门外，数据天然缺一块；最后打开后台，报表多得像飞机驾驶舱，你只想知道「昨天来了多少人」，却要先在菜单里迷路十分钟。&lt;/p&gt;
&lt;p&gt;如果你要的只是「多少人来、从哪来、看哪几页、网站快不快」，Cloudflare Web Analytics 是另一条路线：免费、不用 Cookie、不用弹同意横幅、拦截插件对它的影响也小得多，数据面板打开就是答案。本文把它统计什么、两种接入方式、数据怎么看、以及它做不到什么，一次讲清。&lt;/p&gt;
&lt;p&gt;官方文档：https://developers.cloudflare.com/web-analytics/&lt;/p&gt;
&lt;h2&gt;它到底统计什么&lt;/h2&gt;
&lt;p&gt;Web Analytics 收集的是「页面级」的访问数据，不追踪具体的人。核心指标包括：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;访问量与浏览量&lt;/strong&gt;：Visits（访问次数）和 Page Views（页面浏览量），按小时、天等粒度画成趋势图&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;来源页&lt;/strong&gt;：访客从哪个网站点过来（Referrer），搜索引擎、社交平台、直接访问各占多少&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;国家与地区&lt;/strong&gt;：访客的地理分布，按国家列排行&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;浏览器与设备&lt;/strong&gt;：浏览器、操作系统、设备类型（桌面 / 移动）的占比&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;路径排行&lt;/strong&gt;：哪些页面被看得最多，按路径（Path）排序&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;计数方式也值得说清：它以页面加载时 beacon 的实际上报为准，是「真有人打开过这个页面」的实测口径，而不是 Google Analytics 那种按用户与会话建模推算的口径。好处是数字朴素可信，坏处是它天然没有「独立访客」这种建模概念——同一个人一天来三次，就是三次访问，不会帮你去重成一个人。看报表时心里有这杆秤，就不会拿它和别的工具逐项对账对到心态崩掉。&lt;/p&gt;
&lt;p&gt;除了访问数据，它还顺带测&lt;strong&gt;真实用户性能&lt;/strong&gt;，也就是 Core Web Vitals 三大指标，数据来自真实访客的浏览器，而不是实验室跑分：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;指标&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;良好标准&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;LCP&lt;/td&gt;
&lt;td&gt;最大内容元素渲染时间，页面主体内容多久显示出来&lt;/td&gt;
&lt;td&gt;≤ 2.5 秒&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;INP&lt;/td&gt;
&lt;td&gt;交互到下一次绘制的延迟，点击后多久有反应&lt;/td&gt;
&lt;td&gt;≤ 200 毫秒&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;CLS&lt;/td&gt;
&lt;td&gt;累积布局偏移，页面元素乱跳的程度&lt;/td&gt;
&lt;td&gt;≤ 0.1&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这部分数据的价值经常被低估：它能直接告诉你「访客实际感受到的打开速度」，而不是你自己本地测试的理想值。比如你发现移动端 LCP 普遍偏高，多半是首图太大或渲染被阻塞，具体怎么优化缓存与资源加载，可以配合 &lt;a href=&quot;/posts/cloudflare-cache-rules/&quot;&gt;缓存规则&lt;/a&gt; 一起调。&lt;/p&gt;
&lt;p&gt;读 Web Vitals 数据有两个要点。一是看&lt;strong&gt;分位数而不是平均值&lt;/strong&gt;：控制台给出的是真实访客的分布，平均值会被极端慢的个例拉偏，业内通行的做法是看 p75（75% 的访客体验优于这个值），p75 达标才算真的达标。二是&lt;strong&gt;拆开看&lt;/strong&gt;：同一个页面，桌面端可能飞快、移动端却很惨，因为移动端网络和算力都弱一截；按设备、按国家拆开，才能找到真正拖后腿的组合。举个例子，如果某个页面的 CLS 在移动端异常高，通常是图片没写宽高、广告位或嵌入内容后加载把正文挤动了，这类问题在桌面端自测时往往发现不了。&lt;/p&gt;
&lt;h2&gt;隐私模型：为什么不用弹 Cookie 横幅&lt;/h2&gt;
&lt;p&gt;Web Analytics 的设计原则和传统统计工具正好相反：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;不用 Cookie&lt;/strong&gt;：不在访客浏览器里种任何标识&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;不做指纹追踪&lt;/strong&gt;：不采集设备指纹，不跨站拼接用户画像&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;不卖数据、不建广告档案&lt;/strong&gt;：它就是个统计工具，不服务于广告业务&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;直接结果是：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;因为不存 Cookie、不做跨站追踪，Web Analytics 在绝大多数地区不需要 Cookie 同意横幅就能合规使用&amp;lt;/span&amp;gt;。访客打开页面直接看正文，你拿到聚合后的访问数据，双方都清净。这也是很多独立博客从 Google Analytics 迁出来的主要原因——不是数据不够用，是不想为了统计把站点搞得又重又啰嗦。&lt;/p&gt;
&lt;p&gt;再往深一层说：官方对它的定位就是「隐私优先」——不拿访客的 IP 地址和 User-Agent 去拼设备指纹，也不把数据用于广告投放。对站长而言，这意味着你不需要为了统计去更新隐私政策里一长串第三方共享条款，更不用担心某天因为统计工具的合规问题被访客投诉。当然，如果你的站点本身还有其他会种 Cookie 的服务（评论系统、广告、嵌入视频），同意横幅该弹还得弹——免横幅只针对统计这一项，别把账算混了。&lt;/p&gt;
&lt;h2&gt;接入方式一：域名已在 Cloudflare，一键自动注入&lt;/h2&gt;
&lt;p&gt;如果你的域名已经接入 Cloudflare 并且目标站点走了橙云代理（接入方法见 &lt;a href=&quot;/posts/cloudflare-getting-started/&quot;&gt;Cloudflare 入门&lt;/a&gt;），接入简单到没有代码：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;登录 Cloudflare 控制台，进入 &lt;strong&gt;Web Analytics&lt;/strong&gt;（在控制台左侧或账户主页能找到入口）&lt;/li&gt;
&lt;li&gt;点 &lt;strong&gt;Add a site&lt;/strong&gt;，选择你的域名&lt;/li&gt;
&lt;li&gt;在接入方式里选 &lt;strong&gt;Automatic setup&lt;/strong&gt;（自动安装）&lt;/li&gt;
&lt;li&gt;确认开启，等待几分钟生效&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;开启后，Cloudflare 会在你的页面响应里&lt;strong&gt;自动注入&lt;/strong&gt;统计信标（beacon），你不需要改任何一行源代码。部署在 Cloudflare Pages 上的站点同样适用，在 &lt;a href=&quot;/posts/cloudflare-pages-deploy/&quot;&gt;Pages 部署&lt;/a&gt; 的项目设置里也能找到开启 Web Analytics 的选项，效果一致。&lt;/p&gt;
&lt;p&gt;自动注入的好处是零维护：换主题、改模板都不会把统计弄丢。缺点是它依赖橙云代理，灰云（仅 DNS）状态下不注入。&lt;/p&gt;
&lt;p&gt;原理上，注入发生在 Cloudflare 的边缘节点：访客请求页面时，边缘在返回 HTML 之前把 beacon 脚本插进响应里，源站文件本身一个字都不动。所以你在服务器上翻模板文件是找不到这段代码的，要确认注入是否生效，得看浏览器实际收到的页面源码（见下文的验证方法）。同理，如果你的源站自己做了全页静态缓存，也不用担心——注入在缓存之后、响应之前，照样生效。&lt;/p&gt;
&lt;h2&gt;接入方式二：手动加 JS 片段&lt;/h2&gt;
&lt;p&gt;站点没走 Cloudflare 代理，或者你想自己控制注入位置，就用手动方式。先强调一句容易被误解的事实：&lt;strong&gt;手动接入对不在 Cloudflare 上的站点同样免费开放&lt;/strong&gt;，不要求域名迁入、不要求买任何套餐，注册一个 Cloudflare 账户就能用。这让它成了很多托管在别处（比如 GitHub Pages、Netlify、自己的 VPS）的站点的默认统计选择——统计归统计，托管归托管，两件事互不绑定。&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;在 Web Analytics 里 &lt;strong&gt;Add a site&lt;/strong&gt;，填入站点域名&lt;/li&gt;
&lt;li&gt;接入方式选 &lt;strong&gt;Manual setup&lt;/strong&gt;（手动安装）&lt;/li&gt;
&lt;li&gt;控制台会生成一段带你专属 token 的 JS 片段，形如：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;!-- Cloudflare Web Analytics --&amp;gt;
&amp;lt;script defer src=&quot;https://static.cloudflareinsights.com/beacon.min.js&quot;
        data-cf-beacon=&apos;{&quot;token&quot;: &quot;把这里换成你的Token&quot;}&apos;&amp;gt;&amp;lt;/script&amp;gt;
&amp;lt;!-- End Cloudflare Web Analytics --&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把这段代码放进每个页面的 &lt;code&gt;&amp;lt;/body&amp;gt;&lt;/code&gt; 之前。静态站点生成器一般改一处模板即可全站生效，比如 Astro 可以放进全局 Layout 组件的 body 末尾：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;!-- src/layouts/Layout.astro --&amp;gt;
&amp;lt;body&amp;gt;
  &amp;lt;slot /&amp;gt;
  &amp;lt;script defer src=&quot;https://static.cloudflareinsights.com/beacon.min.js&quot; data-cf-beacon=&apos;{&quot;token&quot;: &quot;把这里换成你的Token&quot;}&apos;&amp;gt;&amp;lt;/script&amp;gt;
&amp;lt;/body&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这个 beacon 脚本本身非常小，&lt;code&gt;defer&lt;/code&gt; 加载不阻塞页面渲染，对性能的影响基本可以忽略——这也是它和传统统计脚本在体验上最明显的差别。&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;自动注入和手动片段只能选一种，重复加会导致数据翻倍统计&amp;lt;/span&amp;gt;。域名走橙云时如果已经开了自动注入，就不要再往模板里贴手动片段；反过来，先贴了片段又开自动注入，记得把片段删掉。另外 token 是片段里唯一的身份标识，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;token 抄错或漏字符，页面看起来一切正常，但后台永远没数据&amp;lt;/span&amp;gt;，粘贴后务必逐字核对。
:::&lt;/p&gt;
&lt;p&gt;关于 token 和多站点管理，再补三点实用信息。第一，&lt;strong&gt;一个站点对应一个 token&lt;/strong&gt;：每个在 Web Analytics 里添加的站点都有自己的 token，A 站的片段贴到 B 站，数据会记到 A 站头上，B 站后台永远是空的，多站点时千万别复制错。第二，token 可以在站点设置里&lt;strong&gt;重新生成&lt;/strong&gt;：怀疑 token 泄露（比如误提交进了公开仓库），就在后台重置，然后把新片段同步更新到站点模板里，旧 token 随即失效。第三，token 本身是公开出现在页面源码里的东西，任何人查看源代码都能看到，它的作用是标识数据归属而不是鉴权，所以&lt;strong&gt;看到 token 被别人知道不用慌&lt;/strong&gt;，真正要保护的是你的 Cloudflare 账户本身。&lt;/p&gt;
&lt;h2&gt;接入后如何验证&lt;/h2&gt;
&lt;p&gt;不管哪种接入方式，上线后都建议亲手验一遍，别只看后台的开关状态：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;用无痕窗口（或手机流量）打开你的站点，随便点开两三个页面&lt;/li&gt;
&lt;li&gt;打开浏览器开发者工具的 &lt;strong&gt;Network&lt;/strong&gt; 面板，筛选 &lt;code&gt;rum&lt;/code&gt;，刷新页面——应该能看到 beacon 向 Cloudflare 发出的数据上报请求，状态码 204 或 200 都算正常&lt;/li&gt;
&lt;li&gt;回到 Web Analytics 后台，等几分钟到十几分钟，第一批数据出现就说明链路通了&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;第 2 步最关键：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;后台开关打开不等于统计在工作&amp;lt;/span&amp;gt;，只有浏览器里真的发出了上报请求，数据才可能回来。验的时候记得关掉自己的广告拦截插件，或者用手机验，避免把自己的测试流量先拦了，还误判成接入失败。&lt;/p&gt;
&lt;h2&gt;数据在哪看&lt;/h2&gt;
&lt;p&gt;开启后进入控制台的 Web Analytics 页面，选你的站点，主界面分几块：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;顶部趋势图&lt;/strong&gt;：Visits 和 Page Views 的时间曲线，可以切换时间范围，看日活走势和哪天有流量高峰&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Referrers&lt;/strong&gt;：来源排行。突然多出一个陌生来源，往往是有人转载或分享了你的文章&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Country&lt;/strong&gt;：国家分布。个人博客看看读者都在哪儿，纯属乐趣也无妨&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Paths&lt;/strong&gt;：页面排行。哪篇文章最受欢迎一目了然，决定下一篇写什么时可以参考&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Browser / OS / Device&lt;/strong&gt;：访客环境。移动端占比高，就得优先照顾移动端排版&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Web Vitals 页签&lt;/strong&gt;：LCP、INP、CLS 的真实用户数据，可以按页面、按设备拆开看，定位慢页面&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;看数据有个小习惯值得养成：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;先看 Paths 找热门页面，再看那几页的 Web Vitals，热门又慢的页面优先优化&amp;lt;/span&amp;gt;，精力花在真正有人看的地方。&lt;/p&gt;
&lt;p&gt;另外两个读图技巧。一是&lt;strong&gt;看趋势不看绝对值&lt;/strong&gt;：个人站流量基数小，单日数字上下浮动三成很正常，盯着某一天的涨跌焦虑没有意义，拉长到一周、一个月的曲线才反映真实走势。二是&lt;strong&gt;流量异常先看来源&lt;/strong&gt;：某天突然爆量，先去 Referrers 里确认来源——是被大站转载、上了某个聚合推荐，还是来源不明、路径集中的机器流量。真爆量值得高兴，假爆量则要回头查站点安全，别对着虚假繁荣做内容决策。&lt;/p&gt;
&lt;h2&gt;它做不到什么（诚实部分）&lt;/h2&gt;
&lt;p&gt;Web Analytics 不是 Google Analytics 的全功能平替，它的边界很明确：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;没有转化漏斗&lt;/strong&gt;：注册、购买这类多步转化路径分析，它做不了&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;没有用户级分析&lt;/strong&gt;：不追踪单个访客的行为链路，看不到「某个用户先看了 A 又看了 B」&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;没有事件与目标&lt;/strong&gt;：按钮点击、表单提交这类自定义事件打点，它不支持&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;实时性与维度有限&lt;/strong&gt;：数据有延迟（通常几分钟到更久），筛选维度也比专业工具少，精细化运营分析撑不起来&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;历史数据不长期留存&lt;/strong&gt;：控制台能回看的时间范围有限，它不是数据仓库；真正在意的长期趋势，建议自己定期把关键数字记下来，别指望几年后还能翻出来&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;不提供原始明细&lt;/strong&gt;：你看到的是聚合后的报表，拿不到逐条访问日志去做二次分析；要逐条日志，得用源站自己的访问日志或专门的日志方案&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;说白了：它回答「来了多少人、看了什么、快不快」，不回答「用户是谁、怎么转化的」。个人博客、技术站点、文档站的需求基本都在前者；真做产品运营，再考虑专业工具或自建。&lt;/p&gt;
&lt;h2&gt;和 GA、自建统计比一比&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;Cloudflare Web Analytics&lt;/th&gt;
&lt;th&gt;Google Analytics&lt;/th&gt;
&lt;th&gt;自建统计（如 Umami）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;成本&lt;/td&gt;
&lt;td&gt;免费&lt;/td&gt;
&lt;td&gt;免费（企业版付费）&lt;/td&gt;
&lt;td&gt;服务器与维护成本自担&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;隐私&lt;/td&gt;
&lt;td&gt;不用 Cookie、不跨站追踪&lt;/td&gt;
&lt;td&gt;依赖 Cookie，需同意横幅&lt;/td&gt;
&lt;td&gt;自己掌控，最彻底&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据维度&lt;/td&gt;
&lt;td&gt;访问与性能，维度较少&lt;/td&gt;
&lt;td&gt;最全面，漏斗与事件齐全&lt;/td&gt;
&lt;td&gt;中等，事件可自定义&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据完整性&lt;/td&gt;
&lt;td&gt;较好，受拦截影响小&lt;/td&gt;
&lt;td&gt;常被拦截插件挡掉一部分&lt;/td&gt;
&lt;td&gt;最好，第一方部署&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;维护&lt;/td&gt;
&lt;td&gt;零维护&lt;/td&gt;
&lt;td&gt;零维护但后台复杂&lt;/td&gt;
&lt;td&gt;要自己升级、备份、防挂&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据归属&lt;/td&gt;
&lt;td&gt;Cloudflare 平台&lt;/td&gt;
&lt;td&gt;Google 平台&lt;/td&gt;
&lt;td&gt;完全归自己&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;从 Google Analytics 迁过来的人，第一周通常会疑惑：为什么两边数字对不上？正常现象。两边的计数口径不同（一个按会话和用户建模，一个按页面实测）、被拦截的比例不同、时区与数据延迟也不同，差出 10%–30% 都不奇怪。迁移期建议两者并行跑一两周，以后固定只看一个口径，别拿两套数字互相折磨。&lt;/p&gt;
&lt;p&gt;自建统计（比如 Umami）是另一个合理选项：数据完全归自己、功能比 Web Analytics 多一截，代价是要占一台服务器并自己维护。本文不展开，真想自建可以看博客的自建服务系列慢慢折腾；只想轻量看个数，Web Analytics 是当前最省事的解法。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;h3&gt;开了半天，后台一点数据都没有&lt;/h3&gt;
&lt;p&gt;按这个顺序查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;站点有没有真实访问——先自己用手机流量打开一次页面，等几分钟再看后台&lt;/li&gt;
&lt;li&gt;手动接入的，检查 token 是否完整、片段是否真的出现在页面源码里（浏览器查看源代码搜 &lt;code&gt;beacon&lt;/code&gt;）&lt;/li&gt;
&lt;li&gt;自动接入的，确认域名是橙云代理状态，灰云不注入；同时确认没和手动片段重复或冲突&lt;/li&gt;
&lt;li&gt;页面被全页缓存时，确认缓存里是最新的 HTML，片段没被缓存的旧版本吞掉&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;数据明显比实际访问少&lt;/h3&gt;
&lt;p&gt;一部分广告拦截插件和隐私浏览器也会拦 &lt;code&gt;static.cloudflareinsights.com&lt;/code&gt;，这是所有第三方统计的通病，只是 Web Analytics 受影响相对小一些。觉得差距离谱时，先换无插件的浏览器自测一轮再下结论。更多通用排查思路可以看 &lt;a href=&quot;/posts/cloudflare-troubleshooting/&quot;&gt;Cloudflare 排障&lt;/a&gt;。&lt;/p&gt;
&lt;h3&gt;站点设了严格的 CSP，脚本被浏览器拦下&lt;/h3&gt;
&lt;p&gt;如果你的站点配了 Content Security Policy，浏览器的控制台会报 beacon 脚本被 CSP 阻止，Network 里也看不到上报请求。把 &lt;code&gt;https://static.cloudflareinsights.com&lt;/code&gt; 加进 &lt;code&gt;script-src&lt;/code&gt;，并允许向上报地址发请求（&lt;code&gt;connect-src&lt;/code&gt; 里放行 Cloudflare Insights 的域名）即可。自动注入模式下，脚本是从本站域名同源注入的，一般不受这条影响，这也是手动接入才容易踩的坑。&lt;/p&gt;
&lt;h3&gt;数据延迟，刚发的文章看不到流量&lt;/h3&gt;
&lt;p&gt;Web Analytics 不是实时面板，数据从产生到出现在报表里有延迟，高峰期更久。发完文章想立刻看效果，请至少等十几分钟再刷新，刚打开页面没数据不等于统计坏了。&lt;/p&gt;
&lt;h3&gt;单页应用（SPA）路由切换不计数&lt;/h3&gt;
&lt;p&gt;SPA 在站内跳转时不刷新页面，默认的 beacon 只统计首次加载。在 Web Analytics 的站点设置里开启 &lt;strong&gt;SPA 支持&lt;/strong&gt;（或在片段的 &lt;code&gt;data-cf-beacon&lt;/code&gt; 配置里启用 spa 选项），beacon 才会监听 History 路由变化、把每次站内跳转也算一次浏览。普通多页站点不用管这一项。&lt;/p&gt;
&lt;h3&gt;Pages 项目开了却没数据&lt;/h3&gt;
&lt;p&gt;确认开的是&lt;strong&gt;生产环境&lt;/strong&gt;的部署而不是某个预览分支，并给生产域名带来一次真实访问再等数据延迟。预览域名的数据不会混进生产站点的报表。&lt;/p&gt;
&lt;h2&gt;适合谁，不适合谁&lt;/h2&gt;
&lt;p&gt;适合：个人博客、技术文档站、作品集、开源项目主页这类「内容型站点」——需求就是看流量、看来源、看性能，不背转化 KPI。不适合：电商站、SaaS 产品官网这类要算注册转化、投放归因和广告 ROI 的站点，那是 Google Analytics 和专业分析工具的主场，硬用 Web Analytics 只会觉得处处缺胳膊少腿。选工具先看自己要回答的问题，问题简单，工具就该简单。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Web Analytics 统计访问量、来源、地区、设备和热门路径，外加 LCP / INP / CLS 真实性能数据&lt;/li&gt;
&lt;li&gt;不用 Cookie、不跨站追踪，多数地区免 Cookie 同意横幅，访客和站长都省心&lt;/li&gt;
&lt;li&gt;接入两条路：橙云域名后台一键自动注入，或手动贴一段带 token 的 JS 片段到 &lt;code&gt;&amp;lt;/body&amp;gt;&lt;/code&gt; 前&lt;/li&gt;
&lt;li&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;自动注入与手动片段不要重复加，token 不要抄错&amp;lt;/span&amp;gt;，这两点是新手没数据的主因&lt;/li&gt;
&lt;li&gt;它做不了漏斗、事件和用户级分析；需要那些，上 GA 或自建统计&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;对个人站点来说，统计的目的是心里有数，不是把访客当数据矿。轻、免费、干净，这三点 Web Analytics 都占了，够用就好，这也是它最值得推荐的地方。&lt;/p&gt;
</content:encoded></item><item><title>Workers 自动部署：GitHub Actions 流水线实战</title><link>https://www.anexns.cloudns.org/posts/cloudflare-workers-cicd/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-workers-cicd/</guid><description>还在本地手敲 wrangler deploy 发版？本文用 GitHub Actions 加 wrangler-action 搭一条自动流水线：最小权限 Token、多环境区分、密钥注入与一键回滚全讲清。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;事故是这样发生的：Worker 改了个小功能，我顺手在终端敲下 &lt;code&gt;wrangler deploy&lt;/code&gt;，敲完才想起来——本地这份 &lt;code&gt;wrangler.toml&lt;/code&gt; 刚刚为了调试，绑的还是测试环境的 KV，调试开关也没关。就这么十几秒，一份带着测试配置的代码堂而皇之上了生产。发现的时候冷汗都下来了，赶紧改回来重新发一遍。手动部署的问题从来不是命令难敲，而是人总会忘、总会累、总会在深夜里敲错那一下。这篇就把发布这件事从人手里拿走：代码推上 GitHub，剩下的交给流水线，你只需要看一眼绿色的对勾。&lt;/p&gt;
&lt;p&gt;官方文档：https://developers.cloudflare.com/workers/ci-cd/&lt;/p&gt;
&lt;h2&gt;思路总览：从手敲命令到推代码即部署&lt;/h2&gt;
&lt;p&gt;自动部署的链路并不复杂，一共四步：本地照常开发调试；写完把代码 &lt;code&gt;git push&lt;/code&gt; 到 GitHub；GitHub Actions 被这次推送触发，在云端的一台临时机器上拉下代码；最后由官方的 &lt;code&gt;cloudflare/wrangler-action&lt;/code&gt; 调用 Wrangler，拿着预先存好的凭据把 Worker 发布到 Cloudflare。整条链路里没有你的电脑参与发布，本地关机了都不影响。&lt;/p&gt;
&lt;p&gt;和手动部署摆在一起对比，差别一目了然：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;手动 wrangler deploy&lt;/th&gt;
&lt;th&gt;GitHub Actions 流水线&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;触发方式&lt;/td&gt;
&lt;td&gt;人在本地终端敲命令&lt;/td&gt;
&lt;td&gt;push 到指定分支自动触发&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;发布环境&lt;/td&gt;
&lt;td&gt;取决于本地当时开着哪份配置&lt;/td&gt;
&lt;td&gt;由 workflow 文件写死，人改不了&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;用哪份代码&lt;/td&gt;
&lt;td&gt;本地工作区，可能混着没提交的改动&lt;/td&gt;
&lt;td&gt;仓库里那次提交，分毫不差&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;凭据存放&lt;/td&gt;
&lt;td&gt;登录态存在本机&lt;/td&gt;
&lt;td&gt;加密存放在仓库 Secrets&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;出了问题&lt;/td&gt;
&lt;td&gt;凭记忆回想刚才发了啥&lt;/td&gt;
&lt;td&gt;每次运行都有日志和提交号可查&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合场景&lt;/td&gt;
&lt;td&gt;一次性试验、临时调试&lt;/td&gt;
&lt;td&gt;长期维护的正式项目&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;流水线最大的价值其实是最后两行：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;每次部署都精确对应一次 Git 提交，出了问题能查、能对、能退。&amp;lt;/span&amp;gt;至于是第一次接触 Workers 的朋友，建议先看 &lt;a href=&quot;/posts/cloudflare-workers-intro/&quot;&gt;Workers 入门篇&lt;/a&gt; 把第一个 Worker 跑起来，再回来给它配上自动部署。&lt;/p&gt;
&lt;h2&gt;第一步：准备一个最小权限的 API Token&lt;/h2&gt;
&lt;p&gt;流水线要在云端替你发布 Worker，它手里必须有一张 Cloudflare 的「通行证」，这就是 API Token。注意不要图省事用 Global API Key，也不要随手给个管理员级别的大 Token——流水线只需要「发布 Worker」这一件事的权限，多给的每一分权限，都是泄露之后多赔出去的损失。&lt;/p&gt;
&lt;p&gt;创建路径是：Cloudflare 控制台右上角头像 → My Profile → API Tokens → Create Token。在模板列表里直接选用 &lt;strong&gt;Edit Cloudflare Workers&lt;/strong&gt; 这个现成模板，它预置了 Workers Scripts、Workers Routes、Workers KV 等发布 Worker 真正需要的编辑权限，范围刚好卡在 Workers 这一圈，不碰你的 DNS、不碰你的账单。创建时再顺手把 Account Resources 限定到目标账户，Token 生成后只显示一次，立刻复制保存。&lt;/p&gt;
&lt;p&gt;:::warning
Token 的权限边界，就是这条流水线万一出事时的损失边界。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不要把 Token 明文写进 workflow 文件、代码或任何提交进仓库的地方&amp;lt;/span&amp;gt;——公开仓库里躺着的 Token 等于把发布权限送给了全世界，别人可以拿它往你的账户里发布任意 Worker。Token 只能进下一节讲的仓库 Secrets。
:::&lt;/p&gt;
&lt;p&gt;关于 Token 的创建细节、有效期管理和轮换方法，系列里的 &lt;a href=&quot;/posts/cloudflare-api-token-ddns/&quot;&gt;API Token 与 DDNS 篇&lt;/a&gt; 已经讲过一整套，这里不重复，只强调一句：给流水线的 Token 要单独创建、单独命名（比如 &lt;code&gt;github-actions-deploy&lt;/code&gt;），将来要吊销、要轮换，都不会误伤你其他用途的 Token。&lt;/p&gt;
&lt;h2&gt;第二步：把凭据存进仓库 Secrets&lt;/h2&gt;
&lt;p&gt;来到 GitHub 仓库页面，依次打开 Settings → Secrets and variables → Actions → New repository secret，添加两个条目：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Secret 名称&lt;/th&gt;
&lt;th&gt;填什么&lt;/th&gt;
&lt;th&gt;从哪儿拿&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;CLOUDFLARE_API_TOKEN&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;上一步创建的 API Token&lt;/td&gt;
&lt;td&gt;创建 Token 时显示的那一串&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;CLOUDFLARE_ACCOUNT_ID&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;你的 Cloudflare 账户 ID&lt;/td&gt;
&lt;td&gt;控制台首页右侧栏，或域名概览页&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;Secrets 存进去之后会被加密，任何人都看不到原文，包括你自己——忘了只能删掉重建。workflow 文件里通过 &lt;code&gt;${{ secrets.CLOUDFLARE_API_TOKEN }}&lt;/code&gt; 这样的方式引用，运行时 GitHub 才会把值注入进去，日志里出现时也会被自动打码。Account ID 本身不算机密（它会出现在控制台网址里），放进 Secrets 纯粹是为了配置集中管理，日后换账户改一处即可。&lt;/p&gt;
&lt;h2&gt;第三步：写下完整的 workflow&lt;/h2&gt;
&lt;p&gt;在仓库根目录新建文件 &lt;code&gt;.github/workflows/deploy.yml&lt;/code&gt;，内容如下。这份配置实现的是最常见的策略：代码推到 &lt;code&gt;main&lt;/code&gt; 分支就自动部署到生产环境。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;name: Deploy Worker

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: Deploy to production
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy with Wrangler
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐段拆开看：&lt;code&gt;on.push.branches&lt;/code&gt; 限定只有 &lt;code&gt;main&lt;/code&gt; 分支的推送才触发，避免你在别的分支上随手一推就上了生产；&lt;code&gt;actions/checkout@v4&lt;/code&gt; 负责把这次提交的代码拉到运行器上；核心就是 &lt;code&gt;cloudflare/wrangler-action@v3&lt;/code&gt; 这一步，它内部装好 Wrangler 并执行默认的 &lt;code&gt;deploy&lt;/code&gt; 命令，&lt;code&gt;apiToken&lt;/code&gt; 和 &lt;code&gt;accountId&lt;/code&gt; 从 Secrets 里取。&lt;/p&gt;
&lt;p&gt;文件提交进仓库后，随便往 &lt;code&gt;main&lt;/code&gt; 推一次小改动，然后打开仓库的 Actions 标签页，就能看到这条流水线跑起来。全绿通过之后去访问你的 Worker 地址，新代码应该已经生效。整个过程里，本地连 Wrangler 都不用装。&lt;/p&gt;
&lt;p&gt;有几个可选参数值得知道：&lt;code&gt;wranglerVersion&lt;/code&gt; 可以锁定 Wrangler 的具体版本，避免上游大版本更新突然改变行为；&lt;code&gt;command&lt;/code&gt; 可以换掉默认的 deploy，比如改成 &lt;code&gt;versions upload&lt;/code&gt; 只上传新版本而不立即切流量；&lt;code&gt;workingDirectory&lt;/code&gt; 则用于仓库里有多个项目、Worker 藏在子目录的情况。先从最小配置跑通，再按需加料。&lt;/p&gt;
&lt;h2&gt;第四步：多环境，预发和生产分开&lt;/h2&gt;
&lt;p&gt;只有一个环境时，任何改动都是直接见用户。项目稍微正经一点，就应该拆出预发（staging）环境：新代码先发到预发地址，自己点一遍确认没问题，再发生产。Wrangler 的环境机制正好为此而生，在 &lt;code&gt;wrangler.toml&lt;/code&gt; 里这样写：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;name = &quot;my-worker&quot;
main = &quot;src/index.js&quot;
compatibility_date = &quot;2025-01-01&quot;

[env.staging]
name = &quot;my-worker-staging&quot;

[env.staging.vars]
DEBUG = &quot;true&quot;
API_BASE = &quot;https://staging-api.example.com&quot;

[env.production]
name = &quot;my-worker-production&quot;

[env.production.vars]
DEBUG = &quot;false&quot;
API_BASE = &quot;https://api.example.com&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;顶层配置是默认环境，&lt;code&gt;[env.staging]&lt;/code&gt; 和 &lt;code&gt;[env.production]&lt;/code&gt; 各自继承顶层、再覆盖自己的那部分。部署时靠 &lt;code&gt;--env&lt;/code&gt; 区分：&lt;code&gt;wrangler deploy --env staging&lt;/code&gt; 发预发，&lt;code&gt;wrangler deploy --env production&lt;/code&gt; 发生产，两个环境是两个独立的 Worker，互不影响。&lt;/p&gt;
&lt;p&gt;落到流水线上，推荐的分支策略是：&lt;code&gt;develop&lt;/code&gt; 分支对应 staging，&lt;code&gt;main&lt;/code&gt; 分支对应 production。workflow 稍作扩展，用两个 job 分别处理：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;name: Deploy Worker

on:
  push:
    branches:
      - main
      - develop

jobs:
  deploy-staging:
    if: github.ref == &apos;refs/heads/develop&apos;
    runs-on: ubuntu-latest
    name: Deploy to staging
    steps:
      - uses: actions/checkout@v4
      - name: Deploy staging
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: deploy --env staging

  deploy-production:
    if: github.ref == &apos;refs/heads/main&apos;
    runs-on: ubuntu-latest
    name: Deploy to production
    steps:
      - uses: actions/checkout@v4
      - name: Deploy production
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: deploy --env production
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;日常开发往 &lt;code&gt;develop&lt;/code&gt; 推，自动上预发；验证通过后把 &lt;code&gt;develop&lt;/code&gt; 合并进 &lt;code&gt;main&lt;/code&gt;，自动上生产。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;分支即环境，合并即发布，整个流程不需要任何人碰发布命令。&amp;lt;/span&amp;gt;这里有个最容易踩的坑：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;code&gt;--env&lt;/code&gt; 后面写的名字必须和 wrangler.toml 里 [env.xxx] 的名字一字不差&amp;lt;/span&amp;gt;，写错了 Wrangler 会直接报错退出，流水线变红——倒也算一种保护。&lt;/p&gt;
&lt;h2&gt;第五步：密钥怎么办，两种注入方式要分清&lt;/h2&gt;
&lt;p&gt;先明确一条界线：数据库密码、第三方 API 密钥这类敏感值，永远不进 &lt;code&gt;wrangler.toml&lt;/code&gt; 的 &lt;code&gt;[vars]&lt;/code&gt;——那是明文，会跟着代码进仓库。敏感值在 Workers 里叫 Secret，通过加密通道单独管理，运行时以环境变量的形式出现在代码里。&lt;/p&gt;
&lt;p&gt;手动管理的方式是在本地执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;wrangler secret put API_KEY
# 按提示粘贴密钥值，输入过程不回显

wrangler secret list
# 查看已设置的 Secret 名称（只能看名字，看不到值）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这种方式适合「设一次、很少动」的密钥：你在本地亲手录入，值不经过任何第三方系统。&lt;/p&gt;
&lt;p&gt;另一种方式是让流水线在部署时顺带注入。&lt;code&gt;wrangler-action&lt;/code&gt; 提供了 &lt;code&gt;secrets&lt;/code&gt; 参数：把 Secret 的名字按行写进去，同时在 &lt;code&gt;env&lt;/code&gt; 里把对应的仓库 Secret 传进来，Action 会在部署前后替你执行 &lt;code&gt;wrangler secret put&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;      - name: Deploy with secrets
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          secrets: |
            API_KEY
            WEBHOOK_TOKEN
        env:
          API_KEY: ${{ secrets.API_KEY }}
          WEBHOOK_TOKEN: ${{ secrets.WEBHOOK_TOKEN }}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两种方式的区别在于信任链：手动 &lt;code&gt;secret put&lt;/code&gt; 时密钥只经过你的电脑和 Cloudflare；CI 注入则多经过 GitHub Secrets 这一环，好处是密钥的增改也纳入了仓库管理、换密钥不用等人开电脑。没有哪种绝对更好，个人项目手动设一次最省事，团队协作或密钥轮换频繁的项目走 CI 注入更顺。要注意 CI 注入只在流水线运行时生效，本地 &lt;code&gt;wrangler dev&lt;/code&gt; 调试时读不到这些值，本地开发所需的变量请放在不提交的 &lt;code&gt;.dev.vars&lt;/code&gt; 文件里。&lt;/p&gt;
&lt;p&gt;另外提醒一句，部署和定时、存储这些运行时能力是两回事：给 Worker 加 Cron 定时触发或 KV 存储的配置方法，在 &lt;a href=&quot;/posts/cloudflare-workers-cron-kv/&quot;&gt;Workers 定时与 KV 篇&lt;/a&gt; 里，那些绑定写在 &lt;code&gt;wrangler.toml&lt;/code&gt; 里，流水线部署时会自动一并生效，不用额外处理。&lt;/p&gt;
&lt;h2&gt;第六步：发错了怎么回滚&lt;/h2&gt;
&lt;p&gt;流水线再可靠，也挡不住代码本身有 bug——新版本上线后发现接口全挂，第一件事是回滚到上一个好版本，而不是急着改代码。Wrangler 内置了版本管理命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 查看最近的部署记录，找到上一个正常版本的版本号
wrangler deployments list

# 回滚到指定版本（不填版本号时会列出最近版本让你选）
wrangler rollback
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;回滚是把流量切回旧版本，秒级生效，不需要重新构建、更不需要重新走一遍流水线。等流量稳住之后，再慢慢定位 bug、修复、重新走 &lt;code&gt;develop&lt;/code&gt; → &lt;code&gt;main&lt;/code&gt; 的正常发布流程。也可以在 Cloudflare 控制台的 Worker 页面 → Deployments 里点选历史版本回滚，效果相同。养成一个习惯：每次生产发布后留意几分钟 Actions 日志和线上表现，真出问题时回滚永远是第一动作，复盘是第二动作。&lt;/p&gt;
&lt;h2&gt;顺带说一句：Pages 的自动部署更省事&lt;/h2&gt;
&lt;p&gt;如果你的项目是静态站点或全栈站点而不是纯 Worker，Cloudflare Pages 连这条流水线都不用你搭：在 Pages 里创建项目时直接连接 GitHub 仓库，之后每次 push 都自动构建部署，非生产分支还会生成独立的预览地址。两种方式没有高下之分，区别只在控制权：Pages 的 Git 直连是全自动托管，构建命令和环境变量在控制台里配；Workers 走 Actions 流水线，全部流程写在仓库的 YAML 里，能塞进测试、检查等任意步骤。选型细节可以看系列的 &lt;a href=&quot;/posts/cloudflare-pages-deploy/&quot;&gt;Pages 部署篇&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;排障：流水线变红时先查这几处&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;日志报 Authentication error（错误码 10000）。&lt;/strong&gt; 十有八九是 Token 的问题：用了只读模板（比如 Read All Resources）创建的 Token 能看不能写，部署必然失败。回到 Token 设置里确认用的是 Edit Cloudflare Workers 模板；顺带检查 Token 有没有过期、复制时有没有带上多余的空格。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;日志报 No account id found。&lt;/strong&gt; 这是 wrangler-action 的经典提示：&lt;code&gt;accountId&lt;/code&gt; 没传对。要么仓库 Secrets 里 &lt;code&gt;CLOUDFLARE_ACCOUNT_ID&lt;/code&gt; 压根没建，要么名字拼错导致 &lt;code&gt;${{ secrets.xxx }}&lt;/code&gt; 取了个空值。Secret 名称大小写敏感，一个字母都不能差；也可以把 &lt;code&gt;account_id&lt;/code&gt; 直接写进 &lt;code&gt;wrangler.toml&lt;/code&gt; 作为兜底。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;部署成功了，但代码没更新。&lt;/strong&gt; 先确认你推的分支对不对：workflow 只监听 &lt;code&gt;main&lt;/code&gt;（和示例里的 &lt;code&gt;develop&lt;/code&gt;），推到其他分支根本不会触发，Actions 页面里自然也找不到记录。再看 Actions 里那次运行拉取的提交号，是不是你以为的那一次。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;报环境不存在或配置不生效。&lt;/strong&gt; 对照第四节的坑：&lt;code&gt;command&lt;/code&gt; 里的 &lt;code&gt;--env staging&lt;/code&gt; 必须与 &lt;code&gt;wrangler.toml&lt;/code&gt; 中的 &lt;code&gt;[env.staging]&lt;/code&gt; 严格同名；另外注意，未写在任何 &lt;code&gt;[env]&lt;/code&gt; 段里的顶层 &lt;code&gt;[vars]&lt;/code&gt; 不会自动出现在具名环境中，具名环境要用到的变量要在各自的段里再声明一遍。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;workflow 文件根本没被识别。&lt;/strong&gt; 文件必须位于 &lt;code&gt;.github/workflows/&lt;/code&gt; 目录下、后缀是 &lt;code&gt;.yml&lt;/code&gt; 或 &lt;code&gt;.yaml&lt;/code&gt;，且已经提交到了仓库的默认分支。YAML 缩进错位也会导致整份文件被忽略，用编辑器的 YAML 校验先过一遍再提交。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;把这篇的动作连起来，就是一条完整的发布流水线：用 Edit Cloudflare Workers 模板创建最小权限 Token，存进仓库 Secrets；一份 &lt;code&gt;deploy.yml&lt;/code&gt; 让 &lt;code&gt;main&lt;/code&gt; 分支的每次推送都自动部署；&lt;code&gt;develop&lt;/code&gt; 加 &lt;code&gt;--env&lt;/code&gt; 分出预发和生产；密钥用 &lt;code&gt;wrangler secret put&lt;/code&gt; 或 Action 的 &lt;code&gt;secrets&lt;/code&gt; 参数注入，绝不进代码；真发错了，&lt;code&gt;wrangler rollback&lt;/code&gt; 一键退回。搭好之后，发布就从一件需要集中精神的手工活，变成了一次普通的 &lt;code&gt;git push&lt;/code&gt;。开头那种把测试配置发上生产的事故，不会再有第二次。&lt;/p&gt;
</content:encoded></item><item><title>Workers 进阶：Cron 定时任务与 KV 存储</title><link>https://www.anexns.cloudns.org/posts/cloudflare-workers-cron-kv/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-workers-cron-kv/</guid><description>让 Worker 自己动起来：Cron Triggers 按计划触发 scheduled 处理函数、KV 存下每次运行的结果，再组合出一个定时探活加状态页的完整实战，Worker 从此能干活。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：上一篇的 Worker 只会「被叫到才动」&lt;/h2&gt;
&lt;p&gt;在 &lt;a href=&quot;/posts/cloudflare-workers-intro/&quot;&gt;Workers 入门&lt;/a&gt; 里，我们写的 Worker 全都是一个模式：请求进来，&lt;code&gt;fetch&lt;/code&gt; 处理函数接住，处理完返回响应。没有人访问，它就静静躺着，一行代码都不会跑。&lt;/p&gt;
&lt;p&gt;但真实需求里有一大类活儿不是请求驱动的：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;每 5 分钟探一次自己的几个站点还活着没有；&lt;/li&gt;
&lt;li&gt;每天凌晨把某个 API 的数据拉回来整理一遍；&lt;/li&gt;
&lt;li&gt;每小时刷新一次缓存、同步一次状态。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这类活儿的共同点是两个：&lt;strong&gt;到点自己醒&lt;/strong&gt;，以及&lt;strong&gt;醒来干完活，得有个地方把结果放下&lt;/strong&gt;，不然下次醒来两眼一抹黑，也没法把结果展示给访客看。&lt;/p&gt;
&lt;p&gt;这正是本篇的两块拼图：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;拼图&lt;/th&gt;
&lt;th&gt;解决什么&lt;/th&gt;
&lt;th&gt;在 Cloudflare 里叫什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;定时醒来&lt;/td&gt;
&lt;td&gt;按计划自动触发代码&lt;/td&gt;
&lt;td&gt;Cron Triggers&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;存下结果&lt;/td&gt;
&lt;td&gt;跨请求、跨运行保留数据&lt;/td&gt;
&lt;td&gt;Workers KV&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;把这两块拼上，Worker 就从「被动接请求」升级成「能自己干活的小服务」。本篇路线：先讲 Cron Triggers 的配置与时区坑，再讲 &lt;code&gt;scheduled&lt;/code&gt; 处理函数的写法，然后讲 KV 的本质与全套操作，最后把两者组合成一个完整实战——定时探活加状态页。&lt;/p&gt;
&lt;p&gt;核心结论先放这里：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Cron 负责「什么时候跑」，KV 负责「跑完把结果放哪」，两者组合就是绝大多数轻量自动化任务的完整骨架。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;Cron Triggers：让 Worker 按计划醒来&lt;/h2&gt;
&lt;h3&gt;cron 表达式五字段速通&lt;/h3&gt;
&lt;p&gt;Cron Triggers 用的是经典的 cron 表达式，一共五个字段，用空格分隔：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;分 时 日 月 星期
│  │  │  │  │
│  │  │  │  └─ 星期：0–6（0 是周日），也可用 MON、TUE 等英文缩写
│  │  │  └──── 月：1–12
│  │  └─────── 日：1–31
│  └────────── 时：0–23
└───────────── 分：0–59
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;每个字段除了写具体数字，还支持三种符号：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;*&lt;/code&gt;：任意值，这个字段不限制；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;*/n&lt;/code&gt;：每隔 n 个单位，比如分钟字段写 &lt;code&gt;*/5&lt;/code&gt; 就是每 5 分钟；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;a-b&lt;/code&gt;：范围，比如小时字段写 &lt;code&gt;9-18&lt;/code&gt; 就是 9 点到 18 点；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;a,b,c&lt;/code&gt;：枚举，比如星期字段写 &lt;code&gt;1,3,5&lt;/code&gt; 就是周一、周三、周五。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;常用例子对照表：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;需求&lt;/th&gt;
&lt;th&gt;表达式&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;每 5 分钟&lt;/td&gt;
&lt;td&gt;&lt;code&gt;*/5 * * * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;探活、刷状态最常用的节奏&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每小时整点&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 * * * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;分钟写 0，即每个整点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每天凌晨 2 点&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 2 * * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;注意这是 UTC 时间，下文细说&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每天早上 8 点半&lt;/td&gt;
&lt;td&gt;&lt;code&gt;30 8 * * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;时、分顺序别写反&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每周一上午 9 点&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 9 * * 1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;星期字段 1 是周一&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每月 1 号零点&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 0 1 * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;日字段写 1&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;工作日每小时&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 * * * 1-5&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;周一到周五&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;最大的坑：时区是 UTC&lt;/h3&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Cron Triggers 的时间一律按 UTC 计算，没有时区设置项。&amp;lt;/span&amp;gt;这是新手最容易栽的地方：在中国（UTC+8）想让任务每天北京时间凌晨 2 点跑，表达式要写的是 UTC 的前一天 18 点：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;北京时间 02:00 = UTC 18:00（前一天）
表达式：0 18 * * *
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;换算方法很简单：&lt;strong&gt;北京时间减 8 小时&lt;/strong&gt;。减完跨到前一天也没关系，cron 只认钟点不认日期对应关系，你只要保证换算后的 UTC 时刻正确即可。但要注意一种情况：带星期字段时，跨天会连星期一起错位。比如想在北京时间周一早上 9 点跑，UTC 是周一凌晨 1 点，同一天，没问题；但想在北京时间周日早上 6 点跑，UTC 是周六 22 点，星期字段要写 6（周六）而不是 0（周日）。&lt;/p&gt;
&lt;p&gt;:::warning
改表达式之前，先在心里（或纸上）把目标时间换算成 UTC 再写。线上发现「任务没按时跑」，十有八九不是平台故障，而是时区算错了 8 小时，任务其实在另一个时刻准时跑了。
:::&lt;/p&gt;
&lt;h3&gt;两种配置方式&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;方式一：控制台配置。&lt;/strong&gt; 打开 Cloudflare 控制台，进入对应 Worker 的「设置 → 触发器（Triggers）→ Cron 触发器」，点添加，填入表达式即可。适合快速试错，改完立即生效，不用重新部署代码。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;方式二：wrangler.toml 配置。&lt;/strong&gt; 把触发器写进项目配置文件，跟着代码一起版本管理：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;name = &quot;my-worker&quot;
main = &quot;src/index.js&quot;
compatibility_date = &quot;2024-11-01&quot;

[triggers]
crons = [&quot;*/5 * * * *&quot;, &quot;0 18 * * *&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;一个 Worker 可以挂多个 cron 表达式（数组里写多条）。部署时 &lt;code&gt;wrangler deploy&lt;/code&gt; 会把 triggers 一并同步上去。&lt;/p&gt;
&lt;p&gt;两种方式的关系要注意：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;如果 wrangler.toml 里写了 [triggers]，每次 deploy 都会以文件为准覆盖控制台里的设置。&amp;lt;/span&amp;gt;团队协作时统一走配置文件，避免出现「控制台改了、下次部署又被打回去」的灵异事件。拿不准当前线上到底挂了哪些触发器，去控制台的触发器页面看一眼，那里显示的是实际生效值。&lt;/p&gt;
&lt;h2&gt;scheduled 处理函数：醒来之后干什么&lt;/h2&gt;
&lt;p&gt;Cron Triggers 只负责「叫醒」。醒来之后执行哪段代码，由 &lt;code&gt;scheduled&lt;/code&gt; 处理函数决定。它和 &lt;code&gt;fetch&lt;/code&gt; 并列写在同一个 &lt;code&gt;export default&lt;/code&gt; 对象里：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;export default {
  // 处理 HTTP 请求（入门篇写过）
  async fetch(request, env, ctx) {
    return new Response(&quot;hello&quot;);
  },

  // 处理定时触发（本篇主角）
  async scheduled(event, env, ctx) {
    console.log(&quot;被 cron 叫醒了，计划时间：&quot;, new Date(event.scheduledTime).toISOString());
    // 在这里写定时任务的逻辑
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三个参数各管一摊：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;event&lt;/code&gt;：这次触发的信息，&lt;code&gt;event.cron&lt;/code&gt; 是触发它的表达式字符串（挂了多个 cron 时靠它区分是哪个计划在叫你），&lt;code&gt;event.scheduledTime&lt;/code&gt; 是计划触发时刻的时间戳；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;env&lt;/code&gt;：环境变量与各种绑定（包括下文要绑的 KV），和 &lt;code&gt;fetch&lt;/code&gt; 里的是同一套；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;ctx&lt;/code&gt;：执行上下文，最重要的是 &lt;code&gt;ctx.waitUntil(promise)&lt;/code&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;ctx.waitUntil 为什么重要&lt;/h3&gt;
&lt;p&gt;定时任务里经常有「发出去就不管了」的异步活儿，比如探活要同时请求好几个 URL、结果要写 KV。&lt;code&gt;scheduled&lt;/code&gt; 函数本身返回后，这次运行随时可能被平台收尾。用 &lt;code&gt;ctx.waitUntil()&lt;/code&gt; 把关键的 Promise 登记进去，等于告诉平台「等这些事办完再结束」：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;async scheduled(event, env, ctx) {
  ctx.waitUntil(doWork(env));
}

async function doWork(env) {
  const res = await fetch(&quot;https://example.com&quot;);
  await env.STATUS.put(&quot;last-check&quot;, String(Date.now()));
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;实践建议：把真正的活儿抽成一个独立函数，&lt;code&gt;scheduled&lt;/code&gt; 里只做一件事——&lt;code&gt;ctx.waitUntil(活儿(env))&lt;/code&gt;。结构清楚，也避免漏登记导致任务「跑了一半被掐掉」。&lt;/p&gt;
&lt;p&gt;还有一个区分多计划的常见写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;async scheduled(event, env, ctx) {
  if (event.cron === &quot;*/5 * * * *&quot;) {
    ctx.waitUntil(checkSites(env));      // 5 分钟计划：探活
  } else if (event.cron === &quot;0 18 * * *&quot;) {
    ctx.waitUntil(dailyReport(env));     // 每日计划：汇总
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;一个 Worker 挂多个计划、各干各的活，完全可行，不必为每个计划单独建一个 Worker。&lt;/p&gt;
&lt;h3&gt;本地测试：手动触发 scheduled&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;wrangler dev&lt;/code&gt; 启动后，&lt;code&gt;scheduled&lt;/code&gt; 不会真的等 cron 到点才跑。本地测试有两种方式：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;启动时加参数 &lt;code&gt;wrangler dev --test-scheduled&lt;/code&gt;，然后访问 &lt;code&gt;http://localhost:8787/__scheduled&lt;/code&gt;，每访问一次就手动触发一次 scheduled，还可以带参数指定用哪个表达式触发：&lt;code&gt;http://localhost:8787/__scheduled?cron=*/5+*+*+*+*&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;不加参数时，本地默认根本不触发 scheduled，别对着日志干等。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;改完代码先在本地用 &lt;code&gt;__scheduled&lt;/code&gt; 把逻辑点通，再部署上线，这是最稳的节奏。&lt;/p&gt;
&lt;h2&gt;KV：给 Worker 一个能存东西的地方&lt;/h2&gt;
&lt;h3&gt;它是什么，本质是什么&lt;/h3&gt;
&lt;p&gt;Workers KV 是一个键值存储：你给一个字符串键（key），存一个字符串值（value），之后凭键取回来。就这么简单，没有表、没有行、没有查询语言。&lt;/p&gt;
&lt;p&gt;它的设计取向非常鲜明：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;KV 的表现&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;读取&lt;/td&gt;
&lt;td&gt;数据复制到全球边缘节点，读的时候就近取，极快&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;写入&lt;/td&gt;
&lt;td&gt;写进中心存储后，再逐步同步到全球各节点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;一致性&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;最终一致：刚写完的值，其他地区可能要过一会儿（通常 60 秒内）才读得到&amp;lt;/span&amp;gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合存&lt;/td&gt;
&lt;td&gt;配置、开关、状态快照、缓存、探活结果&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;不适合存&lt;/td&gt;
&lt;td&gt;账户余额、库存计数、需要读了立刻改的强一致数据&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;KV 的本质是「读多写少、能容忍几十秒延迟」的全球分发存储。&amp;lt;/span&amp;gt;理解这一点，后面所有用法和坑都顺理成章：探活结果每 5 分钟写一次、访客随时读，完美契合；而拿它当计数器高频自增，就是跟最终一致性对着干，迟早读到旧值算错账。&lt;/p&gt;
&lt;p&gt;:::warning
不要用 KV 存任何「写完必须立刻读到新值」的关键数据。典型反例：限流计数、秒杀库存、会话令牌的即时吊销。这类需求要的是强一致存储，应该去用 D1 或外部数据库（本篇结尾会再收束这条边界）。
:::&lt;/p&gt;
&lt;h3&gt;建 namespace 与绑定&lt;/h3&gt;
&lt;p&gt;KV 的存储空间叫 namespace（命名空间），可以理解成「一个独立的键值仓库」。一个 Worker 可以绑多个 namespace，互不干扰。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步：建 namespace。&lt;/strong&gt; 控制台在「Workers 和 Pages → KV」里新建；命令行则是一条：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx wrangler kv namespace create STATUS_KV
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;命令会返回这个 namespace 的 id，形如：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{ binding = &quot;STATUS_KV&quot;, id = &quot;abcd1234...&quot; }
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第二步：绑到 Worker。&lt;/strong&gt; 把绑定写进 &lt;code&gt;wrangler.toml&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[[kv_namespaces]]
binding = &quot;STATUS_KV&quot;
id = &quot;abcd1234...&quot;        # 上一步拿到的 id
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;绑定名（binding）就是代码里访问它的变量名，&lt;code&gt;env.STATUS_KV&lt;/code&gt;。部署后生效。注意本地开发时 &lt;code&gt;wrangler dev&lt;/code&gt; 默认用的是本地模拟 KV，数据不和线上互通；想连线上数据调试需显式加 &lt;code&gt;--remote&lt;/code&gt;，日常开发用本地模拟即可，别把测试垃圾写进生产库。&lt;/p&gt;
&lt;h3&gt;代码里操作 KV：put / get / delete / list&lt;/h3&gt;
&lt;p&gt;绑定完成后，在 &lt;code&gt;fetch&lt;/code&gt; 和 &lt;code&gt;scheduled&lt;/code&gt; 里通过 &lt;code&gt;env.绑定名&lt;/code&gt; 使用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;// 写：存一个字符串
await env.STATUS_KV.put(&quot;site:blog&quot;, &quot;up&quot;);

// 写的时候顺带设置过期时间（秒），到期自动删除
await env.STATUS_KV.put(&quot;temp:token&quot;, &quot;xyz&quot;, { expirationTtl: 300 });

// 读：键不存在时返回 null，记得判空
const value = await env.STATUS_KV.get(&quot;site:blog&quot;);
if (value === null) {
  // 没这个键
}

// 读的时候直接按 JSON 解析（存的时候存的是 JSON 字符串时很好用）
const obj = await env.STATUS_KV.get(&quot;state&quot;, { type: &quot;json&quot; });

// 删
await env.STATUS_KV.delete(&quot;site:blog&quot;);

// 列：按前缀列出键（返回的列表本身也有最终一致性）
const list = await env.STATUS_KV.list({ prefix: &quot;site:&quot; });
for (const key of list.keys) {
  console.log(key.name);
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个使用要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;value 只能是字符串（或 ArrayBuffer、流），对象要先 &lt;code&gt;JSON.stringify&lt;/code&gt; 再存，读时再解析，或直接用 &lt;code&gt;{ type: &quot;json&quot; }&lt;/code&gt; 让运行时帮你解析；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;expirationTtl&lt;/code&gt; 是相对秒数，最小 60 秒；还有绝对时间版本 &lt;code&gt;expiration&lt;/code&gt;（Unix 时间戳）。临时状态、验证码类数据用它自动清理，省得手动删；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;list&lt;/code&gt; 适合按前缀做简单枚举（比如把所有站点状态一次列出来渲染状态页），但不要拿它当数据库的 &lt;code&gt;WHERE&lt;/code&gt; 查询使，键多了性能与语义都不对路；&lt;/li&gt;
&lt;li&gt;单个 value 有大小上限，KV 是存小数据的，别往里塞大文件——那是 R2 的活。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;命令行直接操作 KV&lt;/h3&gt;
&lt;p&gt;调试和运维时不用写代码，&lt;code&gt;wrangler kv&lt;/code&gt; 子命令组可以直接读写：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 写一个键
npx wrangler kv key put --binding STATUS_KV &quot;site:blog&quot; &quot;up&quot;

# 读一个键
npx wrangler kv key get --binding STATUS_KV &quot;site:blog&quot;

# 列出所有键
npx wrangler kv key list --binding STATUS_KV

# 删一个键
npx wrangler kv key delete --binding STATUS_KV &quot;site:blog&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意区分两种寻址方式：&lt;code&gt;--binding&lt;/code&gt; 是按 wrangler.toml 里的绑定名（要在项目目录里执行），也可以用 &lt;code&gt;--namespace-id&lt;/code&gt; 直接指定 namespace。线上排障时先用 &lt;code&gt;key get&lt;/code&gt; 看一眼实际存的值，往往比看日志更快定位问题。&lt;/p&gt;
&lt;h2&gt;完整实战：定时探活 + 状态页&lt;/h2&gt;
&lt;p&gt;现在把两块拼图装到一起，做一个真能用的小系统：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;每 5 分钟，&lt;code&gt;scheduled&lt;/code&gt; 自动探活两个站点，把每个站点的状态（up/down）、HTTP 状态码、检查时间写入 KV；&lt;/li&gt;
&lt;li&gt;任何人访问这个 Worker 的地址，&lt;code&gt;fetch&lt;/code&gt; 从 KV 读出最新结果，渲染成一个极简状态页。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;完整代码&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;const SITES = [
  { name: &quot;blog&quot;, url: &quot;https://blog.example.com&quot; },
  { name: &quot;api&quot;, url: &quot;https://api.example.com&quot; },
];

export default {
  // ① 定时部分：被 Cron Triggers 叫醒后探活，结果写 KV
  async scheduled(event, env, ctx) {
    ctx.waitUntil(checkAll(env));
  },

  // ② 请求部分：有人访问时，读 KV 渲染状态页
  async fetch(request, env, ctx) {
    const rows = [];
    for (const site of SITES) {
      const raw = await env.STATUS_KV.get(&quot;site:&quot; + site.name, { type: &quot;json&quot; });
      if (raw === null) {
        rows.push(`&amp;lt;tr&amp;gt;&amp;lt;td&amp;gt;${site.name}&amp;lt;/td&amp;gt;&amp;lt;td&amp;gt;暂无数据&amp;lt;/td&amp;gt;&amp;lt;td&amp;gt;-&amp;lt;/td&amp;gt;&amp;lt;td&amp;gt;-&amp;lt;/td&amp;gt;&amp;lt;/tr&amp;gt;`);
      } else {
        const mark = raw.status === &quot;up&quot; ? &quot;🟢 正常&quot; : &quot;🔴 异常&quot;;
        const time = new Date(raw.time).toLocaleString(&quot;zh-CN&quot;, { timeZone: &quot;Asia/Shanghai&quot; });
        rows.push(`&amp;lt;tr&amp;gt;&amp;lt;td&amp;gt;${site.name}&amp;lt;/td&amp;gt;&amp;lt;td&amp;gt;${mark}&amp;lt;/td&amp;gt;&amp;lt;td&amp;gt;${raw.code}&amp;lt;/td&amp;gt;&amp;lt;td&amp;gt;${time}&amp;lt;/td&amp;gt;&amp;lt;/tr&amp;gt;`);
      }
    }
    const html = `&amp;lt;!doctype html&amp;gt;
&amp;lt;html lang=&quot;zh-CN&quot;&amp;gt;&amp;lt;head&amp;gt;&amp;lt;meta charset=&quot;utf-8&quot;&amp;gt;&amp;lt;title&amp;gt;站点状态&amp;lt;/title&amp;gt;&amp;lt;/head&amp;gt;
&amp;lt;body&amp;gt;&amp;lt;h1&amp;gt;站点状态&amp;lt;/h1&amp;gt;
&amp;lt;table border=&quot;1&quot; cellspacing=&quot;0&quot; cellpadding=&quot;6&quot;&amp;gt;
&amp;lt;tr&amp;gt;&amp;lt;th&amp;gt;站点&amp;lt;/th&amp;gt;&amp;lt;th&amp;gt;状态&amp;lt;/th&amp;gt;&amp;lt;th&amp;gt;HTTP 状态码&amp;lt;/th&amp;gt;&amp;lt;th&amp;gt;最近检查（北京时间）&amp;lt;/th&amp;gt;&amp;lt;/tr&amp;gt;
${rows.join(&quot;\n&quot;)}
&amp;lt;/table&amp;gt;&amp;lt;/body&amp;gt;&amp;lt;/html&amp;gt;`;
    return new Response(html, {
      headers: { &quot;content-type&quot;: &quot;text/html; charset=utf-8&quot; },
    });
  },
};

async function checkAll(env) {
  for (const site of SITES) {
    let result;
    try {
      const res = await fetch(site.url, { method: &quot;GET&quot;, redirect: &quot;follow&quot; });
      result = {
        status: res.status &amp;gt;= 200 &amp;amp;&amp;amp; res.status &amp;lt; 400 ? &quot;up&quot; : &quot;down&quot;,
        code: res.status,
        time: Date.now(),
      };
    } catch (err) {
      result = { status: &quot;down&quot;, code: 0, time: Date.now() };
    }
    await env.STATUS_KV.put(&quot;site:&quot; + site.name, JSON.stringify(result));
  }
  await env.STATUS_KV.put(&quot;last-run&quot;, String(Date.now()));
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;配套的 &lt;code&gt;wrangler.toml&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;name = &quot;site-status&quot;
main = &quot;src/index.js&quot;
compatibility_date = &quot;2024-11-01&quot;

[triggers]
crons = [&quot;*/5 * * * *&quot;]

[[kv_namespaces]]
binding = &quot;STATUS_KV&quot;
id = &quot;替换成你自己的 namespace id&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;逐段讲&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;为什么探活写在 scheduled、展示写在 fetch。&lt;/strong&gt; 探活是「到点就该发生」的事，与有没有访客无关，放 scheduled；状态页是「有人来才需要生成」的东西，放 fetch。两者唯一的交集就是 KV：一个只写，一个只读，职责干净。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;为什么探活结果要连时间戳一起存。&lt;/strong&gt; 状态页上只写「正常」是不够的——如果 Worker 的定时任务本身挂了，页面会永远显示上次的「正常」，骗人。把 &lt;code&gt;time&lt;/code&gt; 一起存、一起展示，任何人一眼就能看出「这数据是 3 分钟前的还是 3 天前的」。&lt;code&gt;last-run&lt;/code&gt; 这个键同理，是给运维留的全局心跳。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;为什么状态判断用 200–399 算 up。&lt;/strong&gt; 站点根路径返回重定向（3xx）在很多部署里是正常行为（比如强制跳 HTTPS 或跳语言首页），一刀切只认 200 会天天误报。连接失败、超时这类异常走 &lt;code&gt;catch&lt;/code&gt;，记为 down 且状态码记 0，与「服务器有响应但状态码不对」区分开。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;为什么这个组合正好扬长避短。&lt;/strong&gt; 探活每 5 分钟才写一次，写频率极低；状态页可能被频繁访问，全是读。KV 恰恰是为「写得少、读得多、读要快」设计的。反过来想：如果把每次探活的原始日志都往 KV 里堆、还要按时间范围查询统计，那就已经越界了——那是数据库的活。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;上线顺序别搞反。&lt;/strong&gt; 先建 namespace 拿到 id，填好 wrangler.toml，再 &lt;code&gt;wrangler deploy&lt;/code&gt;。部署后先手动验证：浏览器访问一次状态页（此时多半显示「暂无数据」，正常），等 5 分钟 cron 跑过一轮，刷新页面就应该有数据了。等不及也可以在控制台的 Worker 页面里用「触发器」相关的测试入口手动触发一次，或者本地先用 &lt;code&gt;--test-scheduled&lt;/code&gt; 把 checkAll 的逻辑验通。&lt;/p&gt;
&lt;h2&gt;与真数据库的边界&lt;/h2&gt;
&lt;p&gt;把话说透，免得以后在选型上反复纠结：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;需求特征&lt;/th&gt;
&lt;th&gt;用 KV&lt;/th&gt;
&lt;th&gt;换 D1 / 外部数据库&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;读多写少、能忍几十秒同步延迟&lt;/td&gt;
&lt;td&gt;✅ 正合适&lt;/td&gt;
&lt;td&gt;大材小用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;存配置、开关、状态快照、缓存&lt;/td&gt;
&lt;td&gt;✅&lt;/td&gt;
&lt;td&gt;也行但没必要&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;写完立刻要读到、不能读旧值&lt;/td&gt;
&lt;td&gt;❌ 最终一致做不到&lt;/td&gt;
&lt;td&gt;✅&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;计数器、余额、库存这类要原子增减&lt;/td&gt;
&lt;td&gt;❌&lt;/td&gt;
&lt;td&gt;✅&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;按条件筛选、排序、聚合统计&lt;/td&gt;
&lt;td&gt;❌ 只有按前缀 list&lt;/td&gt;
&lt;td&gt;✅ SQL 的本行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;结构复杂、表间有关联的数据&lt;/td&gt;
&lt;td&gt;❌&lt;/td&gt;
&lt;td&gt;✅&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一句话定位：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;KV 是「分发到全球边缘的公告板」，不是账本。&amp;lt;/span&amp;gt;公告板上的字晚几十秒同步到所有人眼里没关系；账本上的数字错一位、晚一秒，都可能是事故。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;h3&gt;定时任务没触发&lt;/h3&gt;
&lt;p&gt;按这个顺序查，别乱猜：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;表达式写错&lt;/strong&gt;：字段顺序是分、时、日、月、星期，最常见的错误是把时和分写反，或者星期与日同时写了具体值导致语义叠加。用控制台触发器页面对照一遍，那里会把表达式和下一次触发时间直观列出来；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;时区换算错位&lt;/strong&gt;：任务其实跑了，只是跑在 UTC 换算后的时刻，和你预期的北京时间差 8 小时。去 Worker 的日志（控制台「日志」或 &lt;code&gt;wrangler tail&lt;/code&gt;）里看 scheduled 的实际触发时间，一对便知；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;部署没带上 triggers&lt;/strong&gt;：本地 wrangler.toml 改了 crons 但没重新 &lt;code&gt;wrangler deploy&lt;/code&gt;，或者在控制台手动改完又被下一次 deploy 覆盖。记住两者以最后一次 deploy 的文件为准，改完必须部署；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;代码里没有 scheduled&lt;/strong&gt;：只有触发器、没有处理函数，等于叫醒了但没人应声，不会报错，也不会干活。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;KV 读到旧值&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;先接受这是正常现象&lt;/strong&gt;：写入后全球同步需要时间，通常 60 秒内。用「刚 put 完立刻在另一个地区 get 到了旧值」当 bug 提，是对最终一致性的误解；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;判断是不是超期未同步&lt;/strong&gt;：如果过了几分钟还读不到新值，再去查是不是写错了 namespace 或绑定（本地 dev 用的是模拟 KV、线上是另一个库，这种「我明明写了」多半是环境串了）；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;业务上绕开&lt;/strong&gt;：如果某个流程确实需要「自己刚写的值自己立刻能读到」，把值在同一次运行内用变量传递，不要写完再读 KV。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;wrangler dev 里 scheduled 不自动跑&lt;/h3&gt;
&lt;p&gt;这是预期行为，不是坏了。本地开发服务器不会按 cron 表达式自动触发 scheduled，必须加 &lt;code&gt;--test-scheduled&lt;/code&gt; 启动，再手动访问 &lt;code&gt;/__scheduled&lt;/code&gt; 端点触发（见前文）。另外注意：本地触发时连接的是本地模拟 KV 与本地环境变量，和线上不是一套，测试结论别直接套到线上。&lt;/p&gt;
&lt;h3&gt;状态页一直显示「暂无数据」&lt;/h3&gt;
&lt;p&gt;顺着数据流查：cron 有没有触发（看日志）→ scheduled 里的探活有没有报错（fetch 目标是否可达）→ put 有没有成功（用 &lt;code&gt;wrangler kv key get&lt;/code&gt; 直接查键在不在）→ fetch 里读的键名和写的键名是否一致（&lt;code&gt;site:&lt;/code&gt; 前缀拼错一位是最常见的低级错误）。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Worker 想自己干活，需要两块拼图：Cron Triggers 管定时唤醒，KV 管保存结果；&lt;/li&gt;
&lt;li&gt;cron 表达式五字段不难，真正的坑只有一个：时间是 UTC，北京时间减 8 小时再写，带星期时注意跨天错位；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;scheduled&lt;/code&gt; 与 &lt;code&gt;fetch&lt;/code&gt; 并列，活儿用 &lt;code&gt;ctx.waitUntil&lt;/code&gt; 登记，本地用 &lt;code&gt;--test-scheduled&lt;/code&gt; 加 &lt;code&gt;/__scheduled&lt;/code&gt; 手动触发测试；&lt;/li&gt;
&lt;li&gt;KV 是最终一致的全球键值存储，为读多写少而生，&lt;code&gt;put / get / delete / list&lt;/code&gt; 加过期时间就是它的全套本事，强一致与复杂查询请交给 D1 或外部数据库；&lt;/li&gt;
&lt;li&gt;探活加状态页这个实战把两者的长处用满了：低频写、高频读、结果带时间戳，是拿来练手和真上线的都合适的第一个 Cron + KV 项目。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;至此，Workers 从「接请求」到「定时干活存结果」就齐了。下一步如果想让状态异常时主动通知你，可以在探活逻辑里加一条发消息的 API 调用；想存得更结构化，就去看 D1。额度与计费细节以官方定价页为准，动手前扫一眼免费与付费的边界即可。&lt;/p&gt;
</content:encoded></item><item><title>Cloudflare Workers 入门</title><link>https://www.anexns.cloudns.org/posts/cloudflare-workers-intro/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/cloudflare-workers-intro/</guid><description>在全球边缘节点上跑你的代码：Workers 是什么、和传统服务器的区别、控制台与 Wrangler 两条上手路线，写出改响应头、维护页与简单反代三个能直接用的例子。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;前面几篇讲的都是「配置」：改 DNS、套规则、开缓存。这一篇开始写「代码」了。Cloudflare Workers 让你把一段 JavaScript 代码部署到 Cloudflare 遍布全球的边缘节点上，请求在到达你的源站之前，先经过你的代码处理一遍：可以改请求、改响应、直接返回内容、把流量转发到别处，甚至整个站都不需要源站。&lt;/p&gt;
&lt;p&gt;本篇主线分三段：先讲清 Workers 是什么、和你熟悉的服务器有什么本质区别；再给两条上手路线（控制台在线编辑、Wrangler 命令行），任选一条把第一个 Worker 跑起来；最后给出三个拿来就能用的完整例子——加安全响应头、维护模式页、简单反代。读完你应该能自己判断：什么需求值得写个 Worker，什么需求用前面几篇的规则配置就够了。&lt;/p&gt;
&lt;h2&gt;Workers 是什么&lt;/h2&gt;
&lt;p&gt;Workers 是 Cloudflare 的边缘计算平台。你写一个处理函数，部署上去，Cloudflare 把它分发到全球数百个城市的节点。访客的请求就近进入某个节点时，先执行你的函数，再决定是返回你生成的内容，还是继续去源站取数据。&lt;/p&gt;
&lt;p&gt;它的运行时不是 Node.js，也不是一台虚拟机，而是 Chrome 同款的 V8 引擎里的 &lt;strong&gt;isolate（隔离实例）&lt;/strong&gt;。这是理解 Workers 一切特性的钥匙：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;没有冷启动&lt;/strong&gt;。传统 Serverless 函数冷启动要拉起一个容器或进程，慢则几百毫秒；isolate 的启动成本低到可以忽略，官方口径是接近零冷启动。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;没有完整的操作系统环境&lt;/strong&gt;。没有文件系统、没有 &lt;code&gt;fs&lt;/code&gt;、&lt;code&gt;child_process&lt;/code&gt; 这类 Node.js API，能用的是 Web 标准 API：&lt;code&gt;fetch&lt;/code&gt;、&lt;code&gt;Request&lt;/code&gt;、&lt;code&gt;Response&lt;/code&gt;、&lt;code&gt;URL&lt;/code&gt;、Web Crypto 等。你在浏览器里写前端时用的那套 API，在这里基本都能用。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;按请求计费&lt;/strong&gt;。不跑不花钱，免费版每天有一定请求额度，具体数字以官方定价页为准。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;和你熟悉的几种东西横向对比一下定位：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方案&lt;/th&gt;
&lt;th&gt;运行位置&lt;/th&gt;
&lt;th&gt;启动速度&lt;/th&gt;
&lt;th&gt;环境完整度&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;自己买的 VPS&lt;/td&gt;
&lt;td&gt;固定机房&lt;/td&gt;
&lt;td&gt;常驻运行&lt;/td&gt;
&lt;td&gt;完整系统，随便装&lt;/td&gt;
&lt;td&gt;长期服务、数据库、复杂后端&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;云函数（如 Lambda）&lt;/td&gt;
&lt;td&gt;云厂商机房&lt;/td&gt;
&lt;td&gt;有冷启动&lt;/td&gt;
&lt;td&gt;较完整，可带依赖&lt;/td&gt;
&lt;td&gt;事件触发的后端任务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cloudflare Workers&lt;/td&gt;
&lt;td&gt;全球边缘节点&lt;/td&gt;
&lt;td&gt;近乎无冷启动&lt;/td&gt;
&lt;td&gt;只有 Web 标准 API&lt;/td&gt;
&lt;td&gt;请求改写、边缘逻辑、轻量 API、反代&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;一句话定位：Workers 不是用来替代你的服务器的，而是给流量加一层可编程的「门卫」——请求进门之前先过一遍你的逻辑。&amp;lt;/span&amp;gt;重活、长连接、大计算该放源站的还是放源站；但凡逻辑只跟「这一次 HTTP 请求」有关，放到边缘又快又省。&lt;/p&gt;
&lt;p&gt;:::warning
Workers 的代码运行在 Cloudflare 的节点上，请求和响应都会经过它。给支付、登录这类敏感接口写 Worker 之前，先想清楚日志里会不会打出请求头、Cookie、令牌这类东西——&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把敏感信息写进 console.log 是最常见的翻车方式&amp;lt;/span&amp;gt;，调试完记得清掉。
:::&lt;/p&gt;
&lt;h2&gt;运行模型速通&lt;/h2&gt;
&lt;p&gt;Workers 的心智模型非常简单，就一句话：&lt;strong&gt;一个请求进来，交给你的 &lt;code&gt;fetch&lt;/code&gt; 处理函数，你要么自己造一个 &lt;code&gt;Response&lt;/code&gt; 返回，要么用 &lt;code&gt;fetch()&lt;/code&gt; 把请求转发出去、拿到响应加工后再返回。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;现行推荐的是模块写法（Module Worker），骨架长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;export default {
  async fetch(request, env, ctx) {
    // request：进来的请求（URL、方法、头、体都在里面）
    // env：绑定的变量、KV、密钥等都挂在这里
    // ctx：用来登记「响应返回后继续在后台干」的任务
    return new Response(&quot;Hello from Workers!&quot;);
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个必须先建立的概念：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;一切都是 Web 标准对象&lt;/strong&gt;。&lt;code&gt;request.url&lt;/code&gt; 是字符串，要解析就 &lt;code&gt;new URL(request.url)&lt;/code&gt;；请求头用 &lt;code&gt;request.headers.get(&quot;User-Agent&quot;)&lt;/code&gt; 读；改响应头不能直接改原对象，要新建 &lt;code&gt;Headers&lt;/code&gt; 再构造新的 &lt;code&gt;Response&lt;/code&gt;（下面的例子会演示）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;没有本地状态&lt;/strong&gt;。每个请求可能落在不同节点、不同 isolate 里，别指望用一个全局变量当数据库。需要存数据，用后面提到的 KV、D1、R2。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CPU 时间有限&lt;/strong&gt;。免费版单个请求的 CPU 时间很短（具体以官方定价页为准），它适合做判断、改写、转发，不适合在里面跑重型计算或长时间循环。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;老写法了解即可&lt;/strong&gt;。你在旧教程里会看到 &lt;code&gt;addEventListener(&quot;fetch&quot;, ...)&lt;/code&gt; 的 Service Worker 写法，那是早期语法，现在新项目一律用上面的模块写法，本篇所有例子都用模块写法。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;路线 A：控制台快速上手&lt;/h2&gt;
&lt;p&gt;第一次接触，先别装工具。控制台在线编辑是最快的验证路径，五分钟能看到效果。&lt;/p&gt;
&lt;p&gt;操作顺序：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;登录 Cloudflare 控制台，进入「Workers 和 Pages」→「创建」→「创建 Worker」，起个名字，比如 &lt;code&gt;hello-edge&lt;/code&gt;，点部署。&lt;/li&gt;
&lt;li&gt;部署完点「编辑代码」，把默认代码换成下面这段：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    return new Response(`你正在访问：${url.pathname}\n`, {
      headers: { &quot;content-type&quot;: &quot;text/plain; charset=utf-8&quot; },
    });
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;ol&gt;
&lt;li&gt;点右上角「部署」。回到 Worker 概览页，点开它给的 &lt;code&gt;*.workers.dev&lt;/code&gt; 地址（形如 &lt;code&gt;hello-edge.你的子域名.workers.dev&lt;/code&gt;），就能看到输出，且路径会跟着你访问的路径变。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;到这一步，代码已经在全球边缘跑起来了。但要注意：&lt;code&gt;workers.dev&lt;/code&gt; 地址只是给你预览和测试用的，&lt;strong&gt;真正给自己域名上的流量用，必须绑路由（Route）&lt;/strong&gt;，这一步在下面「路由与触发」里讲。很多新手卡在「Worker 部署成功了但网站上没反应」，原因就是没绑路由。&lt;/p&gt;
&lt;h2&gt;路线 B：Wrangler 命令行&lt;/h2&gt;
&lt;p&gt;正经维护的 Worker 应该走 Wrangler：Cloudflare 官方的命令行工具，负责本地调试、部署、看日志、管绑定。代码进 Git、部署一条命令，比在网页编辑器里改生产代码靠谱得多。&lt;/p&gt;
&lt;h3&gt;安装与登录&lt;/h3&gt;
&lt;p&gt;Wrangler 是个 npm 包，建议装在项目里而不是全局：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir my-worker &amp;amp;&amp;amp; cd my-worker
npm init -y
npm install -D wrangler
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;登录（会拉起浏览器走 OAuth 授权）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx wrangler login
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;初始化项目&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;npx wrangler init
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它会问几个问题（项目名、是否用 TypeScript 等），然后生成骨架。生成的关键文件是 &lt;code&gt;wrangler.toml&lt;/code&gt;，这是 Worker 的部署说明书，核心字段先认识这几个：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;name = &quot;hello-edge&quot;          # Worker 名称，部署后就是这个名字
main = &quot;src/index.js&quot;        # 入口文件
compatibility_date = &quot;2025-01-01&quot;  # 兼容性日期，决定运行时行为版本，新项目填近期日期即可

# 绑到自己域名时才写 routes，二选一即可
# routes = [
#   { pattern = &quot;example.com/api/*&quot;, zone_name = &quot;example.com&quot; },
# ]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;compatibility_date&lt;/code&gt; 是个容易被忽略的坑：它锁定了运行时的行为版本，太旧的日期可能用不了新 API。新建项目时 Wrangler 会自动填当天的日期，照做就行。&lt;/p&gt;
&lt;h3&gt;本地调试与发布&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;npx wrangler dev      # 本地起一个模拟环境，改代码即时生效
npx wrangler deploy   # 部署到 Cloudflare 边缘
npx wrangler tail     # 实时看线上日志，排障必备
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;wrangler dev&lt;/code&gt; 会在本机模拟 Workers 运行时（底层是本地版的 workerd），绝大多数 API 行为和线上一致，先在本地把逻辑跑通再 &lt;code&gt;deploy&lt;/code&gt;，这是标准姿势。&lt;/p&gt;
&lt;p&gt;两条路线怎么选，看这张表：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;控制台在线编辑&lt;/th&gt;
&lt;th&gt;Wrangler&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;上手成本&lt;/td&gt;
&lt;td&gt;零安装，打开网页就能写&lt;/td&gt;
&lt;td&gt;要装 Node.js 和 npm 包&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;代码管理&lt;/td&gt;
&lt;td&gt;存在 Cloudflare 侧，无版本历史&lt;/td&gt;
&lt;td&gt;本地文件，可进 Git&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本地调试&lt;/td&gt;
&lt;td&gt;无，只能部署后看&lt;/td&gt;
&lt;td&gt;&lt;code&gt;wrangler dev&lt;/code&gt; 本地模拟&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;看线上日志&lt;/td&gt;
&lt;td&gt;控制台里有简单日志&lt;/td&gt;
&lt;td&gt;&lt;code&gt;wrangler tail&lt;/code&gt; 实时流&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合&lt;/td&gt;
&lt;td&gt;临时验证、一次性小改动&lt;/td&gt;
&lt;td&gt;任何要长期维护的 Worker&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;例子一：给全站响应加安全头&lt;/h2&gt;
&lt;p&gt;第一个实战例子：让 Worker 在每个响应返回给访客之前，统一加上几个安全相关的响应头（防点击劫持、防 MIME 嗅探等）。这种事在源站 Nginx 上也能做，但边缘统一加的好处是：不管源站换成什么，头都在。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;export default {
  async fetch(request, env, ctx) {
    // 先正常去源站（或后续逻辑）拿到响应
    const response = await fetch(request);

    // 响应头是只读的，必须复制一份再改
    const newHeaders = new Headers(response.headers);
    newHeaders.set(&quot;X-Content-Type-Options&quot;, &quot;nosniff&quot;);
    newHeaders.set(&quot;X-Frame-Options&quot;, &quot;SAMEORIGIN&quot;);
    newHeaders.set(&quot;Referrer-Policy&quot;, &quot;strict-origin-when-cross-origin&quot;);

    // 用改好的头构造一个新响应返回
    return new Response(response.body, {
      status: response.status,
      statusText: response.statusText,
      headers: newHeaders,
    });
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐段看关键点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;await fetch(request)&lt;/code&gt;：把原始请求原样转发给源站，拿到源站的响应。这一步叫「回源」。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;new Headers(response.headers)&lt;/code&gt;：&lt;code&gt;response.headers&lt;/code&gt; 不能直接 &lt;code&gt;set&lt;/code&gt;，这是新手最常撞的墙——必须先克隆。&lt;/li&gt;
&lt;li&gt;重新构造 &lt;code&gt;Response&lt;/code&gt; 时把 &lt;code&gt;body&lt;/code&gt;、&lt;code&gt;status&lt;/code&gt; 一起带上，只换头。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;把这个 Worker 的路由绑成 &lt;code&gt;example.com/*&lt;/code&gt;（全站），所有经过 Cloudflare 的响应就都带上这三个头了。用 &lt;code&gt;curl -I https://example.com&lt;/code&gt; 就能验证。&lt;/p&gt;
&lt;p&gt;:::warning
全站绑 &lt;code&gt;/*&lt;/code&gt; 意味着每个请求都要过 Worker。免费版每天的请求额度是有限的（以官方定价页为准），&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;高流量站点全站套 Worker 可能把额度烧穿，超额后请求会直接报错&amp;lt;/span&amp;gt;。更稳妥的做法是只给需要的路径绑路由，比如只处理动态页面，静态资源走缓存不进 Worker。
:::&lt;/p&gt;
&lt;h2&gt;例子二：维护模式页&lt;/h2&gt;
&lt;p&gt;半夜要给服务器做维护，希望访客看到一个友好的维护页，而不是源站的连接错误。用 Worker 做这件事有个天然优势：&lt;strong&gt;源站哪怕关机了，维护页照样能打开&lt;/strong&gt;，因为它根本不回源。&lt;/p&gt;
&lt;p&gt;实现思路：用一个环境变量当开关。变量在控制台的 Worker 设置里加，或者写在 &lt;code&gt;wrangler.toml&lt;/code&gt; 的 &lt;code&gt;[vars]&lt;/code&gt; 里：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[vars]
MAINTENANCE = &quot;off&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;要维护时把值改成 &lt;code&gt;&quot;on&quot;&lt;/code&gt; 重新部署（或直接在控制台改变量，立即生效）。代码：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;const MAINTENANCE_HTML = `&amp;lt;!doctype html&amp;gt;
&amp;lt;html lang=&quot;zh-CN&quot;&amp;gt;
&amp;lt;head&amp;gt;&amp;lt;meta charset=&quot;utf-8&quot;&amp;gt;&amp;lt;title&amp;gt;维护中&amp;lt;/title&amp;gt;&amp;lt;/head&amp;gt;
&amp;lt;body style=&quot;font-family: sans-serif; text-align: center; padding-top: 15vh;&quot;&amp;gt;
  &amp;lt;h1&amp;gt;网站维护中&amp;lt;/h1&amp;gt;
  &amp;lt;p&amp;gt;我们正在进行计划内维护，请稍后再来。&amp;lt;/p&amp;gt;
&amp;lt;/body&amp;gt;
&amp;lt;/html&amp;gt;`;

export default {
  async fetch(request, env, ctx) {
    if (env.MAINTENANCE === &quot;on&quot;) {
      return new Response(MAINTENANCE_HTML, {
        status: 503,
        headers: {
          &quot;content-type&quot;: &quot;text/html; charset=utf-8&quot;,
          &quot;Retry-After&quot;: &quot;3600&quot;,
        },
      });
    }
    // 开关关闭时，请求原样回源
    return fetch(request);
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个细节值得注意：一是返回 &lt;strong&gt;503&lt;/strong&gt; 而不是 200，这是给搜索引擎看的——503 表示「临时不可用，过会再来」，不会把你的页面从索引里误伤掉；二是带上 &lt;code&gt;Retry-After&lt;/code&gt; 头，告诉爬虫和客户端多久之后再重试。如果只想维护期间放行自己的 IP 测试，可以再在判断里加一个 &lt;code&gt;request.headers.get(&quot;CF-Connecting-IP&quot;)&lt;/code&gt; 的白名单判断，这里就不展开了。&lt;/p&gt;
&lt;h2&gt;例子三：简单反代&lt;/h2&gt;
&lt;p&gt;第三个例子是 Workers 最常见的用法之一：把某个路径的流量转发到另一台服务器。比如主站是 &lt;code&gt;example.com&lt;/code&gt;，但你想让 &lt;code&gt;example.com/api/*&lt;/code&gt; 实际去请求另一台机器 &lt;code&gt;api.internal.example.net&lt;/code&gt;，并且把路径前缀去掉。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);

    if (url.pathname.startsWith(&quot;/api/&quot;)) {
      // 换源站域名，并去掉 /api 前缀
      const target = new URL(url.pathname.replace(/^\/api/, &quot;&quot;) + url.search, &quot;https://api.internal.example.net&quot;);

      // 基于原请求构造新请求，保留方法、头和请求体
      const newRequest = new Request(target, {
        method: request.method,
        headers: request.headers,
        body: request.method === &quot;GET&quot; || request.method === &quot;HEAD&quot; ? undefined : request.body,
        redirect: &quot;manual&quot;,
      });

      return fetch(newRequest);
    }

    // 不匹配 /api/ 的请求，走默认回源
    return fetch(request);
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;关键点逐个说：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;改 URL 要用 &lt;code&gt;new URL()&lt;/code&gt; 重新组装&lt;/strong&gt;，别用字符串硬拼，查询参数（&lt;code&gt;url.search&lt;/code&gt;）很容易拼丢。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;转发请求体要小心&lt;/strong&gt;：GET 和 HEAD 没有请求体，传 &lt;code&gt;body&lt;/code&gt; 反而可能报错，所以上面做了方法判断。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;redirect: &quot;manual&quot;&lt;/code&gt; 表示源站返回 3xx 时不要自动跟随，把重定向原样透传给访客，避免边缘替源站「做主」。&lt;/li&gt;
&lt;li&gt;转发时 &lt;code&gt;Host&lt;/code&gt; 头会由 &lt;code&gt;fetch&lt;/code&gt; 按目标 URL 自动设置，一般不用手动改；个别源站按 Host 校验的，再单独 &lt;code&gt;headers.set(&quot;Host&quot;, ...)&lt;/code&gt; 处理。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;绑路由时把这个 Worker 绑到 &lt;code&gt;example.com/api/*&lt;/code&gt; 即可，&lt;code&gt;/api/&lt;/code&gt; 之外的流量根本不进 Worker，比在代码里判断更省额度。代码里的 &lt;code&gt;startsWith&lt;/code&gt; 判断留着是双保险。&lt;/p&gt;
&lt;h2&gt;路由与触发：没绑路由等于没上线&lt;/h2&gt;
&lt;p&gt;再强调一遍这个最高频的坑：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Worker 部署成功只是把代码放上了边缘，必须再给它绑路由，告诉 Cloudflare「哪些请求要先过这个 Worker」，否则它永远不会被触发。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;绑定的方式有两种：控制台里 Worker 页面的「设置 → 触发器 → 路由」里添加，或者写在 &lt;code&gt;wrangler.toml&lt;/code&gt; 的 &lt;code&gt;routes&lt;/code&gt; 里随部署一起生效。路由的写法是「域名 + 路径」的模式串：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;路由写法&lt;/th&gt;
&lt;th&gt;匹配范围&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;example.com/*&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;该域名下所有路径&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;example.com/api/*&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只有 &lt;code&gt;/api/&lt;/code&gt; 开头的路径&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;*.example.com/*&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;所有子域名&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;example.com/static/*.css&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;特定后缀，也支持这种细粒度写法&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个规则要记牢：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;更具体的路由优先&lt;/strong&gt;。同时存在 &lt;code&gt;example.com/*&lt;/code&gt; 和 &lt;code&gt;example.com/api/*&lt;/code&gt; 两个 Worker 时，&lt;code&gt;/api/&lt;/code&gt; 的请求走后者。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;路由所在域名的 DNS 记录必须开启橙云代理&lt;/strong&gt;（小云朵是橙色）。只有 DNS-only（灰云）的记录，流量根本不经过 Cloudflare，Worker 自然不会触发——这是「路由不生效」的第一嫌疑。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;workers.dev&lt;/code&gt; 子域名是每个账号一个的预览域名，定位就是测试和个人小工具，正式业务请绑自己的域名路由。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;存储：一句话各表一个&lt;/h2&gt;
&lt;p&gt;Worker 本身是无状态的，需要存东西时 Cloudflare 给了三个选择，本篇只给定位，细节看对应文章：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;KV&lt;/strong&gt;：键值存储，全球只读分发、写入后最终一致，适合存配置、开关、映射表这类读多写少的数据。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D1&lt;/strong&gt;：基于 SQLite 的关系型数据库，适合需要正经查表的小型业务数据。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;R2&lt;/strong&gt;：S3 兼容的对象存储，适合存文件、图片、备份，细节见本系列的 &lt;a href=&quot;/posts/cloudflare-r2-storage/&quot;&gt;R2 对象存储实战&lt;/a&gt; 一篇。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;另外还有环境变量与 Secrets：普通变量写 &lt;code&gt;[vars]&lt;/code&gt;，密码、令牌这类敏感值用 &lt;code&gt;wrangler secret put&lt;/code&gt; 单独存，代码里统一从 &lt;code&gt;env&lt;/code&gt; 上取，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把令牌直接写死在代码里提交进 Git&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h2&gt;排障小节&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Worker 报 1101 错误（Worker threw exception）&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;访客看到 1101 就是你的代码抛了未捕获的异常。用 &lt;code&gt;npx wrangler tail&lt;/code&gt; 实时盯日志，再复现一次请求，异常堆栈会直接打出来；控制台里 Worker 的「日志」页也能看历史报错。本地先用 &lt;code&gt;wrangler dev&lt;/code&gt; 复现，能解决掉绝大多数低级错误（变量拼错、给只读头赋值之类）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;路由绑了但完全不生效&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;按顺序查三件事：一，目标域名的 DNS 记录是不是橙云代理（灰云直接排除）；二，路由模式串写对没有，&lt;code&gt;*&lt;/code&gt; 的位置和路径前缀最容易写错；三，这个路径是不是被另一条更具体的路由抢去了别的 Worker。三项都对还不行，把路由临时改成 &lt;code&gt;域名/*&lt;/code&gt; 全量测试，能触发就说明是模式串的问题。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;本地 &lt;code&gt;wrangler dev&lt;/code&gt; 好好的，线上就报错&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;环境差异通常出在三处：一是&lt;strong&gt;绑定没配齐&lt;/strong&gt;——本地 &lt;code&gt;wrangler.toml&lt;/code&gt; 里注释掉的 KV、变量，线上忘了建或忘了绑，&lt;code&gt;env.XXX&lt;/code&gt; 变成 &lt;code&gt;undefined&lt;/code&gt;；二是 &lt;code&gt;compatibility_date&lt;/code&gt; 本地和线上不一致，导致某个 API 行为不同；三是本地测试的请求太「干净」，线上真实请求带了本地没测过的头、体或方法。所以上线前至少拿真实域名在预发路径上完整跑一遍，而不是只信本地。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;改完代码线上没变化&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;先确认你改的是不是部署的那个 Worker（多个环境、多个 Worker 很容易改错），再确认 &lt;code&gt;wrangler deploy&lt;/code&gt; 真的执行成功而不是报错中断；控制台部署的则检查一下浏览器里编辑的是不是最新版本，顺手刷新一下页面排除缓存的假象。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Workers 是跑在 Cloudflare 全球边缘的 JavaScript，用 V8 isolate 实现近乎无冷启动，代价是只有 Web 标准 API、没有文件系统和本地状态。&lt;/li&gt;
&lt;li&gt;心智模型只有一条：请求进来过你的 &lt;code&gt;fetch&lt;/code&gt; 函数，你返回自己造的 &lt;code&gt;Response&lt;/code&gt;，或者 &lt;code&gt;fetch()&lt;/code&gt; 回源加工后再返回。&lt;/li&gt;
&lt;li&gt;上手两条路：控制台适合快速验证，Wrangler 适合长期维护；新项目一律用模块写法。&lt;/li&gt;
&lt;li&gt;三个例子覆盖了最高频的场景：统一加安全头、源站下线也能展示的维护页、按路径转发到另一台源站的简单反代。&lt;/li&gt;
&lt;li&gt;部署不等于上线，&lt;strong&gt;绑路由才算数&lt;/strong&gt;，且域名记录必须是橙云代理。&lt;/li&gt;
&lt;li&gt;需要存数据时按形态选 KV、D1、R2，敏感配置用 Secret 存，别写进代码。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;下一篇我们回到存储主题，把 R2 对象存储从建桶到当图床、做备份完整走一遍。&lt;/p&gt;
</content:encoded></item><item><title>数据库备份与恢复全攻略</title><link>https://www.anexns.cloudns.org/posts/database-backup-restore/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/database-backup-restore/</guid><description>PostgreSQL、MySQL、Redis 三家备份工具一次讲清：pg_dump 与 mysqldump 的正确姿势、物理备份与时间点恢复的概念、Redis 的 RDB 备份法，再加自动化脚本、备份校验和 3-2-1 备份原则，附完整恢复演练流程。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;写在前面：备份的唯一标准是「能恢复」&lt;/h2&gt;
&lt;p&gt;数据库运维里最扎心的一句话是：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;没验证过恢复的备份，等于没有备份&amp;lt;/span&amp;gt;。无数事故的剧本都是同一个：备份脚本跑了三年，某天真出事了，打开备份文件发现是空的、损坏的、或者根本恢复不回去。所以本文不只讲「怎么备份」，每个工具都会把对应的恢复命令成对讲完，最后还有一节专门讲恢复演练。&lt;/p&gt;
&lt;p&gt;先理清两个基本概念，后面三家的工具都是在这两个维度上做取舍：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;逻辑备份&lt;/strong&gt;：把数据导出成 SQL 语句（或类似文本），恢复时重新执行。优点是跨版本、跨平台、可以只备份单个库甚至单张表；缺点是数据量大时慢。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;物理备份&lt;/strong&gt;：直接复制数据库的数据文件。速度快、能支持时间点恢复；缺点是通常要求同版本、同平台，操作更讲究。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;再补一个概念：&lt;strong&gt;时间点恢复（PITR）&lt;/strong&gt;，即先恢复一份全量备份，再重放之后的操作日志（PostgreSQL 的 WAL、MySQL 的 binlog），把数据恢复到任意一秒。这是对付「误删了一张表」这类事故的终极武器——不用回到昨晚的备份，而是回到误删发生前一秒。&lt;/p&gt;
&lt;h2&gt;PostgreSQL：pg_dump 与 pg_basebackup&lt;/h2&gt;
&lt;h3&gt;逻辑备份：pg_dump&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;pg_dump&lt;/code&gt; 是最常用的工具，它导出的是一个数据库的完整 SQL（或归档格式），且备份过程不锁表、不影响业务读写（基于 MVCC 快照）。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 导出为纯 SQL 文本
pg_dump -h 127.0.0.1 -U postgres -d mydb -f mydb.sql

# 导出为自定义归档格式（推荐：可压缩、可并行恢复、可选择性恢复）
pg_dump -h 127.0.0.1 -U postgres -d mydb -Fc -f mydb.dump

# 只备份结构不要数据 / 只要数据不要结构
pg_dump -d mydb --schema-only -f schema.sql
pg_dump -d mydb --data-only -f data.sql

# 备份全部数据库（含角色等全局对象要用 pg_dumpall，它连角色、表空间一起导出）
pg_dumpall -h 127.0.0.1 -U postgres -f all.sql
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;恢复方式按格式区分：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 纯 SQL 格式：用 psql 执行（目标库需先建好）
createdb -h 127.0.0.1 -U postgres mydb_restore
psql -h 127.0.0.1 -U postgres -d mydb_restore -f mydb.sql

# 自定义格式：用 pg_restore，可并行加速
pg_restore -h 127.0.0.1 -U postgres -d mydb_restore -j 4 mydb.dump

# 只恢复某一张表（自定义格式才行）
pg_restore -d mydb_restore -t orders mydb.dump
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;容易踩的坑：&lt;code&gt;pg_dump&lt;/code&gt; 只备份单个数据库的内容，&lt;strong&gt;角色、权限这类全局对象不在里面&lt;/strong&gt;，整机迁移时必须额外跑一次 &lt;code&gt;pg_dumpall --globals-only&lt;/code&gt;。psql 的使用细节在 &lt;a href=&quot;/posts/postgresql-psql-guide/&quot;&gt;《psql 常用命令与操作实战》&lt;/a&gt; 里有完整介绍。&lt;/p&gt;
&lt;h3&gt;物理备份与 PITR：pg_basebackup + WAL 归档&lt;/h3&gt;
&lt;p&gt;要做时间点恢复，路线是：用 &lt;code&gt;pg_basebackup&lt;/code&gt; 拉一份基础备份，同时开启 WAL 归档持续收集日志。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 拉取基础备份（需要有复制权限的用户）
pg_basebackup -h 127.0.0.1 -U repuser -D /backup/base -Ft -z -P
# -Ft 输出 tar 格式，-z 压缩，-P 显示进度
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;postgresql.conf&lt;/code&gt; 里开启归档：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;wal_level = replica
archive_mode = on
archive_command = &apos;test ! -f /backup/wal/%f &amp;amp;&amp;amp; cp %p /backup/wal/%f&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;恢复时把基础备份解开、在数据目录里创建 &lt;code&gt;recovery.signal&lt;/code&gt; 文件并配置 &lt;code&gt;restore_command&lt;/code&gt; 指向 WAL 归档目录，启动后 PostgreSQL 会自动重放日志。还可以设置 &lt;code&gt;recovery_target_time = &apos;2026-11-15 09:30:00&apos;&lt;/code&gt; 把恢复精确停在误删之前的那一秒。&lt;/p&gt;
&lt;h2&gt;MySQL：mysqldump 与 binlog 时间点恢复&lt;/h2&gt;
&lt;h3&gt;逻辑备份：mysqldump&lt;/h3&gt;
&lt;p&gt;MySQL 8.4 里 &lt;code&gt;mysqldump&lt;/code&gt; 依然是逻辑备份的主力。一条合格的生产备份命令长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mysqldump -h 127.0.0.1 -u root -p \
  --single-transaction \
  --routines --events --triggers \
  --databases mydb &amp;gt; mydb_backup.sql
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐个解释关键参数，少一个都可能埋雷：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;--single-transaction&lt;/code&gt;：在事务快照里导出，InnoDB 表不加锁、不影响业务，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;漏了它备份时可能锁表或者数据不一致&amp;lt;/span&amp;gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--routines&lt;/code&gt; / &lt;code&gt;--events&lt;/code&gt; / &lt;code&gt;--triggers&lt;/code&gt;：存储过程、定时事件、触发器默认不全在备份里，要显式带上&lt;/li&gt;
&lt;li&gt;全库备份则用 &lt;code&gt;--all-databases&lt;/code&gt; 替代 &lt;code&gt;--databases&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;恢复就是把 SQL 导回去：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mysql -h 127.0.0.1 -u root -p &amp;lt; mydb_backup.sql
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;数据量大时可以用 &lt;code&gt;pv&lt;/code&gt; 看进度：&lt;code&gt;pv mydb_backup.sql | mysql -u root -p&lt;/code&gt;。大体量（几十 GB 以上）的物理备份可以考虑 Percona XtraBackup 这类第三方工具，支持热备和增量备份，是 MySQL 生态的事实标准，这里不展开。&lt;/p&gt;
&lt;h3&gt;时间点恢复：全量 + binlog 重放&lt;/h3&gt;
&lt;p&gt;mysqldump 时加上 &lt;code&gt;--source-data=2&lt;/code&gt;（MySQL 8.4 的写法，旧版本叫 &lt;code&gt;--master-data=2&lt;/code&gt;），导出的 SQL 文件头部会以注释形式记录备份时刻对应的 binlog 文件和位置。有了这个坐标，事故后就能：先恢复全量备份，再用 &lt;code&gt;mysqlbinlog&lt;/code&gt; 把坐标之后、误删之前的日志重放一遍。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 找出误删语句的位置（比如一条没带 WHERE 的 DELETE）
mysqlbinlog --base64-output=decode-rows -v mysql-bin.000123 &amp;gt; binlog.txt

# 从备份坐标重放到误删之前的位置，再导入
mysqlbinlog --start-position=12345 --stop-position=67890 mysql-bin.000123 | mysql -u root -p
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;前提是 binlog 没有被清理掉：生产环境建议把 &lt;code&gt;binlog_expire_logs_seconds&lt;/code&gt; 设为至少 7 天（604800），并且把 binlog 同步备份到另一台机器，本机磁盘坏了日志也得在。&lt;/p&gt;
&lt;h2&gt;Redis：拷 RDB 文件就够了&lt;/h2&gt;
&lt;p&gt;Redis 的备份最简单，因为它的数据本来就周期性地落在 RDB 文件里（机制详见 &lt;a href=&quot;/posts/redis-persistence/&quot;&gt;《Redis 持久化：RDB 与 AOF 怎么选》&lt;/a&gt;）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 先触发一次最新快照，再拷走文件
redis-cli BGSAVE
cp /var/lib/redis/dump.rdb /backup/redis-$(date +%F).rdb
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Docker 部署则从卷里拷：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec redis redis-cli BGSAVE
docker cp redis:/data/dump.rdb ./redis-backup.rdb
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;恢复时停掉 Redis，把备份文件放回 &lt;code&gt;dir&lt;/code&gt; 目录（注意文件属主和权限要对），再启动即可。如果这台 Redis 开着 AOF，恢复 RDB 前的注意事项在持久化那篇里强调过：必须先处理 &lt;code&gt;appendonlydir&lt;/code&gt;，否则 AOF 会被优先加载。&lt;/p&gt;
&lt;p&gt;需要说明的是，很多团队对纯缓存型 Redis 根本不做备份——数据丢了从数据库重新预热即可。这完全合理，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;备份策略永远取决于数据丢了能不能重建&amp;lt;/span&amp;gt;，别给无状态缓存上重型备份方案。&lt;/p&gt;
&lt;h2&gt;三家工具速查表&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;数据库&lt;/th&gt;
&lt;th&gt;逻辑备份&lt;/th&gt;
&lt;th&gt;恢复命令&lt;/th&gt;
&lt;th&gt;物理备份&lt;/th&gt;
&lt;th&gt;时间点恢复靠什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;PostgreSQL 17&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pg_dump&lt;/code&gt; / &lt;code&gt;pg_dumpall&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;psql&lt;/code&gt; / &lt;code&gt;pg_restore&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pg_basebackup&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;WAL 归档重放&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MySQL 8.4&lt;/td&gt;
&lt;td&gt;&lt;code&gt;mysqldump&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;mysql &amp;lt; file.sql&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;XtraBackup（第三方）&lt;/td&gt;
&lt;td&gt;binlog 重放&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Redis 7.4&lt;/td&gt;
&lt;td&gt;拷 &lt;code&gt;dump.rdb&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;放回 &lt;code&gt;dir&lt;/code&gt; 目录重启&lt;/td&gt;
&lt;td&gt;同左&lt;/td&gt;
&lt;td&gt;不支持（靠主从/备份文件）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
备份目录的权限必须收紧：备份文件里是数据库的全部明文数据，任何能读到它的人都等于拿到了整个数据库。目录权限建议设为仅备份用户可读（&lt;code&gt;chmod 700&lt;/code&gt;），更不要把备份目录放在 Web 服务器能访问的路径下——网上不少数据泄露事件，源头就是一个能被浏览器直接下载的 &lt;code&gt;.sql&lt;/code&gt; 备份文件。
:::&lt;/p&gt;
&lt;h2&gt;自动化：脚本 + 定时任务&lt;/h2&gt;
&lt;p&gt;备份必须自动化，人肉记得备份等于没备份。一个典型的 PostgreSQL 每日备份脚本：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
# /usr/local/bin/backup-pg.sh
set -e
BACKUP_DIR=/backup/postgresql
DATE=$(date +%F_%H%M)
mkdir -p &quot;$BACKUP_DIR&quot;
pg_dump -h 127.0.0.1 -U postgres -d mydb -Fc -f &quot;$BACKUP_DIR/mydb-$DATE.dump&quot;
# 只保留最近 7 天
find &quot;$BACKUP_DIR&quot; -name &quot;mydb-*.dump&quot; -mtime +7 -delete
echo &quot;$(date) backup ok: mydb-$DATE.dump&quot; &amp;gt;&amp;gt; /var/log/db-backup.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;挂到 crontab，每天凌晨 3 点执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;0 3 * * * /usr/local/bin/backup-pg.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;脚本里两个细节别省：&lt;code&gt;set -e&lt;/code&gt; 让任何一步失败就整体报错退出（配合监控告警），以及&lt;strong&gt;备份完检查文件大小&lt;/strong&gt;——导出失败却生成了个 0 字节文件，是最经典的静默翻车。进阶一点可以在脚本末尾加一句 &lt;code&gt;test -s 文件&lt;/code&gt; 校验非空，失败就发告警。&lt;/p&gt;
&lt;h2&gt;备份策略：3-2-1 原则与恢复演练&lt;/h2&gt;
&lt;p&gt;工具之外，策略层面记住业界通用的 &lt;strong&gt;3-2-1 原则&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;3&lt;/strong&gt; 份数据副本（生产 1 份＋备份 2 份）&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;2&lt;/strong&gt; 种不同介质（比如本机磁盘＋对象存储）&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;1&lt;/strong&gt; 份异地存放（另一台服务器、另一个机房或云存储）&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;只把备份放在同一台机器上，防得了误删，防不了磁盘损坏和机器丢失——&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;同机备份在整机故障时和没备份没区别&amp;lt;/span&amp;gt;。个人和小团队的低成本做法：本机保留 7 天，同时用 &lt;code&gt;rclone&lt;/code&gt; 把备份同步一份到对象存储或另一台 VPS，就基本达标了。&lt;/p&gt;
&lt;p&gt;最后是恢复演练，频率建议每季度至少一次，流程固定三步：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;拿最近一份备份，在一台临时机器（或 Docker 容器）上完整恢复&lt;/li&gt;
&lt;li&gt;启动数据库，抽查核心表的行数和最近几条数据&lt;/li&gt;
&lt;li&gt;记录恢复耗时——这个数字就是你的真实 RTO（恢复时间目标），写进运维文档&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Docker 时代演练成本很低，比如验证 PostgreSQL 备份：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d --name pg-restore-test -e POSTGRES_PASSWORD=test postgres:17
docker cp mydb.dump pg-restore-test:/tmp/
docker exec pg-restore-test pg_restore -U postgres -d postgres /tmp/mydb.dump
docker exec pg-restore-test psql -U postgres -c &quot;SELECT count(*) FROM orders;&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;查得到数据、行数对得上，这份备份才算数。演练完把容器删掉即可。&lt;/p&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：备份文件要不要压缩？&lt;/strong&gt;
逻辑备份的 SQL 文本压缩率极高（gzip 后通常只有原体积的 10%–20%），建议必压：&lt;code&gt;pg_dump ... | gzip &amp;gt; backup.sql.gz&lt;/code&gt;，MySQL 同理。&lt;code&gt;pg_dump&lt;/code&gt; 自定义格式 &lt;code&gt;-Fc&lt;/code&gt; 本身已带压缩。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：备份期间业务会变慢吗？&lt;/strong&gt;
&lt;code&gt;pg_dump&lt;/code&gt; 和带 &lt;code&gt;--single-transaction&lt;/code&gt; 的 &lt;code&gt;mysqldump&lt;/code&gt; 都是快照读，不锁表，但会占用磁盘 IO 和 CPU，尽量安排在业务低谷期（比如凌晨）。物理备份同理。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：误删了表，又没有时间点恢复，只有昨晚的备份怎么办？&lt;/strong&gt;
只能恢复到昨晚的状态，当天数据靠应用日志、binlog 残留（若有）人工拼凑。所以重要库请认真评估要不要上 PITR，它的成本只是开个 WAL/binlog 归档，收益是事故时能精确回滚到任意一秒。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：备份文件里有明文数据，要加密吗？&lt;/strong&gt;
备份文件等同于数据库本体，里面什么都有。异地传输和存放前建议加密，比如 &lt;code&gt;gpg&lt;/code&gt; 对称加密后再上传对象存储，密钥单独保管。至少要保证存储位置的访问权限收紧，不能裸奔在公开桶里。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：主从复制能代替备份吗？&lt;/strong&gt;
不能。复制会把误删操作实时同步到从库，主库删了表从库立刻跟着删。复制解决的是高可用，备份解决的是历史回滚，两件事，&lt;a href=&quot;/posts/database-replication-basics/&quot;&gt;《主从复制入门》&lt;/a&gt; 里会再强调这一点。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;备份这件事，工具只占三分，策略和演练占七分。记住四句话：逻辑备份用官方 dump 工具并带全参数；重要库开启日志归档做时间点恢复；备份遵循 3-2-1，必须有异地副本；&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;定期做恢复演练，没演练过的备份不算数&amp;lt;/span&amp;gt;。下一篇讲主从复制——让数据实时多一份活副本，和备份一起构成完整的容灾体系。&lt;/p&gt;
</content:encoded></item><item><title>数据库怎么选：PostgreSQL、MySQL、Redis 分别适合什么场景</title><link>https://www.anexns.cloudns.org/posts/database-choosing-guide/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/database-choosing-guide/</guid><description>选数据库之前先想清楚三件事：数据要不要长期保存、查询有多复杂、访问有多快。这篇把 PostgreSQL、MySQL、Redis 的定位、优劣和典型场景一次讲透，给出可以直接照着用的选型结论。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说结论：没有最好的数据库，只有最合适的&lt;/h2&gt;
&lt;p&gt;很多新手选数据库的方式是「看别人用什么」「看哪个教程多」，结果项目做到一半才发现选错：拿 Redis 存订单，重启一次数据全没；拿 MySQL 硬扛排行榜每秒上万次刷新，数据库先累趴下。选型这件事，本质上是在回答三个问题：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;数据要不要长期、可靠地保存？&lt;/strong&gt; 丢了会不会出大事？&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;查询有多复杂？&lt;/strong&gt; 是简单的按主键查一行，还是多表关联、聚合统计、全文检索？&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;访问模式是什么？&lt;/strong&gt; 读写比例多少？延迟要求是毫秒级还是秒级就行？&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;把这三个问题想清楚，PostgreSQL、MySQL、Redis 之间的分工其实非常明确。这也是本系列的开篇，后面会分别深入每个数据库：先看 &lt;a href=&quot;/posts/database-docker-quickstart/&quot;&gt;《用 Docker 快速搭建三大数据库》&lt;/a&gt; 把环境跑起来，再看 &lt;a href=&quot;/posts/sql-basics-crud/&quot;&gt;《SQL 基础速成》&lt;/a&gt; 补齐通用语法。&lt;/p&gt;
&lt;p&gt;一句话版本：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;订单、用户、账目这类核心数据用关系型数据库（PostgreSQL 或 MySQL），缓存、计数、临时状态用 Redis 补充&lt;/strong&gt;&amp;lt;/span&amp;gt;。三者不是互相替代，成熟的项目里往往是关系型数据库当主力、Redis 当加速器，同时存在。&lt;/p&gt;
&lt;h2&gt;三个数据库的定位&lt;/h2&gt;
&lt;h3&gt;PostgreSQL：功能最强的全能关系型数据库&lt;/h3&gt;
&lt;p&gt;PostgreSQL 是开源关系型数据库里功能最丰富的：标准 SQL 支持最完整，窗口函数、CTE、物化视图、部分索引、表达式索引一应俱全；原生支持 JSON/JSONB，既能当关系型用，也能存半结构化数据；扩展生态强大，PostGIS 做地理位置、pg_trgm 做模糊匹配、TimescaleDB 做时序数据。它对数据一致性和复杂查询的支持是三者里最好的，适合「数据是核心资产」的场景。&lt;/p&gt;
&lt;p&gt;代价是：相对 MySQL 上手略陡一点，默认配置偏保守，小内存机器上要稍微调一调（后面《PostgreSQL 安装与初始配置》一篇会讲）。&lt;/p&gt;
&lt;h3&gt;MySQL：生态最大、运维资料最多的关系型数据库&lt;/h3&gt;
&lt;p&gt;MySQL 是全球使用量最大的开源数据库，WordPress、各种建站程序、绝大多数 PHP 生态默认就是它。它的优势不在功能，而在生态：教程多、运维工具多、云厂商托管服务多、招人容易。InnoDB 引擎对高并发读写、主从复制的支持非常成熟，互联网公司的大规模实践也最多。&lt;/p&gt;
&lt;p&gt;功能上 MySQL 8.x 已经补齐了窗口函数、CTE、JSON 等特性，日常业务完全够用。短板是复杂分析和部分高级 SQL 特性仍不如 PostgreSQL，授权协议（Oracle 的 GPL + 商业双授权）也是一些公司选 MariaDB 分支的原因。&lt;/p&gt;
&lt;h3&gt;Redis：内存数据结构服务器&lt;/h3&gt;
&lt;p&gt;Redis 严格说不算传统数据库，它是把数据放在内存里的数据结构服务器。它的特点是&lt;strong&gt;极快&lt;/strong&gt;：单机轻松每秒十万级读写，延迟在亚毫秒级。除了简单的键值，它还提供列表、集合、有序集合、哈希、位图等丰富的数据结构，原生适合做缓存、排行榜、计数器、会话存储、消息队列、分布式锁。&lt;/p&gt;
&lt;p&gt;代价同样明显：数据以内存为主，持久化是辅助手段，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;绝不能把 Redis 当作唯一存储来放订单、支付等不可丢失的数据&lt;/strong&gt;&amp;lt;/span&amp;gt;。内存价格也远高于磁盘，同等数据量成本高得多。&lt;/p&gt;
&lt;h2&gt;横向对比&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;PostgreSQL&lt;/th&gt;
&lt;th&gt;MySQL&lt;/th&gt;
&lt;th&gt;Redis&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;类型&lt;/td&gt;
&lt;td&gt;关系型数据库&lt;/td&gt;
&lt;td&gt;关系型数据库&lt;/td&gt;
&lt;td&gt;内存键值 / 数据结构&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据存放&lt;/td&gt;
&lt;td&gt;磁盘（带内存缓存）&lt;/td&gt;
&lt;td&gt;磁盘（带内存缓存）&lt;/td&gt;
&lt;td&gt;内存为主，磁盘持久化为辅&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;查询语言&lt;/td&gt;
&lt;td&gt;SQL（最完整）&lt;/td&gt;
&lt;td&gt;SQL&lt;/td&gt;
&lt;td&gt;命令式 API，无 SQL&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;事务&lt;/td&gt;
&lt;td&gt;完整 ACID，默认隔离级别高&lt;/td&gt;
&lt;td&gt;InnoDB 支持 ACID&lt;/td&gt;
&lt;td&gt;单命令原子，多命令事务较弱&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;典型延迟&lt;/td&gt;
&lt;td&gt;毫秒级&lt;/td&gt;
&lt;td&gt;毫秒级&lt;/td&gt;
&lt;td&gt;亚毫秒级&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;擅长&lt;/td&gt;
&lt;td&gt;复杂查询、数据分析、JSON、地理数据&lt;/td&gt;
&lt;td&gt;高并发 Web 业务、生态整合&lt;/td&gt;
&lt;td&gt;缓存、排行榜、计数、会话&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;不擅长&lt;/td&gt;
&lt;td&gt;超大规模简单读写的极致吞吐调优资料相对少&lt;/td&gt;
&lt;td&gt;复杂分析查询、高级 SQL 特性&lt;/td&gt;
&lt;td&gt;大数据量持久存储、复杂查询&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;扩展方式&lt;/td&gt;
&lt;td&gt;垂直扩展为主，扩展插件丰富&lt;/td&gt;
&lt;td&gt;主从复制、分片生态成熟&lt;/td&gt;
&lt;td&gt;集群模式分片&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;授权&lt;/td&gt;
&lt;td&gt;PostgreSQL License（宽松）&lt;/td&gt;
&lt;td&gt;GPL / 商业双授权&lt;/td&gt;
&lt;td&gt;RSALv2 / SSPLv1（7.4 起三授权，含 AGPLv3 选项）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;按场景选型&lt;/h2&gt;
&lt;h3&gt;场景一：做一个博客、商城、企业官网&lt;/h3&gt;
&lt;p&gt;这是最常见的场景：用户、文章、商品、订单，全是结构化数据，要长期保存，查询以增删改查和简单关联为主。&lt;/p&gt;
&lt;p&gt;结论：&lt;strong&gt;PostgreSQL 或 MySQL 二选一，都不会错&lt;/strong&gt;。团队里有人熟悉哪个就用哪个；全新项目、没有历史包袱，我更推荐 PostgreSQL，功能上限更高，以后想加复杂统计、JSON 字段、地理查询时不用换库。老项目、现成程序（比如 WordPress）要求 MySQL 的，就老老实实用 MySQL。&lt;/p&gt;
&lt;h3&gt;场景二：给系统加缓存、扛热点流量&lt;/h3&gt;
&lt;p&gt;商品详情页每秒被刷一万次，每次都查数据库，数据库 CPU 直接打满。这类场景的解法是把热点数据放进 Redis，请求先查 Redis，没有再查数据库并回填。&lt;/p&gt;
&lt;p&gt;结论：&lt;strong&gt;Redis 作为关系型数据库的补充&lt;/strong&gt;，不是替代。缓存数据丢了可以从数据库重建，所以 Redis 挂了最多是慢一点，不会丢业务数据。&lt;/p&gt;
&lt;h3&gt;场景三：排行榜、计数器、点赞数&lt;/h3&gt;
&lt;p&gt;游戏积分榜、文章阅读量、视频点赞数：写入频繁、要实时排序、单条数据很小。&lt;/p&gt;
&lt;p&gt;结论：&lt;strong&gt;Redis 的有序集合和计数器是天生为此而生&lt;/strong&gt;，用关系型数据库做要么频繁 &lt;code&gt;UPDATE&lt;/code&gt; 锁行，要么 &lt;code&gt;ORDER BY&lt;/code&gt; 全表扫，性能差一个数量级。定期把 Redis 里的计数落盘到关系型数据库做持久备份即可。&lt;/p&gt;
&lt;h3&gt;场景四：数据分析、报表统计&lt;/h3&gt;
&lt;p&gt;运营要按月、按地区、按品类多维度统计销售额，还要同比环比。这类 OLAP 倾向的查询，PostgreSQL 的窗口函数、聚合和并行查询明显强于 MySQL；数据量再大（亿级以上、专门的分析系统）则应该考虑 ClickHouse 这类列式数据库，不在本文三者范围内。&lt;/p&gt;
&lt;h3&gt;场景五：地理位置、附近的人&lt;/h3&gt;
&lt;p&gt;PostgreSQL + PostGIS 是开源界的事实标准，MySQL 的空间功能够用但弱一截，这个场景直接选 PostgreSQL。&lt;/p&gt;
&lt;h2&gt;选型避坑清单&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;不要只用 Redis 存全部数据&lt;/strong&gt;：内存满了会触发淘汰策略，数据说没就没；持久化配置不当，断电一样丢数据。Redis 的持久化细节在 &lt;a href=&quot;/posts/redis-persistence/&quot;&gt;《Redis 持久化：RDB 与 AOF 怎么选》&lt;/a&gt; 里专门讲。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;不要过早上分库分表&lt;/strong&gt;：单机关系型数据库扛住每天几百万请求毫无压力，过早分片只会让开发运维复杂度爆炸。先把索引加对（本系列后面有专门篇目），九成性能问题都在索引上。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;不要忽视备份&lt;/strong&gt;：选哪个库都要先想好备份方案，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;没有备份的数据库等于把资产放在火山口上&lt;/strong&gt;&amp;lt;/span&amp;gt;，具体做法看 &lt;a href=&quot;/posts/database-backup-restore/&quot;&gt;《数据库备份与恢复全攻略》&lt;/a&gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;许可证要留意&lt;/strong&gt;：公司产品要分发、闭源商用时，先确认授权条款，MySQL 的 GPL 和 Redis 7.x 的新授权都值得法务扫一眼；PostgreSQL 的授权最宽松，无此类顾虑。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
选型最常见的错误不是选错产品，而是&lt;strong&gt;只选一个&lt;/strong&gt;：用关系型数据库硬做缓存和排行榜，或者用 Redis 硬存核心业务数据。正确姿势是让每个组件做它擅长的事，组合使用。
:::&lt;/p&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：PostgreSQL 和 MySQL 到底怎么二选一？&lt;/strong&gt;
A：全新项目、查询复杂、想用 JSON 和高级 SQL 特性，选 PostgreSQL；现成程序指定 MySQL、团队已有 MySQL 运维经验、要用大量现成托管服务，选 MySQL。两者在普通业务下的性能差距远小于索引和 SQL 写得好不好的差距。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：小项目能不能只用 Redis 不用关系型数据库？&lt;/strong&gt;
A：纯临时数据的小工具可以；只要有用户账号、订单、文章这类丢了就出事的数据，就必须有关系型数据库兜底，Redis 只能做加速层。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：SQLite 算什么定位？&lt;/strong&gt;
A：它是嵌入式数据库，单文件、零运维，适合桌面软件、小工具、单机低并发服务。多人同时写入的 Web 服务不要硬上 SQLite，锁粒度太粗。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：数据量大了是不是必须换 NoSQL？&lt;/strong&gt;
A：绝大多数项目到不了这一步。关系型数据库加好索引、做好读写分离，支撑千万级数据很轻松。先优化，别先换架构。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;选型口诀：&lt;strong&gt;核心数据找关系型，PostgreSQL 功能强、MySQL 生态大；速度场景找 Redis，它是加速器不是仓库&lt;/strong&gt;。想清楚数据可靠性、查询复杂度、访问模式这三个问题，选型就不会大错。下一篇我们直接动手，用一份 Docker Compose 把三个数据库全部跑起来。&lt;/p&gt;
</content:encoded></item><item><title>用 Docker 快速搭建三大数据库：一份 Compose 全搞定</title><link>https://www.anexns.cloudns.org/posts/database-docker-quickstart/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/database-docker-quickstart/</guid><description>一份 docker-compose.yml 同时跑起 PostgreSQL 17、MySQL 8.4 和 Redis 7.4，包含数据持久化、健康检查、端口规划和连接验证全流程，十分钟拥有完整的本地数据库练功房。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;为什么用 Docker 装数据库&lt;/h2&gt;
&lt;p&gt;上一篇 &lt;a href=&quot;/posts/database-choosing-guide/&quot;&gt;《数据库怎么选》&lt;/a&gt; 讲完了三者的分工，接下来自然是把它们跑起来。传统装法要在系统里装三个服务、改三套配置、卸载还卸不干净；用 Docker 则是一份配置文件描述全部环境，&lt;code&gt;docker compose up -d&lt;/code&gt; 一条命令拉起，&lt;code&gt;docker compose down&lt;/code&gt; 一条命令清场，还不会污染宿主机。&lt;/p&gt;
&lt;p&gt;本文的目标：&lt;strong&gt;一份 Compose 文件同时跑 PostgreSQL 17、MySQL 8.4、Redis 7.4&lt;/strong&gt;，数据都持久化到命名卷，带健康检查，并逐个验证能连上。这套环境就是本系列后面所有篇目的实验场：&lt;a href=&quot;/posts/sql-basics-crud/&quot;&gt;《SQL 基础速成》&lt;/a&gt; 里的练习、&lt;a href=&quot;/posts/postgresql-install-config/&quot;&gt;《PostgreSQL 安装与初始配置》&lt;/a&gt; 里的调优，都会在它上面做。&lt;/p&gt;
&lt;p&gt;前置要求：宿主机已装好 Docker Engine 和 Docker Compose v2（&lt;code&gt;docker compose version&lt;/code&gt; 能输出版本号）。没装的先看本博客 Docker 系列的部署篇。&lt;/p&gt;
&lt;h2&gt;端口与规划&lt;/h2&gt;
&lt;p&gt;先把基本规划定下来，避免和宿主机已有服务冲突：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;服务&lt;/th&gt;
&lt;th&gt;镜像&lt;/th&gt;
&lt;th&gt;容器内端口&lt;/th&gt;
&lt;th&gt;宿主机端口&lt;/th&gt;
&lt;th&gt;数据库/账号规划&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;PostgreSQL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;postgres:17&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;5432&lt;/td&gt;
&lt;td&gt;5432&lt;/td&gt;
&lt;td&gt;库 &lt;code&gt;appdb&lt;/code&gt;，用户 &lt;code&gt;appuser&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MySQL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;mysql:8.4&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;3306&lt;/td&gt;
&lt;td&gt;3306&lt;/td&gt;
&lt;td&gt;库 &lt;code&gt;appdb&lt;/code&gt;，用户 &lt;code&gt;appuser&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Redis&lt;/td&gt;
&lt;td&gt;&lt;code&gt;redis:7.4&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;6379&lt;/td&gt;
&lt;td&gt;6379&lt;/td&gt;
&lt;td&gt;开启密码认证&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;如果宿主机上已经跑着同名服务占用了这些端口，把宿主机侧改成 15432、13306、16379 之类即可，容器内端口不要动。&lt;/p&gt;
&lt;p&gt;:::warning
本文的密码只是示例。任何要暴露到公网的数据库，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;必须改成强密码，并且不要把数据库端口直接对公网开放&lt;/strong&gt;&amp;lt;/span&amp;gt;；确需远程访问时，优先走内网、VPN 或 SSH 隧道，原因和做法在《MySQL 用户权限与安全管理》一篇里还会再强调。
:::&lt;/p&gt;
&lt;h2&gt;编写 Compose 文件&lt;/h2&gt;
&lt;p&gt;新建目录并写入 &lt;code&gt;docker-compose.yml&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/db-lab &amp;amp;&amp;amp; cd ~/db-lab
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;services:
  postgres:
    image: postgres:17
    container_name: lab-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: pg_password_123
      TZ: Asia/Shanghai
    ports:
      - &quot;127.0.0.1:5432:5432&quot;
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: [&quot;CMD-SHELL&quot;, &quot;pg_isready -U appuser -d appdb&quot;]
      interval: 5s
      timeout: 3s
      retries: 10

  mysql:
    image: mysql:8.4
    container_name: lab-mysql
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: mysql_root_123
      MYSQL_DATABASE: appdb
      MYSQL_USER: appuser
      MYSQL_PASSWORD: mysql_password_123
      TZ: Asia/Shanghai
    ports:
      - &quot;127.0.0.1:3306:3306&quot;
    volumes:
      - mysql_data:/var/lib/mysql
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
    healthcheck:
      test: [&quot;CMD&quot;, &quot;mysqladmin&quot;, &quot;ping&quot;, &quot;-h&quot;, &quot;localhost&quot;, &quot;-uroot&quot;, &quot;-pmysql_root_123&quot;]
      interval: 5s
      timeout: 3s
      retries: 15

  redis:
    image: redis:7.4
    container_name: lab-redis
    restart: unless-stopped
    ports:
      - &quot;127.0.0.1:6379:6379&quot;
    volumes:
      - redis_data:/data
    command: redis-server --appendonly yes --requirepass redis_password_123
    healthcheck:
      test: [&quot;CMD&quot;, &quot;redis-cli&quot;, &quot;-a&quot;, &quot;redis_password_123&quot;, &quot;ping&quot;]
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  pg_data:
  mysql_data:
  redis_data:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个关键点逐个说明：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;端口只绑 127.0.0.1&lt;/strong&gt;：写成 &lt;code&gt;&quot;127.0.0.1:5432:5432&quot;&lt;/code&gt; 后端口只对本机开放，局域网和公网都连不进来。省掉 IP 直接写 &lt;code&gt;&quot;5432:5432&quot;&lt;/code&gt; 等于绑到所有网卡，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;这是新手最常踩的坑，很多数据库被入侵都是因为这一步图省事&lt;/strong&gt;&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;数据必须进命名卷&lt;/strong&gt;：不挂卷的话容器一删数据全没。命名卷由 Docker 管理，&lt;code&gt;docker compose down&lt;/code&gt; 不带 &lt;code&gt;-v&lt;/code&gt; 时不会删除。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Redis 开了 AOF 和密码&lt;/strong&gt;：&lt;code&gt;--appendonly yes&lt;/code&gt; 让数据持久化到卷里，&lt;code&gt;--requirepass&lt;/code&gt; 设访问密码；持久化策略的取舍后面《Redis 持久化：RDB 与 AOF 怎么选》一篇专门讲。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;MySQL 字符集钉死 utf8mb4&lt;/strong&gt;：MySQL 历史上默认字符集存不下 emoji 和部分汉字，8.4 虽然默认已是 utf8mb4，显式写明可以避免被旧配置覆盖。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;环境变量只在首次初始化生效&lt;/strong&gt;：&lt;code&gt;POSTGRES_USER&lt;/code&gt;、&lt;code&gt;MYSQL_DATABASE&lt;/code&gt; 这类变量只在数据目录为空、第一次启动时执行。改密码、改库名不能靠改环境变量重启，得进数据库里改，或者删卷重建。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;启动与验证&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose ps
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;等十几秒到几十秒（MySQL 首次初始化最慢），&lt;code&gt;docker compose ps&lt;/code&gt; 里三个服务的 STATUS 都变成 &lt;code&gt;Up ... (healthy)&lt;/code&gt; 就说明健康检查全过。然后逐个验证连接：&lt;/p&gt;
&lt;p&gt;PostgreSQL：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec -it lab-postgres psql -U appuser -d appdb -c &quot;SELECT version();&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;MySQL：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec -it lab-mysql mysql -uappuser -p&apos;mysql_password_123&apos; -e &quot;SELECT VERSION();&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Redis：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec -it lab-redis redis-cli -a redis_password_123 PING
# 正常返回 PONG
docker exec -it lab-redis redis-cli -a redis_password_123 SET hello world
docker exec -it lab-redis redis-cli -a redis_password_123 GET hello
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三条都通，练功房就建好了。核心结论记住一句：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;Compose 管生命周期，命名卷管数据命根子，两者配合，删容器永远不等于删数据&lt;/strong&gt;&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h2&gt;日常管理命令&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;docker compose stop          # 停服务，数据保留
docker compose start         # 再启动
docker compose restart mysql # 只重启 MySQL
docker compose logs -f postgres  # 跟踪 PostgreSQL 日志
docker compose down          # 删容器和网络，卷保留
docker compose down -v       # 连卷一起删，数据清零，慎用
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;docker compose down -v&lt;/code&gt; 会把三个命名卷一并删除，&lt;strong&gt;所有数据库数据不可恢复&lt;/strong&gt;。执行前先确认这是你想要的，生产环境更要三思；正经备份的做法看 &lt;a href=&quot;/posts/database-backup-restore/&quot;&gt;《数据库备份与恢复全攻略》&lt;/a&gt;，删卷不是备份的替代品。
:::&lt;/p&gt;
&lt;h2&gt;排障：常见启动失败&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：容器一直 Restarting 或直接 Exited？&lt;/strong&gt;
A：先 &lt;code&gt;docker compose logs &amp;lt;服务名&amp;gt;&lt;/code&gt; 看日志。数据库容器起不来九成是三类原因：数据卷里已有旧版本数据（比如卷里是 PostgreSQL 15 的数据却用 17 的镜像，大版本之间数据目录不兼容）；环境变量缺失（MySQL 没给 &lt;code&gt;MYSQL_ROOT_PASSWORD&lt;/code&gt; 会直接拒绝初始化）；宿主机端口被占用（日志里会有 bind 相关报错，&lt;code&gt;ss -tlnp&lt;/code&gt; 一查便知）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：改了 Compose 里的密码，重启后旧密码还能连、新密码不行？&lt;/strong&gt;
A：这是上面说的「环境变量只在首次初始化生效」。卷里已经有初始化好的数据，后续启动直接跳过初始化。要么进库里用 SQL 改密码，要么 &lt;code&gt;docker compose down -v&lt;/code&gt; 删卷重来（数据清零）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：&lt;code&gt;docker compose ps&lt;/code&gt; 显示 unhealthy？&lt;/strong&gt;
A：先看日志确认服务本身是否正常。有时是服务已就绪但健康检查命令写错，比如 Redis 改了密码而 healthcheck 里的密码没同步。用 &lt;code&gt;docker exec&lt;/code&gt; 手动执行一遍 healthcheck 里的命令就能定位。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：宿主机上的客户端连不上，只能在容器里连？&lt;/strong&gt;
A：检查端口映射是否绑了 127.0.0.1（那就只能本机连，属预期行为）；再检查宿主机防火墙；最后确认连接用的端口是宿主机侧端口而不是容器内端口。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;一份 Compose 文件把 PostgreSQL、MySQL、Redis 三件套全拉了起来：命名卷保数据、健康检查报状态、端口只绑本机保安全。这套环境会贯穿整个数据库系列，下一篇就用它来练 SQL 的基本功。&lt;/p&gt;
</content:encoded></item><item><title>数据库性能监控与常见故障排障</title><link>https://www.anexns.cloudns.org/posts/database-monitoring-troubleshooting/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/database-monitoring-troubleshooting/</guid><description>数据库出问题时先看哪几个指标：PostgreSQL、MySQL、Redis 三家各自的核心监控命令与慢查询定位方法，再系统过一遍连接数打满、磁盘爆满、慢查询、复制延迟、内存溢出五大高频故障的排查路径。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;写在前面：排障先看指标，不要先猜&lt;/h2&gt;
&lt;p&gt;数据库报警或者业务喊慢的时候，新手的第一反应是重启，老手的第一反应是看数据。本文是数据库系列的收官篇，把三家数据库的日常监控要点和五大高频故障的排查路径汇总成一份速查手册：平时用它做巡检，出事时照着它一步步定位。&lt;/p&gt;
&lt;p&gt;先立一条通用原则：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;任何数据库问题，先看四个维度——连接、延迟、资源、错误日志&amp;lt;/span&amp;gt;。连接是不是被打满了，查询延迟是不是突增，CPU/内存/磁盘/IO 哪个到顶了，错误日志里有没有新报错。九成问题在这四步里就能定位到方向。监控不是装个面板看个热闹，核心是知道每个数字背后的含义和正常范围。&lt;/p&gt;
&lt;p&gt;还有个前提认知：宿主机层面的资源（磁盘空间、内存使用）要用系统命令看，数据库内部状态（谁在跑什么 SQL、锁在等什么）要用各家自己的视图看，两层结合才完整。&lt;code&gt;df -h&lt;/code&gt;、&lt;code&gt;free -h&lt;/code&gt;、&lt;code&gt;top&lt;/code&gt; 这老三样永远是第一步。&lt;/p&gt;
&lt;h2&gt;PostgreSQL：看活动会话与慢查询&lt;/h2&gt;
&lt;h3&gt;此刻谁在干什么：pg_stat_activity&lt;/h3&gt;
&lt;p&gt;这是 PostgreSQL 排障的第一命令，相当于数据库版的 &lt;code&gt;top&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 查看当前所有连接在执行什么
SELECT pid, usename, application_name, state, wait_event_type,
       now() - query_start AS duration, query
FROM pg_stat_activity
WHERE state != &apos;idle&apos;
ORDER BY duration DESC;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重点字段：&lt;code&gt;state&lt;/code&gt; 是 &lt;code&gt;active&lt;/code&gt;（执行中）还是 &lt;code&gt;idle in transaction&lt;/code&gt;（事务开着不提交，最常见的连接占用元凶）；&lt;code&gt;wait_event_type&lt;/code&gt; 为 &lt;code&gt;Lock&lt;/code&gt; 说明在等锁。发现某个查询卡了很久，可以先温和取消、再考虑杀连接：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SELECT pg_cancel_backend(pid);    -- 取消该会话正在执行的查询
SELECT pg_terminate_backend(pid); -- 直接断开整个连接（更狠，后手）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;连接数总览与上限：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SELECT count(*) FROM pg_stat_activity;       -- 当前连接数
SHOW max_connections;                        -- 上限（默认 100）
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;历史慢查询：pg_stat_statements&lt;/h3&gt;
&lt;p&gt;实时视图只能看当下，找「历史上最慢的 SQL」要装扩展 &lt;code&gt;pg_stat_statements&lt;/code&gt;（在 &lt;code&gt;postgresql.conf&lt;/code&gt; 里加 &lt;code&gt;shared_preload_libraries = &apos;pg_stat_statements&apos;&lt;/code&gt; 后重启，再执行 &lt;code&gt;CREATE EXTENSION pg_stat_statements;&lt;/code&gt;）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 按总耗时排序找最值得优化的 SQL
SELECT query, calls, total_exec_time, mean_exec_time, rows
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 10;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;配合慢日志双保险：把 &lt;code&gt;log_min_duration_statement = 1000&lt;/code&gt;（毫秒）打开，超过 1 秒的语句自动记进日志。定位出慢 SQL 之后怎么优化索引，去看 &lt;a href=&quot;/posts/postgresql-index-optimization/&quot;&gt;《PostgreSQL 索引与查询优化入门》&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;另外两个巡检点：&lt;strong&gt;长事务&lt;/strong&gt;会阻止垃圾回收导致表膨胀，用 &lt;code&gt;SELECT pid, now() - xact_start AS age FROM pg_stat_activity WHERE xact_start IS NOT NULL ORDER BY age DESC;&lt;/code&gt; 定期查；&lt;strong&gt;复制延迟&lt;/strong&gt;在备库上用 &lt;code&gt;SELECT now() - pg_last_xact_replay_timestamp() AS replay_lag;&lt;/code&gt; 查看，背景见 &lt;a href=&quot;/posts/database-replication-basics/&quot;&gt;《主从复制入门》&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;MySQL：看进程、慢日志与 Performance Schema&lt;/h2&gt;
&lt;h3&gt;实时状态：SHOW PROCESSLIST 与状态计数器&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;SHOW FULL PROCESSLIST;    -- 当前每个连接在执行什么、已运行多久
SHOW GLOBAL STATUS LIKE &apos;Threads_connected&apos;;   -- 当前连接数
SHOW VARIABLES LIKE &apos;max_connections&apos;;         -- 连接上限（默认 151）
SHOW GLOBAL STATUS LIKE &apos;Slow_queries&apos;;        -- 累计慢查询条数
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;SHOW FULL PROCESSLIST&lt;/code&gt; 里 State 列出现大量 &lt;code&gt;Waiting for ... lock&lt;/code&gt; 或某条 SQL 的 Time 值很大，方向就找到了。杀会话用 &lt;code&gt;KILL &amp;lt;Id&amp;gt;&lt;/code&gt;，先 &lt;code&gt;KILL QUERY &amp;lt;Id&amp;gt;&lt;/code&gt; 只杀语句不行再杀连接。&lt;/p&gt;
&lt;h3&gt;慢查询日志：定位慢 SQL 的主战场&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;[mysqld]
slow_query_log = ON
slow_query_log_file = /var/log/mysql/slow.log
long_query_time = 1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;开启后用官方工具 &lt;code&gt;mysqldumpslow&lt;/code&gt; 做聚合分析（按出现次数或总耗时排序），比肉眼翻日志高效得多：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mysqldumpslow -s t -t 10 /var/log/mysql/slow.log    # 总耗时最高的 10 条
mysqldumpslow -s c -t 10 /var/log/mysql/slow.log    # 出现次数最多的 10 条
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;更细的维度（某条 SQL 的锁等待、扫描行数分布）可以查 Performance Schema 的 &lt;code&gt;events_statements_summary_by_digest&lt;/code&gt; 视图，前提是该功能开启（MySQL 8.4 默认开）。找到慢 SQL 后的优化手段在 &lt;a href=&quot;/posts/mysql-index-slow-query/&quot;&gt;《MySQL 索引与慢查询优化》&lt;/a&gt; 里系统讲过，监控负责发现，优化负责根治，分工明确。&lt;/p&gt;
&lt;h3&gt;InnoDB 状态&lt;/h3&gt;
&lt;p&gt;引擎层面的锁等待、死锁、缓冲池命中情况看：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SHOW ENGINE INNODB STATUS\G
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出很长，重点看 &lt;code&gt;LATEST DETECTED DEADLOCK&lt;/code&gt;（最近一次死锁的双方 SQL）和 &lt;code&gt;TRANSACTIONS&lt;/code&gt; 段里长时间 &lt;code&gt;ACTIVE&lt;/code&gt; 的事务。死锁偶发一两次不用慌，频繁出现就要回去改业务的加锁顺序。&lt;/p&gt;
&lt;h2&gt;Redis：INFO 是总入口&lt;/h2&gt;
&lt;p&gt;Redis 的监控高度集中，一条 &lt;code&gt;INFO&lt;/code&gt; 命令给出全部关键指标，分段查看更清晰：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;redis-cli INFO stats         # 命令统计：总命令数、每秒命令数 instantaneous_ops_per_sec
redis-cli INFO memory        # 内存：used_memory_human、used_memory_rss、mem_fragmentation_ratio
redis-cli INFO clients       # 客户端：connected_clients、blocked_clients
redis-cli INFO persistence   # 持久化状态（见持久化那篇）
redis-cli INFO stats | grep keyspace_hits   # 缓存命中
redis-cli INFO stats | grep keyspace_misses # 缓存未命中
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个要盯紧的数字：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;命中率&lt;/strong&gt; = hits / (hits + misses)，长期低于 90% 说明缓存策略或容量有问题&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;mem_fragmentation_ratio&lt;/strong&gt;（内存碎片率），在 1.0–1.5 之间正常，超过 1.5 可以考虑开启自动碎片整理 &lt;code&gt;activedefrag yes&lt;/code&gt;，远小于 1 说明在用 swap，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Redis 一旦用上 swap 延迟会暴涨，必须处理&amp;lt;/span&amp;gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;evicted_keys&lt;/strong&gt;：被内存淘汰策略赶走的键数。持续增长说明内存不够用或 &lt;code&gt;maxmemory&lt;/code&gt; 设得太小，业务可能在悄悄丢缓存&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;blocked_clients&lt;/strong&gt;：卡在 &lt;code&gt;BLPOP&lt;/code&gt; 等阻塞命令上的客户端数，异常升高要查消费者&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;慢命令排查用内置慢日志：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CONFIG SET slowlog-log-slower-than 10000   # 记录执行超过 10 毫秒的命令（单位微秒）
SLOWLOG GET 10                             # 看最近 10 条慢命令
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;实时看命令流量可以用 &lt;code&gt;redis-cli MONITOR&lt;/code&gt;，但它会把每条命令都打印出来，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;生产环境高峰期开 MONITOR 本身就能把 Redis 拖慢&amp;lt;/span&amp;gt;，只适合短时间抓样本或低峰期使用。查大键用 &lt;code&gt;redis-cli --bigkeys&lt;/code&gt;，查内存热点键用 &lt;code&gt;redis-cli --memkeys&lt;/code&gt; 或 &lt;code&gt;MEMORY USAGE key&lt;/code&gt; 单个分析。&lt;/p&gt;
&lt;h2&gt;五大高频故障排查路径&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;故障现象&lt;/th&gt;
&lt;th&gt;先查什么&lt;/th&gt;
&lt;th&gt;常见根因&lt;/th&gt;
&lt;th&gt;处理方向&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;连接数打满，新连接报错&lt;/td&gt;
&lt;td&gt;各家的活动会话视图&lt;/td&gt;
&lt;td&gt;连接泄漏、长事务不提交、连接池配置过大&lt;/td&gt;
&lt;td&gt;杀僵尸会话、修应用连接释放、调大上限只是缓兵&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;磁盘空间爆满&lt;/td&gt;
&lt;td&gt;&lt;code&gt;df -h&lt;/code&gt; + 找大文件&lt;/td&gt;
&lt;td&gt;binlog/WAL 堆积、备份文件没清理、慢日志无限增长&lt;/td&gt;
&lt;td&gt;清理与轮转策略、归档改到其他盘、扩容&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;突然变慢&lt;/td&gt;
&lt;td&gt;慢查询视图 + &lt;code&gt;top&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;新上线的全表扫描 SQL、统计信息过期、IO 被其他进程抢占&lt;/td&gt;
&lt;td&gt;加索引/改 SQL、更新统计信息、隔离资源&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;主从延迟飙升&lt;/td&gt;
&lt;td&gt;复制状态视图&lt;/td&gt;
&lt;td&gt;大事务、从库硬件弱、网络抖动&lt;/td&gt;
&lt;td&gt;拆大事务、从库扩容、强一致读切回主库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Redis 内存溢出/被杀&lt;/td&gt;
&lt;td&gt;&lt;code&gt;INFO memory&lt;/code&gt;、系统日志&lt;/td&gt;
&lt;td&gt;没设 &lt;code&gt;maxmemory&lt;/code&gt;、大键写入、内存泄漏型用法&lt;/td&gt;
&lt;td&gt;设上限＋淘汰策略、拆大键&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;逐条展开最要命的两个：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;连接数打满&lt;/strong&gt;。报错通常是 PostgreSQL 的 &lt;code&gt;too many clients already&lt;/code&gt; 或 MySQL 的 &lt;code&gt;Too many connections&lt;/code&gt;。先用活动会话视图看连接都是谁、什么状态：如果大量 &lt;code&gt;idle in transaction&lt;/code&gt;（PG）或 &lt;code&gt;Sleep&lt;/code&gt;（MySQL），基本是应用没正确释放连接或事务没提交。临时救急可以杀掉空闲时间最长的会话腾出名额，但&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要第一反应就调大 max_connections&amp;lt;/span&amp;gt;——连接数翻倍意味着内存和调度开销翻倍，掩盖泄漏只会让下次爆得更惨。正解是修应用＋上连接池（如 PgBouncer）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;磁盘爆满&lt;/strong&gt;。数据库对磁盘满的反应都很剧烈：轻则拒绝写入，重则进程崩溃。排查用 &lt;code&gt;du -sh&lt;/code&gt; 逐层找大头，数据库机器上常见的三大户是：日志类（binlog、WAL、慢日志）、备份文件、数据文件本身。预防靠策略：binlog 设过期天数（见 &lt;a href=&quot;/posts/database-backup-restore/&quot;&gt;《数据库备份与恢复全攻略》&lt;/a&gt;）、日志做轮转、磁盘使用率超过 80% 就告警，别等 100% 才知道。&lt;/p&gt;
&lt;p&gt;:::warning
排障时最忌讳「没留现场就重启」。重启能解决一部分问题，但会把活动会话、锁等待、错误上下文全部清掉，根因永远查不出来，下次还会再犯。正确顺序是：先截图留存关键视图输出（活动会话、状态变量、错误日志尾部），再做处置，重启永远是最后选项。
:::&lt;/p&gt;
&lt;h2&gt;指标速查表&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;指标&lt;/th&gt;
&lt;th&gt;PostgreSQL&lt;/th&gt;
&lt;th&gt;MySQL&lt;/th&gt;
&lt;th&gt;Redis&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;当前连接&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pg_stat_activity&lt;/code&gt; 计数&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Threads_connected&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;connected_clients&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;正在执行的 SQL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pg_stat_activity&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;SHOW FULL PROCESSLIST&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;CLIENT LIST&lt;/code&gt;（看 cmd 列）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;历史慢查询&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pg_stat_statements&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;慢日志 + &lt;code&gt;mysqldumpslow&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;SLOWLOG GET&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;复制延迟&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pg_last_xact_replay_timestamp()&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Seconds_Behind_Source&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;INFO replication&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;内存/容量&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pg_database_size()&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;information_schema.tables&lt;/code&gt; 算库大小&lt;/td&gt;
&lt;td&gt;&lt;code&gt;INFO memory&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;锁等待&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pg_locks&lt;/code&gt;（granted = false）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;SHOW ENGINE INNODB STATUS&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;无锁概念，看 &lt;code&gt;blocked_clients&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：要不要上 Prometheus + Grafana 做监控面板？&lt;/strong&gt;
数据量和机器数少时，各家自带命令完全够用，先把命令练熟。机器上了规模（比如 5 台以上数据库）再上 Prometheus 导出器（postgres_exporter、mysqld_exporter、redis_exporter）＋Grafana 面板做统一看板和告警，顺序不要反：不懂指标含义，面板再漂亮也只是装饰。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：慢日志文件本身变得很大怎么办？&lt;/strong&gt;
说明慢查询量不小，先解决问题再谈文件。文件处理上，MySQL 可以 &lt;code&gt;SET GLOBAL slow_query_log = OFF&lt;/code&gt; 后轮转再打开，或用系统 logrotate 管理；根本上要把慢 SQL 逐条优化掉，慢日志应该越记越薄才对。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：业务说慢，但数据库各项指标都正常？&lt;/strong&gt;
那就往外查：网络延迟、应用服务器资源、连接池等待、DNS 解析。数据库的 &lt;code&gt;duration&lt;/code&gt; 统计的是库内执行时间，应用感知的耗时还包括排队和网络。用同一条 SQL 在数据库本机直连测一次、从应用机测一次，对比就知道时间花在哪一段了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：Redis 的 used_memory 超过 maxmemory 会怎样？&lt;/strong&gt;
取决于淘汰策略 &lt;code&gt;maxmemory-policy&lt;/code&gt;：默认 &lt;code&gt;noeviction&lt;/code&gt; 是拒绝写入并报错；缓存场景一般设 &lt;code&gt;allkeys-lru&lt;/code&gt; 或 &lt;code&gt;volatile-lru&lt;/code&gt; 自动淘汰冷数据。报错 &lt;code&gt;OOM command not allowed&lt;/code&gt; 就是撞上了 noeviction 的上限，先查是不是忘了改策略。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：监控多久巡检一次合适？&lt;/strong&gt;
关键指标（连接数、延迟、磁盘、复制状态）建议自动化每分钟采集＋阈值告警；人工巡检每周扫一遍慢查询 Top 10 和容量趋势就够了。容量趋势最容易被忽视：磁盘和数据量是线性增长的，看趋势能提前几周预知爆盘日期。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;监控排障的功夫在平时：熟悉三家的活动视图和慢查询入口，知道每个核心指标的正常范围，出事时按「连接、延迟、资源、日志」四步走，留好现场再处置。至此数据库系列 18 篇全部完成：从&lt;a href=&quot;/posts/database-choosing-guide/&quot;&gt;选型&lt;/a&gt;、&lt;a href=&quot;/posts/database-docker-quickstart/&quot;&gt;Docker 快速搭建&lt;/a&gt;，到 PostgreSQL、MySQL、Redis 三家的安装、权限、命令、优化与持久化，再到备份、复制、监控的通用运维体系。把这套东西在自己的服务器上跑一遍，你的数据库基本功就成型了。&lt;/p&gt;
</content:encoded></item><item><title>主从复制入门：PostgreSQL 与 MySQL 各搭一套</title><link>https://www.anexns.cloudns.org/posts/database-replication-basics/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/database-replication-basics/</guid><description>主从复制从原理到动手：PostgreSQL 流复制用 pg_basebackup 拉起从库，MySQL 用 GTID 模式配置主从，附延迟查看、只读设置、故障切换的基本思路和常见报错排查，两套都能照着搭出来。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;写在前面：复制解决的不是备份问题&lt;/h2&gt;
&lt;p&gt;先把一个观念摆正：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;主从复制不是备份&amp;lt;/span&amp;gt;。你在主库执行一条没带 WHERE 的 &lt;code&gt;DELETE&lt;/code&gt;，这条语句会毫秒级同步到从库，两边一起删干净——这正是上一篇 &lt;a href=&quot;/posts/database-backup-restore/&quot;&gt;《数据库备份与恢复全攻略》&lt;/a&gt; 里强调过的事。&lt;/p&gt;
&lt;p&gt;那复制解决什么？两件事：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;高可用&lt;/strong&gt;：主库宕机时，可以把从库提升为新主库继续提供服务，停机时间从「恢复备份的几小时」缩短到「切换的几分钟」&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;读写分离&lt;/strong&gt;：写请求走主库，读请求分一部分到从库，给主库减负&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;原理上两家是同一个模型：主库把数据变更记录成日志（PostgreSQL 叫 WAL，MySQL 叫 binlog），从库把日志拉过来重放一遍，于是数据追上主库。本文带你把 PostgreSQL 流复制和 MySQL GTID 复制各搭一套出来，都用两台机器（或两台 VPS、两个 Docker 容器）演示。假设主库 IP 是 &lt;code&gt;192.168.1.10&lt;/code&gt;，从库 IP 是 &lt;code&gt;192.168.1.11&lt;/code&gt;，请按你的实际环境替换。单机安装与初始配置分别见 &lt;a href=&quot;/posts/postgresql-install-config/&quot;&gt;《PostgreSQL 安装与初始配置》&lt;/a&gt; 和 &lt;a href=&quot;/posts/mysql-install-config/&quot;&gt;《MySQL 安装与初始配置》&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;PostgreSQL 流复制&lt;/h2&gt;
&lt;h3&gt;原理一句话&lt;/h3&gt;
&lt;p&gt;主库持续产生 WAL 日志，从库通过一条长连接实时把 WAL 拉过来重放，这就是流复制（Streaming Replication），默认异步：主库不等从库确认就返回写入成功，极端情况下主库宕机可能丢最后一点未同步的数据。&lt;/p&gt;
&lt;h3&gt;第一步：主库准备&lt;/h3&gt;
&lt;p&gt;在主库创建专用复制用户：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE USER repuser WITH REPLICATION ENCRYPTED PASSWORD &apos;强密码&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;修改 &lt;code&gt;postgresql.conf&lt;/code&gt;（关键项）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;listen_addresses = &apos;*&apos;        # 允许从库连进来（配合防火墙收紧来源）
wal_level = replica           # 默认就是 replica，确认一下即可
max_wal_senders = 5           # 最多允许几个从库同时拉日志
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;在 &lt;code&gt;pg_hba.conf&lt;/code&gt; 里放行从库的复制连接：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;host    replication    repuser    192.168.1.11/32    scram-sha-256
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改完重启主库：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl restart postgresql
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第二步：从库用 pg_basebackup 初始化&lt;/h3&gt;
&lt;p&gt;从库上先停掉自带的空实例、清掉数据目录，然后从主库拉一份基础数据：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl stop postgresql
sudo -u postgres rm -rf /var/lib/postgresql/17/main/*

sudo -u postgres pg_basebackup \
  -h 192.168.1.10 -U repuser \
  -D /var/lib/postgresql/17/main \
  -Fp -Xs -P -R
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个关键参数：&lt;code&gt;-Xs&lt;/code&gt; 表示备份的同时以流方式把期间的 WAL 一起带过来，避免数据不一致；&lt;code&gt;-R&lt;/code&gt; 是灵魂参数，它会自动在数据目录里写好 &lt;code&gt;postgresql.auto.conf&lt;/code&gt; 的连接信息并创建一个 &lt;code&gt;standby.signal&lt;/code&gt; 标记文件——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;有 standby.signal，这个实例启动后就知道自己是备库&amp;lt;/span&amp;gt;。执行时会提示输入 repuser 的密码，想免交互可以把密码写进 &lt;code&gt;~/.pgpass&lt;/code&gt; 文件（权限必须 600）。&lt;/p&gt;
&lt;p&gt;拉完直接启动从库：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl start postgresql
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第三步：验证复制状态&lt;/h3&gt;
&lt;p&gt;主库上查从库连接情况：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SELECT client_addr, state, sync_state FROM pg_stat_replication;
-- 出现一行 state = streaming、sync_state = async 就是正常工作
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;从库上确认自己是备库状态：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SELECT pg_is_in_recovery();   -- 返回 t（true）说明处于恢复/备库模式
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再做个冒烟测试：主库建表插一行数据，从库立刻能查到，复制就通了。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 主库
CREATE TABLE repl_test (id int, note text);
INSERT INTO repl_test VALUES (1, &apos;hello&apos;);
-- 从库
SELECT * FROM repl_test;      -- 能查到 hello 即成功
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;MySQL 基于 GTID 的复制&lt;/h2&gt;
&lt;h3&gt;原理一句话&lt;/h3&gt;
&lt;p&gt;MySQL 复制经历过「文件＋位置」和「GTID」两个时代。GTID（全局事务标识）给每个事务发一个全网唯一的编号，从库只要告诉主库「我执行到哪个 GTID 了」，主库就知道该补发哪些事务，不用再人工对 binlog 文件名和偏移量。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;新部署一律用 GTID 模式&amp;lt;/span&amp;gt;，老式位点模式只在维护存量系统时才会碰到。&lt;/p&gt;
&lt;h3&gt;第一步：主库配置&lt;/h3&gt;
&lt;p&gt;编辑主库 &lt;code&gt;my.cnf&lt;/code&gt; 的 &lt;code&gt;[mysqld]&lt;/code&gt; 段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[mysqld]
server_id = 1
log_bin = mysql-bin
gtid_mode = ON
enforce_gtid_consistency = ON
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;创建复制专用账号并授权（MySQL 8.4 语法）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE USER &apos;repl&apos;@&apos;192.168.1.11&apos; IDENTIFIED BY &apos;强密码&apos;;
GRANT REPLICATION SLAVE ON *.* TO &apos;repl&apos;@&apos;192.168.1.11&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改完配置重启主库，然后把存量数据导一份到从库（空库对空库可以跳过这步）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mysqldump -u root -p --single-transaction --source-data=2 --all-databases &amp;gt; full.sql
# 把 full.sql 传到从库并导入
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第二步：从库配置并启动复制&lt;/h3&gt;
&lt;p&gt;从库 &lt;code&gt;my.cnf&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[mysqld]
server_id = 2
gtid_mode = ON
enforce_gtid_consistency = ON
relay_log = mysql-relay-bin
read_only = ON
super_read_only = ON
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;server_id&lt;/code&gt; 全网唯一，主从不能相同——这是新手最常犯的错误之一。&lt;code&gt;read_only&lt;/code&gt;＋&lt;code&gt;super_read_only&lt;/code&gt; 把从库锁成只读，防止有人误连从库写入造成数据分叉。&lt;/p&gt;
&lt;p&gt;重启从库后，配置复制源并启动（MySQL 8.4 推荐用 SOURCE 而不是旧的 MASTER 术语）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CHANGE REPLICATION SOURCE TO
  SOURCE_HOST = &apos;192.168.1.10&apos;,
  SOURCE_USER = &apos;repl&apos;,
  SOURCE_PASSWORD = &apos;强密码&apos;,
  SOURCE_AUTO_POSITION = 1;

START REPLICA;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;SOURCE_AUTO_POSITION = 1&lt;/code&gt; 就是开启 GTID 自动定位，从库自己算缺哪些事务，不用填日志文件名和位置。&lt;/p&gt;
&lt;h3&gt;第三步：验证状态&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;SHOW REPLICA STATUS\G
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重点看三行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Replica_IO_Running: Yes        -- 拉日志的线程正常
Replica_SQL_Running: Yes       -- 重放日志的线程正常
Seconds_Behind_Source: 0       -- 延迟秒数，0 表示已追平
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个线程都是 Yes 且延迟为 0，再在主库写一行、从库查一遍，MySQL 这套就搭好了。&lt;/p&gt;
&lt;p&gt;:::warning
搭复制时最容易被忽略的是网络安全：复制连接传输的是数据库的全部变更数据，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把复制端口直接暴露在公网&amp;lt;/span&amp;gt;。主从之间优先走内网或 VPN 通道，防火墙只放行从库 IP 访问主库的 5432/3306 端口，复制账号也要用强密码并限定来源 IP，和前面配置里写的一样，不要为了图省事授权给 &lt;code&gt;%&lt;/code&gt; 或 &lt;code&gt;0.0.0.0/0&lt;/code&gt;。
:::&lt;/p&gt;
&lt;h2&gt;两家复制方式对比&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;PostgreSQL 流复制&lt;/th&gt;
&lt;th&gt;MySQL GTID 复制&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;同步的日志&lt;/td&gt;
&lt;td&gt;WAL&lt;/td&gt;
&lt;td&gt;binlog&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;从库初始化&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pg_basebackup&lt;/code&gt; 一条命令拉全量&lt;/td&gt;
&lt;td&gt;先导全量数据，再启动复制线程&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;位点管理&lt;/td&gt;
&lt;td&gt;自动（LSN）&lt;/td&gt;
&lt;td&gt;GTID 自动定位&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;状态查看&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pg_stat_replication&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;SHOW REPLICA STATUS&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;默认模式&lt;/td&gt;
&lt;td&gt;异步（可配同步）&lt;/td&gt;
&lt;td&gt;异步（可配半同步）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;从库可读&lt;/td&gt;
&lt;td&gt;可以（热备模式默认可查）&lt;/td&gt;
&lt;td&gt;可以（建议开只读锁防误写）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;主从延迟与故障切换的基本思路&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;延迟&lt;/strong&gt;是异步复制的固有现象：主库写入高峰、从库机器性能差、大事务（如一次更新百万行）都会让从库落后。延迟的查看方式两家都在上文给出了。延迟几秒对读写分离的读请求意味着可能读到旧数据，所以「写完立刻读」的关键路径（如支付后查订单）应强制走主库，这是读写分离落地的第一原则。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;故障切换&lt;/strong&gt;（主库宕机时）的手工流程，两家通用：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;确认主库真的不可用（别被网络抖动误判，否则会出现双主脑裂）&lt;/li&gt;
&lt;li&gt;等待从库把已收到的日志重放完（PostgreSQL 看 &lt;code&gt;pg_last_wal_replay_lsn&lt;/code&gt;，MySQL 看状态里的已执行 GTID 追平）&lt;/li&gt;
&lt;li&gt;提升从库：PostgreSQL 执行 &lt;code&gt;pg_ctl promote&lt;/code&gt; 或 &lt;code&gt;SELECT pg_promote();&lt;/code&gt;；MySQL 执行 &lt;code&gt;STOP REPLICA; SET GLOBAL read_only = OFF; SET GLOBAL super_read_only = OFF;&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;把应用连接指向新主库&lt;/li&gt;
&lt;li&gt;老主库修好后，只能作为新主库的从库重新加入（数据要重新同步），&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝不能直接让它复活继续当主&amp;lt;/span&amp;gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;生产环境一般会用 Patroni（PostgreSQL）或 Orchestrator/MHA（MySQL）做自动故障转移，但手工流程必须先懂，自动化工具出问题时才知道它在干什么。&lt;/p&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：MySQL &lt;code&gt;SHOW REPLICA STATUS&lt;/code&gt; 报 Last_IO_Error: 1236 或连接失败？&lt;/strong&gt;
1236 通常是主库 binlog 已被清理、从库要的日志不存在，只能重新导全量再搭。连接失败则依次查：网络是否通、复制账号的授权 IP 是否写对、主库防火墙是否放行 3306、密码是否正确。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：PostgreSQL 从库启动失败，日志说找不到 WAL 文件？&lt;/strong&gt;
多半是主库的 WAL 已经被回收了（从库停机太久）。解决办法是重新跑一次 &lt;code&gt;pg_basebackup&lt;/code&gt; 初始化；长期对策是给主库设置复制槽（replication slot），主库会为主库未消费的 WAL 保留到从库追上为止，但要注意槽会让 WAL 无限堆积撑爆磁盘，需要监控。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：从库延迟越来越大怎么办？&lt;/strong&gt;
先定位是拉日志慢（网络/主库压力）还是重放慢（从库 CPU、磁盘或大事务）。MySQL 8.4 默认开启多线程重放，一般够用；大事务是延迟杀手，业务上把批量更新拆小。从库硬件不要比主库差太多，这是最常见的根因。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：一主多从可以吗？&lt;/strong&gt;
可以，两家都支持一个主库挂多个从库。PostgreSQL 还支持级联复制（从库再带从库）。从库数量上去后注意主库的连接与带宽压力。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：Docker 环境能搭主从吗？&lt;/strong&gt;
能，两个容器加一个自定义网络即可，流程和物理机一模一样，初始化数据的那篇 &lt;a href=&quot;/posts/database-docker-quickstart/&quot;&gt;《用 Docker 快速搭建三大数据库》&lt;/a&gt; 可以作为单机起点。注意容器重建后 IP 可能变化，连接配置里尽量用容器名。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;主从复制的骨架两家是一样的：主库记日志、从库拉日志重放。PostgreSQL 靠 &lt;code&gt;pg_basebackup -R&lt;/code&gt; 一条命令拉起备库，MySQL 靠 GTID 把位点管理自动化。搭好之后记住三件事：复制不等于备份，两者要并行存在；读写分离时强一致读走主库；切换流程先在测试环境演练一遍，真出故障时才不至于手忙脚乱。下一篇是本系列收官——&lt;a href=&quot;/posts/database-monitoring-troubleshooting/&quot;&gt;《数据库性能监控与常见故障排障》&lt;/a&gt;，讲怎么盯住这些数据库的健康状态。&lt;/p&gt;
</content:encoded></item><item><title>BuildKit 与构建缓存进阶</title><link>https://www.anexns.cloudns.org/posts/docker-buildkit-cache/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-buildkit-cache/</guid><description>把镜像构建速度拉满：BuildKit 的并行构建与进度输出、RUN 缓存挂载、构建密钥 secret 挂载、注册表远程缓存的导出与导入，以及构建缓存的清理与排障。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;在 &lt;a href=&quot;/posts/dockerfile-guide/&quot;&gt;《Dockerfile 入门：把自己的应用打包成镜像》&lt;/a&gt; 里，我们已经用「先 COPY 依赖清单、再 COPY 源码」的办法吃到了第一口缓存红利：改业务代码时不用重装依赖。但真实项目里，构建慢的大头往往不在源码层，而在依赖本身——&lt;code&gt;apt-get install&lt;/code&gt; 每次都要重新下载几百 MB 的包，&lt;code&gt;pip install&lt;/code&gt; 在 CI 上一遍遍拉同样的 wheel，换一台机器构建更是从零开始。这一篇就把构建这件事讲透：主角是 Docker 现在的默认构建引擎 BuildKit，内容包括它的并行构建模型、RUN 缓存挂载、构建密钥挂载、注册表远程缓存，最后是缓存的管理与排障。读完之后，你应该能把一个「每次构建 8 分钟」的项目压到 1 分钟以内，而且在 CI 和同事的机器上同样快。&lt;/p&gt;
&lt;h2&gt;BuildKit 是什么：默认引擎早已换代&lt;/h2&gt;
&lt;p&gt;BuildKit 是 Docker 官方的第二代构建引擎，从 Docker 18.09 起就可以通过环境变量开启，到 &lt;strong&gt;Docker 23.0 起，&lt;code&gt;docker build&lt;/code&gt; 已经默认走 BuildKit&lt;/strong&gt;，旧构建器（legacy builder）被标记为弃用。所以只要你的 Docker 不是太老，你其实一直在用 BuildKit，只是可能还没用上它的进阶能力。&lt;/p&gt;
&lt;p&gt;它和旧构建器最核心的区别有三点：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;旧构建器（legacy）&lt;/th&gt;
&lt;th&gt;BuildKit&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;执行模型&lt;/td&gt;
&lt;td&gt;严格按 Dockerfile 从上到下逐条执行&lt;/td&gt;
&lt;td&gt;先把 Dockerfile 解析成依赖图（DAG），无依赖关系的步骤&lt;strong&gt;并行执行&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;多阶段构建&lt;/td&gt;
&lt;td&gt;每个阶段都会完整构建，哪怕最后没用到&lt;/td&gt;
&lt;td&gt;只构建最终镜像真正依赖的阶段和层，&lt;strong&gt;无用阶段直接跳过&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;构建输出&lt;/td&gt;
&lt;td&gt;一条条滚动日志，出错难定位&lt;/td&gt;
&lt;td&gt;树状进度视图，哪个阶段在跑、哪个在等缓存一目了然&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;扩展能力&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;缓存挂载、密钥挂载、SSH 挂载、远程缓存、多平台构建&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;前端语法&lt;/td&gt;
&lt;td&gt;跟随 Docker 版本&lt;/td&gt;
&lt;td&gt;可用 &lt;code&gt;# syntax=&lt;/code&gt; 指令单独指定 Dockerfile 前端版本&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;并行执行带来的收益在多阶段构建里最明显：一个阶段在编译 Go 程序、另一个阶段在拉 Node 依赖，两条线同时跑，互不等待。旧构建器只能排队。&lt;/p&gt;
&lt;h3&gt;切换进度输出：排查构建问题先开 plain&lt;/h3&gt;
&lt;p&gt;BuildKit 默认的进度输出是给人看的交互式视图（tty 模式），在 CI 日志里会变成一堆刷新控制符，想看完整的每步日志时反而碍事。两种改法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 单次构建：命令行参数
docker build --progress=plain -t myapp .

# 长期生效：环境变量
export BUILDKIT_PROGRESS=plain
docker build -t myapp .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--progress&lt;/code&gt; 可选值有 &lt;code&gt;auto&lt;/code&gt;（默认）、&lt;code&gt;tty&lt;/code&gt;、&lt;code&gt;plain&lt;/code&gt;。构建排障时一律先切 &lt;code&gt;plain&lt;/code&gt;，每条指令的完整输出都会顺序打出来，哪一步失败、失败前执行了什么，一清二楚。&lt;/p&gt;
&lt;h3&gt;Dockerfile 第一行：# syntax 指令&lt;/h3&gt;
&lt;p&gt;从这一篇开始，所有 Dockerfile 的第一行都建议这样写：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# syntax=docker/dockerfile:1
FROM python:3.12-slim
# ...
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这一行不是注释摆设，它的作用是&lt;strong&gt;指定解析这份 Dockerfile 的前端（frontend）版本&lt;/strong&gt;。BuildKit 会按需拉取 &lt;code&gt;docker/dockerfile:1&lt;/code&gt; 这个前端镜像来解析语法，好处是：新语法（比如缓存挂载、密钥挂载）由前端版本决定，不必为了用一个新特性去升级整台机器的 Docker；同一份 Dockerfile 在不同机器上构建行为一致。注意它必须写在文件最前面，前面只能有解析器指令和空行，写到中间就只是普通注释了。&lt;/p&gt;
&lt;h2&gt;RUN 缓存挂载：让依赖下载只发生一次&lt;/h2&gt;
&lt;p&gt;这是 BuildKit 最实用的特性，没有之一。先说清它和普通层缓存的区别：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;层缓存&lt;/strong&gt;：指令和输入都没变时，整层直接复用。但只要这一层需要重新执行（比如依赖清单变了），层里的一切都要重来——&lt;code&gt;pip install&lt;/code&gt; 就得把所有包重新下载一遍。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;缓存挂载（cache mount）&lt;/strong&gt;：给 RUN 指令挂一个&lt;strong&gt;持久化目录&lt;/strong&gt;，这个目录不属于任何镜像层，构建结束后保留在 BuildKit 的缓存区里，下次构建同一条 RUN 时原样挂回来。依赖清单只新增了一个包时，包管理器只需要下载那一个，其余全从缓存目录里现成拿。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;一句话概括：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;层缓存省的是「整层重做」，缓存挂载省的是「重做时还要重复下载」&amp;lt;/span&amp;gt;，两者叠加才是完整的提速。&lt;/p&gt;
&lt;h3&gt;实战一：给 pip 挂缓存&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# syntax=docker/dockerfile:1
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt
COPY . .
CMD [&quot;python&quot;, &quot;app.py&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;pip&lt;/code&gt; 默认会把下载过的 wheel 存进 &lt;code&gt;/root/.cache/pip&lt;/code&gt;，下次装同样的包直接用本地缓存、不走网络——但普通构建里这一层一旦失效，缓存目录就随层一起没了。加上 &lt;code&gt;--mount=type=cache,target=/root/.cache/pip&lt;/code&gt; 之后，这个目录由 BuildKit 在镜像之外单独保管：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;第一次构建：正常下载，wheel 落进缓存挂载；&lt;/li&gt;
&lt;li&gt;改了源码重新构建：&lt;code&gt;pip install&lt;/code&gt; 这一层可能因为上下文变化重跑，但包全在缓存里，秒过；&lt;/li&gt;
&lt;li&gt;往 requirements.txt 里加一个新包：只有新包需要下载，其余命中缓存。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;实战二：给 apt 挂缓存（有个坑要先填）&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# syntax=docker/dockerfile:1
FROM debian:bookworm-slim
RUN rm -f /etc/apt/apt.conf.d/docker-clean \
    &amp;amp;&amp;amp; apt-get update \
    &amp;amp;&amp;amp; apt-get install -y --no-install-recommends curl ca-certificates
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;先解释第一行那个坑：Debian / Ubuntu 官方镜像里有个 apt 配置 &lt;code&gt;docker-clean&lt;/code&gt;，它让 apt 在每次安装结束后&lt;strong&gt;自动删掉下载的 .deb 缓存包&lt;/strong&gt;——这是为了减小镜像体积，但正好把我们想保留的缓存清光了。所以用缓存挂载前必须先删掉它。然后正式挂载：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# syntax=docker/dockerfile:1
FROM debian:bookworm-slim
RUN rm -f /etc/apt/apt.conf.d/docker-clean
RUN --mount=type=cache,target=/var/cache/apt/archives \
    --mount=type=cache,target=/var/lib/apt/lists \
    apt-get update \
    &amp;amp;&amp;amp; apt-get install -y --no-install-recommends curl ca-certificates
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个目录都要挂：&lt;code&gt;/var/cache/apt/archives&lt;/code&gt; 存下载的 .deb 包，&lt;code&gt;/var/lib/apt/lists&lt;/code&gt; 存 &lt;code&gt;apt-get update&lt;/code&gt; 拉来的软件包索引，少挂哪个都会多走一遍网络。&lt;/p&gt;
&lt;p&gt;:::warning
删掉 &lt;code&gt;docker-clean&lt;/code&gt; 并挂载缓存目录后，.deb 包不会再被清掉——但它们在缓存挂载里，&lt;strong&gt;不会进入最终镜像层&lt;/strong&gt;，镜像体积不受影响。这正是缓存挂载和「把缓存 COPY 进镜像」的区别，别担心镜像变大。
:::&lt;/p&gt;
&lt;h3&gt;cache 挂载的常用参数&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;target&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器内的挂载路径&lt;/td&gt;
&lt;td&gt;必填，如 &lt;code&gt;target=/root/.cache/pip&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;id&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;缓存的标识名&lt;/td&gt;
&lt;td&gt;不写时默认用 target 路径生成；多个 Dockerfile 想共享同一份缓存时，显式写相同的 &lt;code&gt;id&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;sharing&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;并发共享策略&lt;/td&gt;
&lt;td&gt;&lt;code&gt;shared&lt;/code&gt;（默认，多构建可同时读）/ &lt;code&gt;locked&lt;/code&gt;（同一时间只允许一个构建写）/ &lt;code&gt;private&lt;/code&gt;（每个构建独立一份）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;mode&lt;/code&gt;、&lt;code&gt;uid&lt;/code&gt;、&lt;code&gt;gid&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;权限设置&lt;/td&gt;
&lt;td&gt;一般用不到，缓存目录权限不对导致写入失败时再考虑&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;id&lt;/code&gt; 的典型用法：项目里有两份 Dockerfile（应用一份、定时任务一份），都装同一批系统包，给两边的 apt 缓存写上相同的 &lt;code&gt;id=apt-cache&lt;/code&gt;，就能共用一份缓存，而不是各存一份。&lt;/p&gt;
&lt;p&gt;再补一个并发的坑：apt 和 dpkg 本身对缓存目录有文件锁，多个构建同时写同一份缓存时偶尔会撞锁报错。遇到这种情况，把对应挂载改成 &lt;code&gt;sharing=locked&lt;/code&gt;，让构建排队独占写入，慢一点但稳：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;RUN --mount=type=cache,target=/var/cache/apt/archives,sharing=locked \
    apt-get update &amp;amp;&amp;amp; apt-get install -y curl
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;其他两种挂载：bind 与 tmpfs&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;--mount&lt;/code&gt; 不只有 cache，顺带把另外两个常用的讲清：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;bind 挂载&lt;/strong&gt;：构建时把构建上下文（或某个构建阶段）里的文件临时挂进 RUN 的环境，用完即走，不产生层。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 从名为 build 的阶段里，只取编译产物做校验，不把整个阶段拷进来
RUN --mount=type=bind,from=build,source=/out/app,target=/tmp/app \
    /tmp/app --version
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;最常见的场景是多阶段构建中「借用」前一阶段的文件执行某个命令（跑一次测试、生成校验和），比先 &lt;code&gt;COPY --from&lt;/code&gt; 落一层再删掉干净得多。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;tmpfs 挂载&lt;/strong&gt;：挂一块内存盘，构建结束即消失，适合放编译中间文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;RUN --mount=type=tmpfs,target=/tmp/build \
    make -C /src BUILD_DIR=/tmp/build
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;中间产物既不进镜像层、也不进缓存区，纯粹借内存加速 IO。日常用得不多，知道有这个选项即可。&lt;/p&gt;
&lt;h2&gt;构建密钥：secret 挂载，别再把密码写进 Dockerfile&lt;/h2&gt;
&lt;p&gt;构建时经常需要凭据：拉私有 Git 仓库、从私有 PyPI / npm 源装包、调需要 Token 的 API。老办法是写进 &lt;code&gt;ARG&lt;/code&gt; 或 &lt;code&gt;ENV&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 反面教材，千万别这么干
ARG GITHUB_TOKEN
RUN git clone https://oauth2:${GITHUB_TOKEN}@github.com/myorg/private-repo.git
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这为什么危险，在 &lt;a href=&quot;/posts/docker-security-resources/&quot;&gt;《Docker 安全与资源限制实战》&lt;/a&gt; 里讲过一遍，这里再钉死结论：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;写进 ARG / ENV 的密钥会留在镜像元数据里，任何人拿到镜像用 docker history 和 inspect 就能读出来&amp;lt;/span&amp;gt;，等于把密码印在包裹上寄出去。即使你在一个 RUN 里下载完又删掉文件也没用——层和构建参数的历史记录还在。&lt;/p&gt;
&lt;p&gt;BuildKit 的正解是 &lt;strong&gt;secret 挂载&lt;/strong&gt;：密钥只在某一条 RUN 执行期间以文件形式出现在 &lt;code&gt;/run/secrets/&lt;/code&gt; 下，不进入任何层、不进入镜像历史。&lt;/p&gt;
&lt;p&gt;Dockerfile 侧：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# syntax=docker/dockerfile:1
FROM alpine:3.20
RUN --mount=type=secret,id=github_token \
    TOKEN=$(cat /run/secrets/github_token) \
    &amp;amp;&amp;amp; git clone https://oauth2:${TOKEN}@github.com/myorg/private-repo.git /src
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;构建时把密钥喂进去，两种喂法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 喂法一：从环境变量取
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
docker build --secret id=github_token,env=GITHUB_TOKEN -t myapp .

# 喂法二：从文件取
docker build --secret id=github_token,src=./token.txt -t myapp .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意两边的 &lt;code&gt;id&lt;/code&gt; 必须对上：Dockerfile 里 &lt;code&gt;id=github_token&lt;/code&gt;，构建命令里也得是 &lt;code&gt;id=github_token&lt;/code&gt;。构建结束后可以验证一下镜像里确实没有它：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker history myapp        # 看不到密钥
docker inspect myapp        # Config 里也没有
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;另外还有个同类需求是拉仓库不想用 Token、想直接用本机的 SSH 密钥，BuildKit 提供了 &lt;code&gt;--mount=type=ssh&lt;/code&gt; 配合 &lt;code&gt;docker build --ssh default&lt;/code&gt;，通过 SSH agent 转发凭据，密钥本体连文件都不落，原理和 secret 挂载一样都是「只借不给」。&lt;/p&gt;
&lt;h2&gt;远程缓存：让 CI 和同事的机器也命中缓存&lt;/h2&gt;
&lt;p&gt;本地缓存再快，也只在你这台机器上。换台电脑、换个 CI Runner，缓存全空，又得从头下载。BuildKit 支持把缓存&lt;strong&gt;导出到镜像仓库&lt;/strong&gt;，任何能拉到那个仓库的地方都能导入复用，这叫远程缓存（remote cache）。&lt;/p&gt;
&lt;p&gt;:::warning
远程缓存的导入导出需要用 &lt;code&gt;docker buildx build&lt;/code&gt; 命令（本机单机构建时它和 &lt;code&gt;docker build&lt;/code&gt; 等价），并且构建器要能把缓存推到仓库，记得先 &lt;code&gt;docker login&lt;/code&gt;。另外 &amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;千万不要把缓存推到公共仓库还当成私有资产&amp;lt;/span&amp;gt;，缓存里可能含有构建过程中的中间文件，按和镜像同等的可见性对待。
:::&lt;/p&gt;
&lt;p&gt;两种导出方式的区别先看表：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;&lt;code&gt;type=inline&lt;/code&gt;&lt;/th&gt;
&lt;th&gt;&lt;code&gt;type=registry&lt;/code&gt;&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;缓存存在哪&lt;/td&gt;
&lt;td&gt;嵌进构建出的镜像本身里&lt;/td&gt;
&lt;td&gt;推成一个单独的缓存镜像（用一个专用 tag）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;导出参数&lt;/td&gt;
&lt;td&gt;&lt;code&gt;--cache-to type=inline&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;--cache-to type=registry,ref=仓库/镜像:缓存tag&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;导入参数&lt;/td&gt;
&lt;td&gt;&lt;code&gt;--cache-from type=registry,ref=那个镜像&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;--cache-from type=registry,ref=仓库/镜像:缓存tag&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;缓存范围&lt;/td&gt;
&lt;td&gt;只有最终镜像包含的层&lt;/td&gt;
&lt;td&gt;可选 &lt;code&gt;mode=min&lt;/code&gt;（仅最终层）或 &lt;code&gt;mode=max&lt;/code&gt;（&lt;strong&gt;所有阶段的所有层&lt;/strong&gt;）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合场景&lt;/td&gt;
&lt;td&gt;简单项目、只想让别人拉镜像时顺带复用&lt;/td&gt;
&lt;td&gt;多阶段构建、CI 流水线，正经用法选这个&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;完整命令（以 registry 方式、&lt;code&gt;mode=max&lt;/code&gt; 为例）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker buildx build \
  --cache-from type=registry,ref=registry.example.com/myapp:buildcache \
  --cache-to type=registry,ref=registry.example.com/myapp:buildcache,mode=max \
  -t registry.example.com/myapp:latest \
  --push .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐段拆解：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;--cache-from&lt;/code&gt;：构建前先去仓库把 &lt;code&gt;buildcache&lt;/code&gt; 这个 tag 对应的缓存拉下来，本次构建能命中的层和缓存挂载直接复用；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--cache-to ... mode=max&lt;/code&gt;：构建后把缓存推回去。&lt;code&gt;mode=max&lt;/code&gt; 会把&lt;strong&gt;所有构建阶段&lt;/strong&gt;（包括多阶段里那些不进最终镜像的中间阶段）的缓存都导出，命中率最高，代价是缓存体积大、推送慢；&lt;code&gt;mode=min&lt;/code&gt; 只导出最终镜像的层，体积小但中间阶段的缓存下次用不上；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;-t ... --push&lt;/code&gt;：顺手把成品镜像也推上去。注意 buildx 在使用远程缓存等高级功能时，构建结果默认只留在构建器里，要加 &lt;code&gt;--push&lt;/code&gt; 推走或 &lt;code&gt;--load&lt;/code&gt; 加载到本机 Docker 才能用。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;CI 场景的价值就在这里：GitHub Actions 这类 CI 的 Runner 每次都是全新环境，本地缓存指望不上。流水线里加上这两行参数后，第一次构建负责把缓存种到仓库里，之后每次构建先拉缓存再开工，依赖层、编译层大面积命中，构建时间从分钟级掉到几十秒。缓存的 tag 是固定的（&lt;code&gt;buildcache&lt;/code&gt;），每次构建覆盖更新，不需要人工维护。&lt;/p&gt;
&lt;p&gt;落到 GitHub Actions 里，用官方的 build-push-action 时这两行参数有现成的字段可填，不用手写命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;- name: 构建并推送镜像
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: registry.example.com/myapp:latest
    cache-from: type=registry,ref=registry.example.com/myapp:buildcache
    cache-to: type=registry,ref=registry.example.com/myapp:buildcache,mode=max
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果镜像仓库本身就在 GitHub 体系内（比如推 GHCR），还有个更省事的后端 &lt;code&gt;type=gha&lt;/code&gt;，缓存直接存在 Actions 的缓存空间里，不占仓库的 tag，两行改成 &lt;code&gt;cache-from: type=gha&lt;/code&gt; 和 &lt;code&gt;cache-to: type=gha,mode=max&lt;/code&gt; 即可。出了 GitHub 环境就用回 registry 方式，原理完全一样。&lt;/p&gt;
&lt;p&gt;还有个细节：&lt;code&gt;--cache-from&lt;/code&gt; 可以写多次，从多个来源依次找缓存（比如先找分支专属缓存、再找主干缓存），前面的找不到才看后面的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker buildx build \
  --cache-from type=registry,ref=registry.example.com/myapp:buildcache-feature \
  --cache-from type=registry,ref=registry.example.com/myapp:buildcache \
  -t registry.example.com/myapp:latest --load .
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;多阶段构建下的缓存与 --target&lt;/h2&gt;
&lt;p&gt;多阶段构建里，BuildKit 只构建最终镜像依赖的那条链路：某个阶段如果没被后面的 &lt;code&gt;COPY --from&lt;/code&gt; 或最终阶段引用，整个阶段会被跳过，连带它的缓存也不用操心。当你只想验证某个中间阶段（比如只想看看编译阶段能不能过）时，用 &lt;code&gt;--target&lt;/code&gt; 指定构建到哪个阶段为止：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 只构建到名为 builder 的阶段，不再往下走
docker buildx build --target builder -t myapp:builder-check .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这在排查「到底是编译挂了还是打包挂了」时特别好用：先单独把 builder 阶段构建出来，进容器看产物，再决定下一步查哪。&lt;/p&gt;
&lt;p&gt;反过来也要知道：&lt;code&gt;--target&lt;/code&gt; 构建出的镜像只是那个阶段的状态，&lt;strong&gt;别把中间阶段的镜像当成品推上线&lt;/strong&gt;，里面往往带着编译器、源码和调试工具，又大又不安全。&lt;/p&gt;
&lt;h2&gt;缓存管理：别让缓存把磁盘吃光&lt;/h2&gt;
&lt;p&gt;缓存是拿磁盘换时间，攒久了也会变成负担——几个 GB 起步，项目多了几十 GB 也常见。先看占用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 看构建缓存总占用和明细
docker builder du

# 更细的逐条缓存记录（buildx 版本）
docker buildx du
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;清理命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 清理 30 天没用过的构建缓存
docker builder prune --filter &quot;until=720h&quot;

# 保留最近 20GB，超出的按最久未用先清
docker buildx prune --keep-storage 20GB

# 全部清掉（包括缓存挂载里的内容），慎用
docker builder prune --all
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;docker builder prune --all&lt;/code&gt; 会把缓存挂载（type=cache）里攒的依赖包也一并清掉，下一次构建所有依赖重新下载，慢的那一遍又得重来。日常清理优先用 &lt;code&gt;until&lt;/code&gt; 或 &lt;code&gt;keep-storage&lt;/code&gt; 做「按量保留」，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把 prune --all 写进定时任务无脑跑&amp;lt;/span&amp;gt;。
:::&lt;/p&gt;
&lt;p&gt;还有一个容易混淆的点：构建缓存和镜像、容器不在一个账本里。&lt;code&gt;docker system df&lt;/code&gt; 能看到 Build Cache 一栏的占用，但平时清垃圾用的 &lt;code&gt;docker image prune&lt;/code&gt; &lt;strong&gt;不会动构建缓存&lt;/strong&gt;，磁盘满了查到最后发现是构建缓存的锅，是很常见的剧情。&lt;/p&gt;
&lt;h2&gt;排障：缓存为什么没命中&lt;/h2&gt;
&lt;p&gt;缓存没命中时先别急着加 &lt;code&gt;--no-cache&lt;/code&gt; 硬刚，按下面顺序排查，大多是前三个原因：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;1. 指令顺序不合理。&lt;/strong&gt; 层缓存的规则是「一层变了，它后面的所有层全部作废」。把变化最频繁的东西（源码）放在最前面，后面的依赖安装层就永远命不中。原则在入门篇讲过：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;按变化频率从低到高排列指令&amp;lt;/span&amp;gt;——基础镜像、系统包、依赖清单、依赖安装、源码，越靠后变得越勤。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. COPY 的范围太大。&lt;/strong&gt; 一句 &lt;code&gt;COPY . .&lt;/code&gt; 会把构建上下文里的每个文件都算进这一层的指纹，改任何一个文件（哪怕是 README）都会让这层失效。处理办法：先精确 COPY 依赖清单装依赖，最后才 COPY 源码；同时写好 &lt;code&gt;.dockerignore&lt;/code&gt;，把 &lt;code&gt;.git&lt;/code&gt;、&lt;code&gt;node_modules&lt;/code&gt;、日志、临时文件排除在上下文之外——上下文内容变少，指纹才稳定。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 构建参数或基础镜像变了。&lt;/strong&gt; &lt;code&gt;ARG&lt;/code&gt; 的值一变，从声明它的那层起缓存全部失效；基础镜像被上游更新后，本地还是旧的也会造成「以为命中其实重拉」。这就引出两个参数的正确用法区别：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;什么时候用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--no-cache&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;本次构建完全忽略层缓存，所有指令强制重跑&lt;/td&gt;
&lt;td&gt;怀疑缓存坏了、要验证「从零构建能不能过」时偶尔用一次&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--pull&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;构建前先检查并拉取更新的基础镜像&lt;/td&gt;
&lt;td&gt;想让基础镜像保持最新时用；基础镜像没更新时不影响后续缓存&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;两者别混用成日常习惯：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;每次构建都加 --no-cache 等于亲手关掉全部缓存&amp;lt;/span&amp;gt;，构建慢的毛病只会更重。还有个细节：&lt;code&gt;--no-cache&lt;/code&gt; 只跳过层缓存，&lt;code&gt;type=cache&lt;/code&gt; 挂载里的内容依然会被复用，所以「加了 --no-cache 依赖还是秒装完」不是缓存没关干净，而是缓存挂载在起作用——真要连它一起清，用前面说的 &lt;code&gt;docker builder prune&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 换了机器或构建器。&lt;/strong&gt; 本地缓存只属于本机这个构建器，换电脑、重装 Docker、CI 换 Runner 都会清零，这正是上一节远程缓存要解决的问题。如果已经配了远程缓存还命不中，检查 &lt;code&gt;--cache-from&lt;/code&gt; 的 ref 地址和 tag 写得对不对、构建器有没有拉取权限，构建日志开头会明确打出缓存导入成功还是失败。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. 同一条 RUN 写法变了。&lt;/strong&gt; 层缓存对指令文本敏感，把 &lt;code&gt;apt-get install curl&lt;/code&gt; 改成 &lt;code&gt;apt-get install -y curl&lt;/code&gt; 这种「等价改写」也会被判定为新指令而重跑。无意义的格式抖动尽量避免，Dockerfile 定稿后不要频繁动老指令的写法。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;6. 构建器不是同一个。&lt;/strong&gt; 缓存是按「构建器」隔离存放的。用 &lt;code&gt;docker buildx ls&lt;/code&gt; 能看到当前有哪些构建器：默认的 &lt;code&gt;default&lt;/code&gt; 构建器用的是 Docker 内置 BuildKit，而自己 &lt;code&gt;docker buildx create&lt;/code&gt; 出来的 &lt;code&gt;docker-container&lt;/code&gt; 驱动构建器跑在一个独立容器里，&lt;strong&gt;两边的本地缓存互不相通&lt;/strong&gt;。今天用 A 构建器构建、明天切到 B，缓存就像凭空消失了一样。团队里要把用哪个构建器说死，CI 里更要固定，别让缓存毁在这种低级不一致上。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;BuildKit 是 Docker 23+ 的默认构建引擎，核心优势是把 Dockerfile 当依赖图并行执行、无用阶段跳过，排障时先开 &lt;code&gt;--progress=plain&lt;/code&gt; 看全量日志；&lt;/li&gt;
&lt;li&gt;Dockerfile 第一行写 &lt;code&gt;# syntax=docker/dockerfile:1&lt;/code&gt;，让语法版本独立于 Docker 版本；&lt;/li&gt;
&lt;li&gt;提速的大头是 RUN 缓存挂载：给 pip 挂 &lt;code&gt;/root/.cache/pip&lt;/code&gt;、给 apt 挂 archives 与 lists 两个目录（先删 &lt;code&gt;docker-clean&lt;/code&gt;），依赖下载只发生一次；&lt;/li&gt;
&lt;li&gt;构建要凭据用 secret 挂载，密钥只在构建瞬间以文件出现，绝不写进 ARG / ENV；&lt;/li&gt;
&lt;li&gt;跨机器复用缓存靠远程缓存，正经项目用 &lt;code&gt;type=registry&lt;/code&gt; 加 &lt;code&gt;mode=max&lt;/code&gt;，CI 场景收益最大；&lt;/li&gt;
&lt;li&gt;缓存要用也要管：&lt;code&gt;docker builder du&lt;/code&gt; 看占用，按 &lt;code&gt;until&lt;/code&gt; / &lt;code&gt;keep-storage&lt;/code&gt; 温和清理；&lt;/li&gt;
&lt;li&gt;缓存没命中先查指令顺序、COPY 范围和上下文，别把 &lt;code&gt;--no-cache&lt;/code&gt; 当日常开关。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;下一篇《多平台镜像构建实战》会接着用 buildx，把同一份 Dockerfile 一次构建出 amd64 和 arm64 两套镜像，缓存这篇打好的底子到时候会直接派上用场。&lt;/p&gt;
</content:encoded></item><item><title>多平台镜像构建实战：buildx 双架构</title><link>https://www.anexns.cloudns.org/posts/docker-buildx-multiarch/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-buildx-multiarch/</guid><description>一次构建，处处运行：用 buildx 构建 amd64 与 arm64 双架构镜像，QEMU 模拟与原生构建的区别、manifest 多架构清单的原理与验证，让镜像在 x86 服务器和 ARM 设备上都能直接拉取运行。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;上一篇 &lt;a href=&quot;/posts/dockerfile-guide/&quot;&gt;《Dockerfile 入门：把自己的应用打包成镜像》&lt;/a&gt; 讲了怎么把应用打包成镜像。但那篇里构建出来的镜像有一个隐藏前提：&lt;strong&gt;它只能在和你构建机器相同 CPU 架构的机器上跑&lt;/strong&gt;。你在 x86 服务器上构建的镜像，拿到 ARM 机器上就是跑不起来的。这篇把这个坑填上：用 buildx 一次构建出 amd64＋arm64 双架构镜像，推到仓库之后，任何架构的机器 &lt;code&gt;docker pull&lt;/code&gt; 都能自动拿到自己能跑的那一份。&lt;/p&gt;
&lt;h2&gt;为什么需要多架构&lt;/h2&gt;
&lt;p&gt;先看看现在的机器版图，你手里的设备很可能早就横跨两种架构了：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;设备/环境&lt;/th&gt;
&lt;th&gt;CPU 架构&lt;/th&gt;
&lt;th&gt;平台标识&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;普通 x86 云服务器、台式机&lt;/td&gt;
&lt;td&gt;amd64（x86_64）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;linux/amd64&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ARM 云主机（部分厂商的 ARM 实例）&lt;/td&gt;
&lt;td&gt;arm64（aarch64）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;linux/arm64&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;树莓派 4/5（64 位系统）&lt;/td&gt;
&lt;td&gt;arm64&lt;/td&gt;
&lt;td&gt;&lt;code&gt;linux/arm64&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Apple M 系列芯片的 Mac&lt;/td&gt;
&lt;td&gt;arm64&lt;/td&gt;
&lt;td&gt;&lt;code&gt;linux/arm64&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;老树莓派、32 位 ARM 设备&lt;/td&gt;
&lt;td&gt;armv7&lt;/td&gt;
&lt;td&gt;&lt;code&gt;linux/arm/v7&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;镜像本质上是「文件系统＋可执行文件」的打包，而可执行文件是按 CPU 架构编译的机器码。amd64 的二进制给 ARM 的 CPU，它一个指令都不认识。所以在 x86 上构建的镜像搬到树莓派上启动，容器会立刻退出，日志里就是那句经典报错：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;exec /app/server: exec format error
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;或者：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;standard_init_linux.go:228: exec user process caused: exec format error
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这句话翻译过来就是「这个可执行文件的格式，当前 CPU 执行不了」。它不是你代码写错了，也不是 Docker 坏了，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;纯粹是架构对不上&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;这个坑在实际使用里出现的频率比想象中高。举几个典型场景：你在公司或云上的 x86 服务器开发调试一切正常，镜像推上仓库，回家想在树莓派上把服务也跑一份，拉下来一启动就退出；或者你用的是 M 系列芯片的 Mac，同事在 x86 机器上构建的镜像发给你，你本地怎么都跑不起来；再或者云厂商的 ARM 实例性价比更高，你想把服务迁过去省钱，结果发现手里所有自建镜像都得重新构建一遍。还有一种更隐蔽的：Docker Desktop 在 M 系列 Mac 上对单架构 amd64 镜像会用模拟硬撑，能跑但慢得离谱，很多人误以为是服务本身性能差。&lt;/p&gt;
&lt;p&gt;解决办法不是在每台机器上各构建一次再手动区分标签（那样版本管理全乱套，使用者还得先查自己是什么架构），而是构建&lt;strong&gt;多架构镜像&lt;/strong&gt;：同一个标签底下同时挂 amd64 和 arm64 两份镜像，谁拉取就自动给谁对应的那份。本篇的主线就是把这件事完整走一遍：先讲清 manifest list 的原理，再装 QEMU、建 builder、一条命令构建推送，最后验证清单并在两种机器上实测。&lt;/p&gt;
&lt;h2&gt;原理：manifest list 是什么&lt;/h2&gt;
&lt;p&gt;多架构镜像靠的是一个叫 &lt;strong&gt;manifest list&lt;/strong&gt;（镜像清单列表，OCI 规范里叫 index）的东西。理解它，后面的命令就都顺理成章了。&lt;/p&gt;
&lt;p&gt;平时你拉一个镜像，实际发生的是两步：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;先向仓库要这个标签的 manifest（清单），清单里记录了镜像的配置和每一层文件；&lt;/li&gt;
&lt;li&gt;按清单把层文件下载下来组装。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;多架构镜像在这个基础上多了一层：标签指向的不再是单个 manifest，而是一个 &lt;strong&gt;manifest list&lt;/strong&gt;，里面列着这个标签在每个平台下各自对应的 manifest：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;myapp:1.0（标签）
└── manifest list
    ├── linux/amd64 → manifest A（amd64 版的层与配置）
    └── linux/arm64 → manifest B（arm64 版的层与配置）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Docker 客户端拉取时，会先看这份 list，再根据自己所在机器的架构&lt;strong&gt;自动挑对应的一份下载&lt;/strong&gt;。所以使用者完全无感：同一条 &lt;code&gt;docker pull myapp:1.0&lt;/code&gt;，在 x86 服务器上拉到 amd64 版，在树莓派上拉到 arm64 版。这就是&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;一次构建、一个标签、处处运行&amp;lt;/span&amp;gt;的底层原理。&lt;/p&gt;
&lt;p&gt;官方镜像（Nginx、PostgreSQL、Redis 这些）全都是这么干的，所以你从来没操心过它们的架构问题。现在轮到给你自己的镜像也配上这个待遇。&lt;/p&gt;
&lt;h2&gt;准备工作：确认 buildx 与 QEMU&lt;/h2&gt;
&lt;h3&gt;确认 buildx 可用&lt;/h3&gt;
&lt;p&gt;buildx 是 Docker 官方的增强构建工具，现在 Docker Desktop 和新版 Docker Engine 都自带。先确认：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker buildx version
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;能输出版本号（类似 &lt;code&gt;github.com/docker/buildx v0.x.x&lt;/code&gt;）就可以。没有的话按第一篇的方法把 Docker 升级到较新版本，老版本的 &lt;code&gt;docker build&lt;/code&gt; 不具备多平台能力。&lt;/p&gt;
&lt;h3&gt;给构建机装上 QEMU 模拟&lt;/h3&gt;
&lt;p&gt;这里有个关键问题：你的构建机是 amd64 的，它怎么构建出 arm64 的镜像？构建过程中要运行 ARM 架构的程序（比如在 Dockerfile 里执行 &lt;code&gt;RUN&lt;/code&gt; 安装依赖），amd64 的 CPU 直接跑 ARM 二进制同样会报 &lt;code&gt;exec format error&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;解法是 &lt;strong&gt;QEMU 用户态模拟&lt;/strong&gt;：在内核层面注册一层翻译，遇到 ARM 二进制就交给 QEMU 模拟执行。Docker 官方提供了一键安装镜像：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run --privileged --rm tonistiigi/binfmt --install all
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这条命令通过 binfmt_misc 机制把各种架构的模拟器注册进内核，&lt;code&gt;--install all&lt;/code&gt; 表示把支持的架构全装上。装完检查一下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ls /proc/sys/fs/binfmt_misc/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;能看到 &lt;code&gt;qemu-aarch64&lt;/code&gt; 等文件就说明 ARM64 的模拟已经就位。这个注册在宿主机重启后会失效，重启了重新跑一遍上面的命令即可。&lt;/p&gt;
&lt;p&gt;:::warning
QEMU 是&lt;strong&gt;模拟&lt;/strong&gt;执行，速度比原生 CPU 慢一个数量级。编译型语言的大型项目在模拟下构建可能慢到几十分钟甚至超时，这一节先把流程跑通，性能问题在后面「QEMU 的性能坑」一节专门讲。
:::&lt;/p&gt;
&lt;h2&gt;创建 builder：为什么必须换驱动&lt;/h2&gt;
&lt;p&gt;buildx 的构建工作由「builder 实例」承担，每个 builder 有一个驱动（driver）。默认的 &lt;code&gt;docker&lt;/code&gt; 驱动直接借用 Docker 守护进程的能力，日常单架构构建没问题，但它有个硬伤：&lt;strong&gt;不支持一次构建多平台并合并输出&lt;/strong&gt;。所以要先创建一个 &lt;code&gt;docker-container&lt;/code&gt; 驱动的 builder，它会专门起一个构建容器，能力完整得多：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker buildx create --name multi --driver docker-container --use
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;--name multi&lt;/code&gt;：给这个 builder 起个名字，随便取；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--driver docker-container&lt;/code&gt;：用容器驱动，这是关键；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--use&lt;/code&gt;：创建完立刻切换为当前默认 builder。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;创建后把它启动并检查状态：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker buildx inspect --bootstrap
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出里重点看 &lt;code&gt;Platforms&lt;/code&gt; 一行，应该列出 &lt;code&gt;linux/amd64, linux/arm64, ...&lt;/code&gt; 一长串平台，说明这个 builder 已经具备多架构构建能力（靠的就是上一步装的 QEMU）。&lt;/p&gt;
&lt;p&gt;两个驱动的区别一次说清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;docker 驱动（默认）&lt;/th&gt;
&lt;th&gt;docker-container 驱动&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;构建执行者&lt;/td&gt;
&lt;td&gt;Docker 守护进程本体&lt;/td&gt;
&lt;td&gt;独立的构建容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;单架构构建&lt;/td&gt;
&lt;td&gt;支持&lt;/td&gt;
&lt;td&gt;支持&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;一次多平台构建&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不支持&amp;lt;/span&amp;gt;&lt;/td&gt;
&lt;td&gt;支持&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;构建结果直接 &lt;code&gt;--load&lt;/code&gt; 进本地镜像库&lt;/td&gt;
&lt;td&gt;支持&lt;/td&gt;
&lt;td&gt;单平台可以，多平台不行（见下文）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;缓存导出（registry/gha 等高级缓存）&lt;/td&gt;
&lt;td&gt;受限&lt;/td&gt;
&lt;td&gt;完整支持&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;使用前提&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;首次使用自动拉取构建镜像&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;顺手记一下常用管理命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker buildx ls              # 查看所有 builder 和当前选中项
docker buildx use default     # 切回默认 builder
docker buildx rm multi        # 删除不用的 builder
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;实战：一条命令构建双架构并推送&lt;/h2&gt;
&lt;p&gt;准备沿用 &lt;a href=&quot;/posts/dockerfile-guide/&quot;&gt;Dockerfile 篇&lt;/a&gt;的例子，一个极简应用即可。为了让没看过前篇的读者也能直接动手，这里把示例 Dockerfile 再贴一次，就是一个启动后打印一句话的小程序，重点不在应用本身，而在构建流程：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;FROM alpine:3.20
COPY app.sh /app.sh
RUN chmod +x /app.sh
CMD [&quot;/app.sh&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;其中 &lt;code&gt;app.sh&lt;/code&gt; 只有一行实质内容：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/sh
echo &quot;hello from $(uname -m)&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;特意让它打印 &lt;code&gt;uname -m&lt;/code&gt; 的结果，就是为了验证时能一眼看出当前跑的到底是哪个架构的镜像：在 amd64 机器上输出 &lt;code&gt;x86_64&lt;/code&gt;，在 arm64 机器上输出 &lt;code&gt;aarch64&lt;/code&gt;，装错了一目了然。假设 Dockerfile 已经就绪，当前目录就是构建上下文，镜像准备推到 Docker Hub 的 &lt;code&gt;yourname/myapp&lt;/code&gt;，版本 &lt;code&gt;1.0&lt;/code&gt;。还没登录仓库的话先执行一次 &lt;code&gt;docker login&lt;/code&gt;，推送环节会用到。&lt;/p&gt;
&lt;p&gt;一条命令完成双架构构建＋推送：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t yourname/myapp:1.0 \
  --push .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐个参数拆开讲：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;--platform linux/amd64,linux/arm64&lt;/code&gt;：目标平台列表，逗号分隔不要加空格。buildx 会为每个平台各构建一份镜像；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;-t yourname/myapp:1.0&lt;/code&gt;：镜像名与标签，和普通构建一样；可以多次写 &lt;code&gt;-t&lt;/code&gt; 同时打多个标签（比如再加一个 &lt;code&gt;:latest&lt;/code&gt;）；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--push&lt;/code&gt;：构建完成后直接把 manifest list 连同各架构镜像一起推到仓库；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;.&lt;/code&gt;：构建上下文路径，和 &lt;code&gt;docker build&lt;/code&gt; 一样是最后一个参数。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;构建过程中你会看到进度里每个步骤都标注了平台（如 &lt;code&gt;[linux/arm64 3/5] RUN ...&lt;/code&gt;），两个平台并行推进。注意观察的话会发现 arm64 那一路的 &lt;code&gt;RUN&lt;/code&gt; 步骤明显更慢，那就是 QEMU 模拟在干活，属于正常现象。推送完成后，仓库里 &lt;code&gt;1.0&lt;/code&gt; 这个标签就是一份双架构清单了。&lt;/p&gt;
&lt;p&gt;如果想同时维护一个跟随最新版的 &lt;code&gt;latest&lt;/code&gt; 标签，不用构建两遍，在同一条命令里多写一个 &lt;code&gt;-t&lt;/code&gt; 即可，两个标签共用同一次构建结果：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t yourname/myapp:1.0 \
  -t yourname/myapp:latest \
  --push .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;还有一个容易忽略的细节：多平台构建时，每个平台的构建是&lt;strong&gt;互相独立&lt;/strong&gt;的，Dockerfile 里如果有步骤只对某个平台成立（比如某个依赖只有 amd64 版），构建会在那个平台上单独失败，报错信息里会标明是哪个平台、哪一步挂的，看日志时认准平台前缀再对症处理，别被另一平台的正常输出干扰。&lt;/p&gt;
&lt;h3&gt;为什么多平台构建不能 --load&lt;/h3&gt;
&lt;p&gt;单架构时我们习惯 &lt;code&gt;--load&lt;/code&gt; 把镜像加载进本地 &lt;code&gt;docker images&lt;/code&gt; 里先跑一下看看。多平台构建时这招用不了，原因是本地镜像库的存储结构&lt;strong&gt;装不下一份 manifest list&lt;/strong&gt;——它只认单个架构的镜像。所以 buildx 对多平台构建的要求很明确：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;要么 &lt;code&gt;--push&lt;/code&gt; 直接推到仓库（最常用）；&lt;/li&gt;
&lt;li&gt;要么 &lt;code&gt;--output type=oci&lt;/code&gt; 之类的方式导出成文件。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;如果你硬给多平台构建加上 &lt;code&gt;--load&lt;/code&gt;，会直接报错：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ERROR: docker exporter does not currently support exporting manifest lists
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
记住这个分工：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;多平台构建的结果只能推仓库，不能进本地镜像库&amp;lt;/span&amp;gt;。想在本地验证，就从仓库把镜像按指定平台拉回来跑（下一节演示），这也是最真实的验证方式——模拟一遍使用者拿到镜像的全过程。
:::&lt;/p&gt;
&lt;p&gt;顺带一提，单平台时 &lt;code&gt;--load&lt;/code&gt; 依然可用，比如只想本地快速试一下 arm64 版：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker buildx build --platform linux/arm64 -t myapp:test --load .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这会在 amd64 机器上把 arm64 镜像加载进来，之后 &lt;code&gt;docker run --platform linux/arm64 myapp:test&lt;/code&gt; 就能靠 QEMU 模拟跑起来做冒烟测试（慢，但能验逻辑）。&lt;/p&gt;
&lt;h2&gt;验证：清单要亲眼看到，两台机器都要试&lt;/h2&gt;
&lt;h3&gt;看 manifest list&lt;/h3&gt;
&lt;p&gt;用 buildx 自带的 imagetools 检查刚推送的标签：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker buildx imagetools inspect yourname/myapp:1.0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出大致长这样，重点看 &lt;code&gt;Manifests&lt;/code&gt; 下面是不是每个平台一份：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Name:      docker.io/yourname/myapp:1.0
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:xxxx...

Manifests:
  Name:        docker.io/yourname/myapp:1.0@sha256:aaaa...
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    linux/amd64

  Name:        docker.io/yourname/myapp:1.0@sha256:bbbb...
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    linux/arm64
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;顶层 MediaType 是 &lt;code&gt;image.index&lt;/code&gt;（即 manifest list），底下挂着 amd64、arm64 两份 manifest，这就对了。如果只看到一份 manifest、顶层也不是 index，说明构建时平台参数没生效，回头检查命令。&lt;/p&gt;
&lt;h3&gt;在两种机器上分别拉取运行&lt;/h3&gt;
&lt;p&gt;最后一步是真实环境验证。在一台 x86 服务器和一台 ARM 设备（树莓派、ARM 云主机都行）上分别执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker pull yourname/myapp:1.0
docker run --rm yourname/myapp:1.0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两边用的是&lt;strong&gt;完全相同的命令、完全相同的标签&lt;/strong&gt;，各自拉到自己架构的镜像并正常运行，这才算大功告成。想确认某台机器拉到的到底是哪一架构，可以看镜像详情里的架构字段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker image inspect yourname/myapp:1.0 --format &apos;{{.Architecture}}&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;在 x86 上输出 &lt;code&gt;amd64&lt;/code&gt;，在 ARM 上输出 &lt;code&gt;arm64&lt;/code&gt;，各就其位。再配合示例程序打印的 &lt;code&gt;uname -m&lt;/code&gt;，双保险确认无误。&lt;/p&gt;
&lt;p&gt;如果手边暂时只有一台机器，也可以在本机强制拉取并运行另一个平台的版本做验证（靠 QEMU 模拟运行，慢但能确认镜像本身没问题）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run --rm --platform linux/arm64 yourname/myapp:1.0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;在 amd64 机器上执行这条命令，输出 &lt;code&gt;hello from aarch64&lt;/code&gt;，就说明 arm64 那份镜像是真能跑的，而不是清单里挂了个空壳。发布重要版本前花一分钟做这个检查，能挡住绝大多数「清单对了但某个平台的镜像是坏的」事故。&lt;/p&gt;
&lt;h2&gt;Dockerfile 的架构适配注意&lt;/h2&gt;
&lt;p&gt;多平台构建对 Dockerfile 有两个常见要求，提前知道能少踩坑。&lt;/p&gt;
&lt;h3&gt;基础镜像必须有多架构版本&lt;/h3&gt;
&lt;p&gt;你的 &lt;code&gt;FROM&lt;/code&gt; 用的基础镜像如果只有 amd64 版，那 arm64 的构建会在第一步就失败。好消息是主流官方镜像（&lt;code&gt;python&lt;/code&gt;、&lt;code&gt;node&lt;/code&gt;、&lt;code&gt;golang&lt;/code&gt;、&lt;code&gt;nginx&lt;/code&gt;、&lt;code&gt;alpine&lt;/code&gt; 等）全都提供多架构版本，不用操心。需要警惕的是小众镜像和自己以前构建的单架构镜像。检查一个镜像支持哪些平台：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker buildx imagetools inspect python:3.12-slim
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;看它 Manifests 里列出的 Platform 即可。&lt;/p&gt;
&lt;h3&gt;下载二进制时用 TARGETARCH 按架构选文件&lt;/h3&gt;
&lt;p&gt;最典型的翻车场景：Dockerfile 里写死了下载 amd64 版本的工具（比如某个工具的 release 地址里带 &lt;code&gt;amd64&lt;/code&gt; 字样），单架构时没问题，构建 arm64 版时下回来的还是 amd64 二进制，装的时候不报错，&lt;strong&gt;一运行就 &lt;code&gt;exec format error&lt;/code&gt;&lt;/strong&gt;，而且是在容器启动时才爆，排查起来很绕。&lt;/p&gt;
&lt;p&gt;buildx 在构建时会自动注入一组平台相关的构建参数，其中最常用的是 &lt;code&gt;TARGETARCH&lt;/code&gt;（目标架构，取值 &lt;code&gt;amd64&lt;/code&gt;/&lt;code&gt;arm64&lt;/code&gt;）。在 Dockerfile 里声明并用它拼下载地址即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;FROM alpine:3.20

ARG TARGETARCH
ARG TOOL_VERSION=1.2.3

RUN apk add --no-cache curl \
    &amp;amp;&amp;amp; curl -fsSL -o /usr/local/bin/tool \
       &quot;https://example.com/releases/v${TOOL_VERSION}/tool-linux-${TARGETARCH}&quot; \
    &amp;amp;&amp;amp; chmod +x /usr/local/bin/tool

CMD [&quot;tool&quot;, &quot;serve&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;构建哪个平台，&lt;code&gt;TARGETARCH&lt;/code&gt; 就是哪个平台的值，下载的永远是对应架构的文件。同系列的自动参数还有几个，了解即可：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;构建参数&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;例子&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;TARGETPLATFORM&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;目标平台完整写法&lt;/td&gt;
&lt;td&gt;&lt;code&gt;linux/arm64&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;TARGETOS&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;目标系统&lt;/td&gt;
&lt;td&gt;&lt;code&gt;linux&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;TARGETARCH&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;目标架构&lt;/td&gt;
&lt;td&gt;&lt;code&gt;amd64&lt;/code&gt;、&lt;code&gt;arm64&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;TARGETVARIANT&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;架构变体&lt;/td&gt;
&lt;td&gt;&lt;code&gt;v7&lt;/code&gt;（如 &lt;code&gt;linux/arm/v7&lt;/code&gt;）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;BUILDPLATFORM&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;构建机自身的平台&lt;/td&gt;
&lt;td&gt;&lt;code&gt;linux/amd64&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
这类自动参数必须先用 &lt;code&gt;ARG&lt;/code&gt; 声明才能在 Dockerfile 里引用，忘了声明会取到空值，下载地址拼错还不容易发现。另外下载前最好核对上游 release 的命名规则：有的项目 arm64 文件叫 &lt;code&gt;aarch64&lt;/code&gt;，有的叫 &lt;code&gt;arm64&lt;/code&gt;，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;名字对不上会直接 404&amp;lt;/span&amp;gt;，按对方的实际文件名写映射即可。
:::&lt;/p&gt;
&lt;p&gt;&lt;code&gt;BUILDPLATFORM&lt;/code&gt; 还有个进阶用法：编译型语言可以让编译步骤固定在构建机原生架构上跑（速度快），只把产物按目标架构交叉编译，典型写法是 &lt;code&gt;FROM --platform=$BUILDPLATFORM golang:1.23 AS builder&lt;/code&gt;。Go 这类自带交叉编译的语言特别适合这么干，能绕开 QEMU 的慢，这属于优化手段，先了解有这么回事即可。&lt;/p&gt;
&lt;h2&gt;QEMU 模拟的性能坑与原生构建节点&lt;/h2&gt;
&lt;p&gt;前面说过 QEMU 是模拟执行，它的代价要心里有数：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;纯计算和编译任务最慢&lt;/strong&gt;：模拟下 CPU 密集型操作的耗时常常是原生的 5–10 倍，大型项目一次构建几十分钟很常见；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;I/O 和脚本类步骤影响相对小&lt;/strong&gt;：拷贝文件、解压、跑简单脚本还能接受；&lt;/li&gt;
&lt;li&gt;构建缓存能救命：依赖层没变化时直接命中缓存，慢的主要是首次构建和代码层。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;如果双架构构建要进日常流水线，正经解法是&lt;strong&gt;加一台 ARM 原生构建节点&lt;/strong&gt;：准备一台 ARM 机器（ARM 云主机、树莓派都行），让 buildx 把 arm64 的构建任务分发到它上面原生执行，amd64 的留在本机，两个平台真正并行、还都是原生速度：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 本机 builder 已创建的前提下，把远程 ARM 机器追加为节点
docker buildx create --name multi --append ssh://user@arm-host
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;追加后用 &lt;code&gt;docker buildx inspect --bootstrap&lt;/code&gt; 能看到 builder 底下挂了两个节点、各负责不同平台。前提是本机能免密 SSH 登录那台 ARM 机器，且对方装了 Docker。这个方案要多维护一台机器，属于团队/高频构建场景的选择；个人项目偶尔构建，用 QEMU 忍一下慢通常就够了。核心结论是：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;先用 QEMU 把多架构跑通，慢到受不了再上原生节点&amp;lt;/span&amp;gt;，不要一上来就折腾集群。&lt;/p&gt;
&lt;h2&gt;给现有项目补上双架构：改造清单&lt;/h2&gt;
&lt;p&gt;如果你手里已经有一批按老办法单架构发布的自建镜像，按下面这个顺序改造，半小时内就能切换到双架构发布，不需要推翻任何现有流程：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;盘点基础镜像&lt;/strong&gt;：把每个项目的 Dockerfile 翻出来，用 &lt;code&gt;imagetools inspect&lt;/code&gt; 逐个确认 &lt;code&gt;FROM&lt;/code&gt; 的基础镜像有没有 arm64 版本。官方主流镜像基本都有；卡住的一般是小众镜像，处理办法是换同类官方基础镜像，或者自己先给它做一份双架构版；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;清理写死架构的地方&lt;/strong&gt;：全局搜 Dockerfile 里的 &lt;code&gt;amd64&lt;/code&gt;、&lt;code&gt;x86_64&lt;/code&gt; 字样，凡是下载地址、文件名里带架构的，全部改成用 &lt;code&gt;TARGETARCH&lt;/code&gt; 拼接（见前面专节）；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;本地跑通一次&lt;/strong&gt;：装 QEMU、建 docker-container 驱动的 builder，在测试标签（比如 &lt;code&gt;1.1-rc1&lt;/code&gt;）上完整走一遍构建、推送、双平台验证，确认没问题再动正式标签；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;切换正式发布命令&lt;/strong&gt;：原来的 &lt;code&gt;docker build&lt;/code&gt;＋&lt;code&gt;docker push&lt;/code&gt; 两条命令，替换成本篇的 &lt;code&gt;docker buildx build --platform ... --push&lt;/code&gt; 一条。镜像名和标签规则保持不变，使用者那边零感知；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;老标签不用管&lt;/strong&gt;：以前发布的单架构老版本标签就留在仓库里，不影响新版本；从切换后的第一个版本起，标签自动变双架构。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;如果你的构建是在 GitHub Actions 里跑的，改造量同样很小：官方提供了现成的动作，流水线里依次加上 &lt;code&gt;docker/setup-qemu-action&lt;/code&gt;（装模拟）、&lt;code&gt;docker/setup-buildx-action&lt;/code&gt;（建 builder）、&lt;code&gt;docker/build-push-action&lt;/code&gt;（构建推送时把 &lt;code&gt;platforms&lt;/code&gt; 参数填上两个平台）即可，逻辑和本地完全一致。云端跑 QEMU 构建的速度同样不快，项目大了记得给流水线留足超时时间，或者只在打正式标签时才触发双架构构建、日常提交只做单架构快速验证，这是很多开源项目在用的折中办法。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;容器一启动就报 &lt;code&gt;exec format error&lt;/code&gt;。&lt;/strong&gt;
架构不对的头号症状。按顺序查：①&lt;code&gt;docker image inspect 镜像 --format &apos;{{.Architecture}}&apos;&lt;/code&gt; 看拉到的镜像架构和 &lt;code&gt;uname -m&lt;/code&gt; 看本机架构是否一致；②镜像是自己构建的，检查构建时有没有带全 &lt;code&gt;--platform&lt;/code&gt;；③镜像架构没错还报错，多半是镜像内部某个二进制选错了架构，回头查 Dockerfile 里有没有写死架构的下载（见 TARGETARCH 一节）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;构建 arm64 步骤时报 &lt;code&gt;exec format error&lt;/code&gt; 或卡死在 RUN 步骤。&lt;/strong&gt;
基本是 QEMU 没装或注册失效（宿主机重启后会失效）。重新执行 &lt;code&gt;docker run --privileged --rm tonistiigi/binfmt --install all&lt;/code&gt;，再 &lt;code&gt;docker buildx inspect --bootstrap&lt;/code&gt; 确认 Platforms 里有 &lt;code&gt;linux/arm64&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;docker buildx build&lt;/code&gt; 提示当前 builder 不支持多平台。&lt;/strong&gt;
你多半还在用默认的 &lt;code&gt;docker&lt;/code&gt; 驱动 builder。执行 &lt;code&gt;docker buildx create --name multi --driver docker-container --use&lt;/code&gt; 切换过去再构建。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;多平台加 &lt;code&gt;--load&lt;/code&gt; 报错 &lt;code&gt;docker exporter does not currently support exporting manifest lists&lt;/code&gt;。&lt;/strong&gt;
预期行为，不是故障。多平台结果改用 &lt;code&gt;--push&lt;/code&gt; 推仓库，再从仓库拉回来验证。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;推送时报 &lt;code&gt;denied&lt;/code&gt; 或 &lt;code&gt;unauthorized&lt;/code&gt;。&lt;/strong&gt;
仓库没登录或没权限。先 &lt;code&gt;docker login&lt;/code&gt; 登录目标仓库；镜像名里的用户名/组织名要和登录账号对得上，个人镜像写成别人的命名空间是推不上去的。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;--platform&lt;/code&gt; 写了但只构建出一个架构。&lt;/strong&gt;
检查写法：平台之间是英文逗号分隔、不能有空格，格式必须是 &lt;code&gt;linux/arm64&lt;/code&gt; 这种「系统/架构」全称，只写 &lt;code&gt;arm64&lt;/code&gt; 不行。改完用 imagetools inspect 复查清单里平台数对不对。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;某一平台构建中途失败，另一平台成功。&lt;/strong&gt;
buildx 默认整体失败退出。先看失败平台卡在哪一步：基础镜像缺该平台版本、下载地址分架构 404、模拟执行超时，这三类最常见，分别对应前面各节的处理办法。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;镜像分架构，amd64 的镜像在 ARM 上启动必然 &lt;code&gt;exec format error&lt;/code&gt;，多架构镜像是唯一的正经解法；&lt;/li&gt;
&lt;li&gt;原理是 manifest list：一份标签挂多份架构 manifest，拉取时按本机架构自动选；&lt;/li&gt;
&lt;li&gt;流程四步：装 QEMU（&lt;code&gt;tonistiigi/binfmt --install all&lt;/code&gt;）→ 创建 &lt;code&gt;docker-container&lt;/code&gt; 驱动的 builder → &lt;code&gt;docker buildx build --platform linux/amd64,linux/arm64 --push&lt;/code&gt; → &lt;code&gt;imagetools inspect&lt;/code&gt; 验证清单；&lt;/li&gt;
&lt;li&gt;多平台结果不能 &lt;code&gt;--load&lt;/code&gt;，只能推仓库，这是机制决定的；&lt;/li&gt;
&lt;li&gt;Dockerfile 里下载二进制务必用 &lt;code&gt;TARGETARCH&lt;/code&gt; 按架构选文件，基础镜像也要先确认有多架构版本；&lt;/li&gt;
&lt;li&gt;QEMU 够用但慢，高频构建再考虑加 ARM 原生节点，别提前过度折腾。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>用 Docker 部署 Caddy：自动 HTTPS 反向代理</title><link>https://www.anexns.cloudns.org/posts/docker-caddy-https/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-caddy-https/</guid><description>Caddy 2 详细教程：为什么它的自动 HTTPS 比 Nginx 省心、Caddyfile 从零讲透、Docker Compose 部署与数据卷的命门、多站点与子域名反代、反代到宿主机服务、内网证书、热重载与排障全流程。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;写在前面：先分清 Caddy 和 Caddy 2&lt;/h2&gt;
&lt;p&gt;Caddy 是一个用 Go 写的 Web 服务器，最出名的本事就一句话：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;HTTPS 全自动&lt;/strong&gt;&amp;lt;/span&amp;gt;。你只要把域名指给它，它自己去 Let&apos;s Encrypt（或 ZeroSSL）申请证书、自己续期、自己把 HTTP 跳转到 HTTPS，不需要 Certbot、不需要写续期定时任务、不需要操心证书文件放哪。&lt;/p&gt;
&lt;p&gt;但网上搜 Caddy 教程有个大坑：&lt;strong&gt;Caddy v1 和 Caddy 2 是两个配置语法完全不兼容的版本&lt;/strong&gt;。v1 早已停止维护，它的配置写法（比如 &lt;code&gt;proxy&lt;/code&gt; 指令、没有大括号的站点写法）拿到现在根本跑不起来。现在还在维护、大家实际在用的都是 &lt;strong&gt;Caddy 2&lt;/strong&gt;：官方镜像就是 &lt;code&gt;caddy:2&lt;/code&gt;（也可以用 &lt;code&gt;caddy:latest&lt;/code&gt;，指向的也是 2.x），配置文件叫 Caddyfile，用的是 v2 语法。本文写的全部是 Caddy 2，后面凡是说「Caddy」，指的都是 Caddy 2。&lt;/p&gt;
&lt;p&gt;上一篇 &lt;a href=&quot;/posts/docker-nginx-https/&quot;&gt;《用 Docker 部署 Nginx 反向代理与自动 HTTPS》&lt;/a&gt; 写了 Nginx 的两条路线（原生 Nginx + Certbot、Nginx Proxy Manager）。这篇的 Caddy 是另一条平行路线：没有图形后台，配置全靠一个文本文件，但自动化程度是三者里最高的。两篇可以对照着看，文末有选型建议。&lt;/p&gt;
&lt;p&gt;本文的主线：先讲清 Caddy 和 Nginx 的区别，再用 Docker Compose 把它部署起来，然后把 Caddyfile 从全局块到每个常用指令逐条讲透，最后是日常运维命令和一整套排障流程。Compose 的基础用法不熟悉的，先看 &lt;a href=&quot;/posts/linux-docker-compose/&quot;&gt;《如何在Linux部署Docker&amp;amp;Compose》&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;Caddy 和 Nginx 反代的核心区别&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;Caddy 2&lt;/th&gt;
&lt;th&gt;Nginx（原生）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;自动 HTTPS&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;开箱即用&lt;/strong&gt;：写个域名就自动申请、续期证书，HTTP 自动跳 HTTPS&lt;/td&gt;
&lt;td&gt;要自己配 Certbot 申请证书、写定时任务续期、手动写跳转规则&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;配置文件&lt;/td&gt;
&lt;td&gt;Caddyfile，一行就能反代一个站点&lt;/td&gt;
&lt;td&gt;nginx.conf，一段 server 配置动辄二三十行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;热重载&lt;/td&gt;
&lt;td&gt;&lt;code&gt;caddy reload&lt;/code&gt; 平滑重载，连接不中断&lt;/td&gt;
&lt;td&gt;&lt;code&gt;nginx -s reload&lt;/code&gt;，也不中断，但要先进容器执行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HTTP/3&lt;/td&gt;
&lt;td&gt;默认开启（需要放行 UDP 443）&lt;/td&gt;
&lt;td&gt;要特定编译版本和额外配置，麻烦&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;WebSocket 反代&lt;/td&gt;
&lt;td&gt;默认支持，零配置&lt;/td&gt;
&lt;td&gt;要手动加 Upgrade/Connection 头&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;静态文件性能&lt;/td&gt;
&lt;td&gt;够用，略逊于 Nginx&lt;/td&gt;
&lt;td&gt;久经考验，高并发静态场景更强&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;生态与资料&lt;/td&gt;
&lt;td&gt;相对小，中文资料少&lt;/td&gt;
&lt;td&gt;极大，搜什么都有现成答案&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;图形后台&lt;/td&gt;
&lt;td&gt;无（有 Admin API，但不是给人点着用的）&lt;/td&gt;
&lt;td&gt;无（NPM 是第三方套壳）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一句话总结：&lt;strong&gt;Caddy 赢在省心，Nginx 赢在生态和极限性能&lt;/strong&gt;。个人服务器、家用 NAS、给自己的几个服务套域名，Caddy 的体验明显更好；公司生产环境、复杂规则、团队都熟 Nginx 的，还是 Nginx。&lt;/p&gt;
&lt;h2&gt;前置准备&lt;/h2&gt;
&lt;p&gt;和 Nginx 篇的口径完全一致，三件事：&lt;/p&gt;
&lt;h3&gt;域名解析到服务器&lt;/h3&gt;
&lt;p&gt;在域名服务商处把 A 记录指向服务器公网 IP，比如 &lt;code&gt;blog.example.com&lt;/code&gt;、&lt;code&gt;api.example.com&lt;/code&gt;。Caddy 申请证书时会通过 HTTP-01 或 TLS-ALPN-01 挑战验证域名归属，&lt;strong&gt;解析没生效就签不下来&lt;/strong&gt;，先确认：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 在任意机器上查解析结果，应该返回你的服务器 IP
dig +short blog.example.com
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;放行 80 和 443 端口&lt;/h3&gt;
&lt;p&gt;云服务器要在云厂商安全组里放行 &lt;strong&gt;TCP 80、TCP 443、UDP 443&lt;/strong&gt;（UDP 443 是 HTTP/3 用的，Nginx 篇没提，Caddy 需要多放行这一条）。本机开了防火墙的再放行一遍：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# ufw
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp

# firewalld
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --permanent --add-port=443/udp
sudo firewall-cmd --reload
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意：如果宿主机上已经跑着 Nginx、Apache 或者另一个 Caddy，80/443 已经被占用，新 Caddy 容器会起不来，先 &lt;code&gt;sudo ss -tlnp | grep -E &apos;:80|:443&apos;&lt;/code&gt; 看一眼谁在占。&lt;/p&gt;
&lt;h3&gt;被反代的服务先「藏好」&lt;/h3&gt;
&lt;p&gt;反代的意义就是让外部只从 Caddy 这一个入口进来，后端服务本身不该再直接暴露公网。后端如果是 Compose 部署的，要么和 Caddy 在同一个 Compose 项目里用服务名互通（下面会讲），要么把端口只绑在 &lt;code&gt;127.0.0.1&lt;/code&gt; 上，别写成 &lt;code&gt;0.0.0.0&lt;/code&gt; 裸奔。&lt;/p&gt;
&lt;h2&gt;Docker Compose 部署 Caddy&lt;/h2&gt;
&lt;h3&gt;目录结构&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;/opt/caddy/
├── docker-compose.yml
└── Caddyfile
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;docker-compose.yml&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;services:
  caddy:
    image: caddy:2
    container_name: caddy
    restart: unless-stopped
    ports:
      - &quot;80:80&quot;
      - &quot;443:443&quot;
      - &quot;443:443/udp&quot;   # HTTP/3 用，不要漏
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐项说明：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;image: caddy:2&lt;/code&gt;：官方镜像，锁大版本 2，既能自动拿到小版本更新，又不会哪天被大版本变更打个措手不及。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;443:443/udp&lt;/code&gt;：Caddy 2 默认开启 HTTP/3，走 UDP 443。这行不写，HTTP/3 用不了（浏览器会自动回落到 HTTP/2，不报错，但白瞎了这个特性），云安全组里也要同步放行 UDP 443。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;./Caddyfile:/etc/caddy/Caddyfile:ro&lt;/code&gt;：把宿主机上的 Caddyfile 以&lt;strong&gt;只读&lt;/strong&gt;方式挂进容器官方约定的配置路径。改配置就在宿主机上改文件，然后让 Caddy 热重载（后面讲），不用进容器。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;caddy_data:/data&lt;/code&gt;：&lt;strong&gt;最重要的一行&lt;/strong&gt;。Caddy 把申请到的证书、私钥、ACME 账户信息全存在 &lt;code&gt;/data&lt;/code&gt; 里，必须持久化到命名卷。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;caddy_config:/config&lt;/code&gt;：Caddy 运行时自动生成的配置（autosave）放这里，同样持久化。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
&lt;code&gt;caddy_data&lt;/code&gt; 这个卷是 Caddy 的命门，千万别删。证书和 ACME 账户都在里面，卷一丢，Caddy 重启后会把所有证书当成新证书重新申请——Let&apos;s Encrypt 对同一域名每周签发的新证书数量有明确上限（还有限制失败验证次数），反复重签很容易撞限额，撞上之后就是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;整整一周签不出证书&lt;/strong&gt;&amp;lt;/span&amp;gt;，所有站点一起裸奔 HTTP。所以：不要手贱 &lt;code&gt;docker volume rm&lt;/code&gt;，不要用 &lt;code&gt;docker compose down -v&lt;/code&gt;（&lt;code&gt;-v&lt;/code&gt; 会连卷一起删），迁移服务器时记得把这个卷一起备份带走，备份方法可以参考本系列的数据备份篇。
:::&lt;/p&gt;
&lt;h3&gt;先写一个最小 Caddyfile 把容器拉起来&lt;/h3&gt;
&lt;p&gt;Caddyfile 的具体语法下一节细讲，这里先放一个能跑的最小版本：把 &lt;code&gt;blog.example.com&lt;/code&gt; 反代到本机 3000 端口的一个服务。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;blog.example.com {
    reverse_proxy 172.17.0.1:3000
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;就这么两行。保存后启动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/caddy
docker compose up -d
docker compose logs -f caddy
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;日志里会看到 Caddy 依次做这些事：向 Let&apos;s Encrypt 注册/加载账户、发起验证、最后打出 &lt;code&gt;certificate obtained successfully&lt;/code&gt;。这时浏览器打开 &lt;code&gt;https://blog.example.com&lt;/code&gt;，应该是小绿锁直接到位，输入 &lt;code&gt;http://blog.example.com&lt;/code&gt; 会自动 301 跳到 HTTPS——这些在 Nginx 那边要写好几段配置的事，这里一行都没写，全是默认行为。&lt;/p&gt;
&lt;h2&gt;Caddyfile 从零讲透&lt;/h2&gt;
&lt;p&gt;Caddyfile 的结构分三层：&lt;strong&gt;全局块&lt;/strong&gt;（可选，最多一个）、&lt;strong&gt;站点块&lt;/strong&gt;（一个域名一个块）、&lt;strong&gt;指令&lt;/strong&gt;（写在站点块里，决定这个站点干什么）。&lt;/p&gt;
&lt;h3&gt;全局块：邮箱一定要写&lt;/h3&gt;
&lt;p&gt;全局块写在文件最顶上，用一对大括号包起来，放全站生效的选项。个人部署最该写的是 &lt;code&gt;email&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
    email admin@example.com
}

blog.example.com {
    reverse_proxy 172.17.0.1:3000
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;email&lt;/code&gt; 是你在 ACME 证书机构（Let&apos;s Encrypt 等）那边的账户邮箱，用途有两个：一是证书快过期又自动续期失败时，官方会往这个邮箱发告警邮件（虽然 Caddy 续期很稳，但留个后手没坏处）；二是万一账户出问题，这是找回的凭据。不写也能签证书，但强烈建议写，而且要写你真实能收到信的邮箱。&lt;/p&gt;
&lt;p&gt;全局块里其他偶尔会用到的：&lt;code&gt;debug&lt;/code&gt;（打开调试日志，排障时临时加）、&lt;code&gt;default_sni&lt;/code&gt;（给那些没带 SNI 的老客户端兜底，一般用不上）。记住一个原则：全局块只放全站统一的东西，单个站点的行为写进各自的站点块。&lt;/p&gt;
&lt;h3&gt;站点块：第一行是地址&lt;/h3&gt;
&lt;p&gt;站点块的第一行是「站点地址」，几种常见写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;example.com { ... }          # 域名：自动 HTTPS，自动跳转
www.example.com { ... }      # 子域名同理
example.com, www.example.com { ... }   # 多个地址共用一份配置，逗号分隔
http://example.com { ... }   # 显式带 http:// 前缀：只走 HTTP，不签证书
:8080 { ... }                # 只写端口：任意域名/IP 访问这个端口都响应，纯 HTTP
localhost { ... }            # 本地名：自动用内部 CA 签证书（见后面 tls internal）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里藏着 Caddy 自动 HTTPS 的触发规则：&lt;strong&gt;站点地址是正经公网域名 → 自动走公网证书；是 &lt;code&gt;localhost&lt;/code&gt;、内网域名或 IP → 自动用内部 CA&lt;/strong&gt;。不用你声明，它自己判断。&lt;/p&gt;
&lt;h3&gt;核心指令：reverse_proxy 一行反代&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;reverse_proxy&lt;/code&gt; 是整篇用得最多的指令，最简形式就是「指令 + 后端地址」：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;api.example.com {
    reverse_proxy 127.0.0.1:8080
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;和 Nginx 那边对比一下就知道有多省事：Nginx 要写 &lt;code&gt;proxy_pass&lt;/code&gt; 再加四行 &lt;code&gt;proxy_set_header&lt;/code&gt;，而 Caddy 的 &lt;code&gt;reverse_proxy&lt;/code&gt; &lt;strong&gt;默认就帮你做好了这些&lt;/strong&gt;：自动设置 &lt;code&gt;X-Forwarded-For&lt;/code&gt;、&lt;code&gt;X-Forwarded-Proto&lt;/code&gt;、&lt;code&gt;X-Forwarded-Host&lt;/code&gt; 三个头、原样透传客户端的 Host、WebSocket 直接支持。所以绝大多数场景，一行就是完整配置，不要画蛇添足。&lt;/p&gt;
&lt;h3&gt;一份完整的多站点 Caddyfile&lt;/h3&gt;
&lt;p&gt;把前面讲的拼起来，一台服务器跑四个站点的真实配置长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
    email admin@example.com
}

# 主站：静态文件由 Caddy 自己托管
example.com {
    root * /srv/www
    encode zstd gzip
    file_server
}

# 博客：反代到本机 3000 端口的服务
blog.example.com {
    reverse_proxy 172.17.0.1:3000
}

# 网盘：反代到同一 Compose 里的服务（服务名直达，下面细讲）
drive.example.com {
    reverse_proxy app:8080
}

# 老域名整体跳转到新域名
old.example.com {
    redir https://example.com{uri} permanent
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;root * /srv/www&lt;/code&gt; 里的 &lt;code&gt;*&lt;/code&gt; 是匹配符（表示匹配所有请求），是 Caddyfile 里 &lt;code&gt;root&lt;/code&gt; 指令的固定写法，不是笔误。静态托管需要把宿主机的网站目录挂进容器，在 compose 里给 caddy 服务加一行 &lt;code&gt;- ./www:/srv/www:ro&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;这份文件保存后不用重启容器，执行一次热重载就生效（运维命令那一节讲）。新增一个站点，就是往文件里多加一个站点块再 reload 一次，如此而已。&lt;/p&gt;
&lt;h2&gt;常用指令逐条讲&lt;/h2&gt;
&lt;p&gt;Caddyfile 的指令（directive）有几十个，日常真正高频的就下面这些。每个都给可直接抄的例子。&lt;/p&gt;
&lt;h3&gt;encode：开 gzip / zstd 压缩&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;blog.example.com {
    encode zstd gzip
    reverse_proxy 172.17.0.1:3000
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;给文本类响应开压缩，网页、JSON 接口都能明显变小。zstd 比 gzip 压缩率更好、速度更快，现代浏览器都支持；两个都写上，Caddy 会按浏览器支持情况自动选，老浏览器回落 gzip。后端如果自己已经开了压缩，这里可以不写，避免双重压缩。&lt;/p&gt;
&lt;h3&gt;header：加安全响应头&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;blog.example.com {
    header {
        X-Content-Type-Options nosniff
        X-Frame-Options SAMEORIGIN
        Referrer-Policy strict-origin-when-cross-origin
        -Server
    }
    reverse_proxy 172.17.0.1:3000
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;header&lt;/code&gt; 块里每行一个头。最后一个 &lt;code&gt;-Server&lt;/code&gt; 是特殊写法：&lt;strong&gt;减号表示删掉这个响应头&lt;/strong&gt;，把 Caddy 默认带出去的 &lt;code&gt;Server: Caddy&lt;/code&gt; 去掉，少给扫描器一点信息。后端应用自己设置的同名头优先级更高，不会被这里覆盖掉需要时可以用 &lt;code&gt;header&lt;/code&gt; 的替换语法细调，日常上面四行够用了。&lt;/p&gt;
&lt;h3&gt;redir：跳转&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;example.com {
    redir https://www.example.com{uri} permanent
}

www.example.com {
    reverse_proxy 172.17.0.1:3000
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这是「裸域名跳 www」的经典写法：&lt;code&gt;{uri}&lt;/code&gt; 是占位符，代表原始请求的完整路径（含查询字符串），保证 &lt;code&gt;example.com/a?x=1&lt;/code&gt; 跳过去还是 &lt;code&gt;/a?x=1&lt;/code&gt;。&lt;code&gt;permanent&lt;/code&gt; 表示 301 永久跳转，不写默认是 302 临时跳转。注意带了域名地址的站点块会自动做 HTTP→HTTPS 跳转，这里写的是域名之间的跳转，两回事，别混。&lt;/p&gt;
&lt;p&gt;站内路径跳转也一样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;blog.example.com {
    redir /old-post /new-post permanent
    reverse_proxy 172.17.0.1:3000
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;handle_path：剥掉路径前缀再转发&lt;/h3&gt;
&lt;p&gt;有些后端服务自己不知道自己挂在子路径下，比如一个只认根路径的面板，你想用 &lt;code&gt;example.com/panel/&lt;/code&gt; 访问它：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;example.com {
    handle_path /panel/* {
        reverse_proxy 172.17.0.1:9000
    }
    reverse_proxy 172.17.0.1:3000
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;handle_path&lt;/code&gt; 会先把 &lt;code&gt;/panel&lt;/code&gt; 前缀&lt;strong&gt;剥掉&lt;/strong&gt;再转发：请求 &lt;code&gt;/panel/login&lt;/code&gt; 到后端时变成 &lt;code&gt;/login&lt;/code&gt;，后端按根路径处理毫无感知；块外面那条 &lt;code&gt;reverse_proxy&lt;/code&gt; 兜底处理其余所有请求。对照组是 &lt;code&gt;handle&lt;/code&gt; 指令——用法一样但&lt;strong&gt;不剥前缀&lt;/strong&gt;，后端收到的还是 &lt;code&gt;/panel/login&lt;/code&gt;，后端本身就部署在子路径时用它。两个指令别用混，这是新手最常踩的点之一。&lt;/p&gt;
&lt;h3&gt;basicauth：给站点加一层账号密码&lt;/h3&gt;
&lt;p&gt;临时给某个管理后台挡一道最简单的门：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;admin.example.com {
    basicauth {
        admin $2a$14$uJ8exampleHashValueDoNotCopyThisOne9eKxYzAbCdEfGhIjKlM
    }
    reverse_proxy 172.17.0.1:9000
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;密码不能写明文&amp;lt;/span&amp;gt;，必须是 bcrypt 哈希。用官方命令生成：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose exec caddy caddy hash-password
# 按提示输入两遍密码，输出的一串 $2a$14$... 就是要填进配置的哈希
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;生成好填进配置再 reload，访问站点会先弹浏览器的账号密码框。说明清楚：basicauth 只是「简单挡一下」，强度有限，真正的管理后台还应该有自己的登录体系，它适合套在已经有登录的后台外面做双保险，或者给纯静态的内部页面用。&lt;/p&gt;
&lt;h3&gt;file_server：托管静态站&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docs.example.com {
    root * /srv/docs
    encode zstd gzip
    file_server
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把目录挂进容器（compose 里加 &lt;code&gt;- ./docs:/srv/docs:ro&lt;/code&gt;），三行就是一个带自动 HTTPS 的静态站。想让目录可浏览（显示文件列表）就写 &lt;code&gt;file_server browse&lt;/code&gt;；想做单页应用（SPA）那种「路径不存在就回 index.html」，再加一行 &lt;code&gt;try_files {path} /index.html&lt;/code&gt; 并用 &lt;code&gt;handle&lt;/code&gt; 包一下，日常静态托管用不上这么细，知道有这个能力即可。&lt;/p&gt;
&lt;h3&gt;tls internal：给内网签内部证书&lt;/h3&gt;
&lt;p&gt;有些服务只在家里/内网用，没有公网域名，只有 &lt;code&gt;nas.home&lt;/code&gt; 这种内网名字，或者干脆用 IP 访问。公网 CA 不可能给这种名字签证书，Caddy 的解法是&lt;strong&gt;自己当 CA&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;nas.home {
    tls internal
    reverse_proxy 172.17.0.1:5000
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;加上 &lt;code&gt;tls internal&lt;/code&gt; 后，Caddy 用它内置的本地 CA 给这个站点签证书，HTTPS 照样成立。其实对 &lt;code&gt;localhost&lt;/code&gt;、IP 地址这类站点，Caddy 默认就会自动用内部 CA，&lt;code&gt;tls internal&lt;/code&gt; 是把这件事写明、或在域名看起来像公网域名时强制走内部签发。&lt;/p&gt;
&lt;p&gt;代价在客户端这一侧：浏览器不认识这个自建 CA，第一次访问会报证书不受信任。把根证书装进设备就一劳永逸了——根证书文件在数据卷里：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/data/caddy/pki/authorities/local/root.crt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;从容器里把它拷出来，装到手机/电脑的受信任根证书里，之后所有 &lt;code&gt;tls internal&lt;/code&gt; 的站点都是绿锁：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
这张根证书的私钥就躺在 &lt;code&gt;caddy_data&lt;/code&gt; 卷里，它能签出&lt;strong&gt;任意域名&lt;/strong&gt;的「可信」证书。装了它的设备，等于无条件信任这台服务器冒充任何网站。所以&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;根证书只装自己的设备&amp;lt;/span&amp;gt;，卷文件别外传——这也是 &lt;code&gt;caddy_data&lt;/code&gt; 不能丢、更不能泄的第二个理由。
:::&lt;/p&gt;
&lt;h2&gt;反代进阶&lt;/h2&gt;
&lt;h3&gt;反代到同一个 Compose 里的服务：用服务名&lt;/h3&gt;
&lt;p&gt;如果后端和 Caddy 写在同一个 docker-compose.yml 里（或者接入了同一个 Docker 网络），直接用服务名当地址：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  caddy:
    image: caddy:2
    # ...同前，略
  app:
    image: myapp:latest
    # 注意：app 不需要写 ports，它根本不用对外露头
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;app.example.com {
    reverse_proxy app:8080
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;app:8080&lt;/code&gt; 里的 8080 是&lt;strong&gt;容器内部&lt;/strong&gt;的端口，不是宿主机映射端口。这种写法下后端连 &lt;code&gt;ports&lt;/code&gt; 都不用写，外部完全摸不到它，只能经 Caddy 进，干净又安全，是 Caddy（以及所有 Docker 反代）最推荐的组网方式。&lt;/p&gt;
&lt;h3&gt;反代到宿主机上的服务：172.17.0.1&lt;/h3&gt;
&lt;p&gt;后端不在容器里、直接跑在宿主机上（比如宿主机进程监听的 3000 端口），或者在另一个 Compose 项目里已经映射到了宿主机端口，这时在 Caddyfile 里写：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;blog.example.com {
    reverse_proxy 172.17.0.1:3000
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;172.17.0.1&lt;/code&gt; 是 Docker 默认网桥 &lt;code&gt;docker0&lt;/code&gt; 在宿主机一侧的网关地址，从容器里访问它，就等于访问宿主机本人。这和 Nginx 篇里给 NPM 填上游时用 &lt;code&gt;172.17.0.1:&amp;lt;端口&amp;gt;&lt;/code&gt; 是同一个道理：不用把反代容器硬塞进每个业务的 Docker 网络里，反代和业务解耦，各管各的。两个注意点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;后端服务监听地址不能是 &lt;code&gt;127.0.0.1&lt;/code&gt;——那样只有宿主机自己能连，容器经网桥进来会被拒。要监听 &lt;code&gt;0.0.0.0&lt;/code&gt; 或干脆监听 &lt;code&gt;172.17.0.1&lt;/code&gt;，同时用防火墙挡住公网方向（云安全组不放行该端口即可，Docker 映射端口绕过 ufw 的坑在网络篇里讲过）。&lt;/li&gt;
&lt;li&gt;如果你改过默认网桥网段或用的是自定义网络，网关地址会变，进容器执行 &lt;code&gt;ip route&lt;/code&gt; 看 &lt;code&gt;default via&lt;/code&gt; 后面的地址，那就是宿主机。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;header_up：给后端补头&lt;/h3&gt;
&lt;p&gt;前面说过 X-Forwarded 三件套 Caddy 默认就带，但有些老应用认 &lt;code&gt;X-Real-IP&lt;/code&gt;，或者你想额外传个自定义头，这时在 &lt;code&gt;reverse_proxy&lt;/code&gt; 里套一个块，用 &lt;code&gt;header_up&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;api.example.com {
    reverse_proxy 127.0.0.1:8080 {
        header_up X-Real-IP {remote_host}
        header_up X-Custom-Flag internal
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;{remote_host}&lt;/code&gt; 是占位符，表示客户端 IP；同类常用的还有 &lt;code&gt;{host}&lt;/code&gt;（请求的域名）、&lt;code&gt;{scheme}&lt;/code&gt;（http/https）。反过来 &lt;code&gt;header_down&lt;/code&gt; 是改写后端返回的响应头，日常用得少。&lt;/p&gt;
&lt;p&gt;还有一个进阶场景顺带提一句：如果 Caddy 前面还套了一层 CDN 或另一层代理，&lt;code&gt;{remote_host}&lt;/code&gt; 拿到的是上一层代理的 IP 而不是真实用户 IP，需要在 &lt;code&gt;reverse_proxy&lt;/code&gt; 块里用 &lt;code&gt;trusted_proxies&lt;/code&gt; 声明信任的代理网段，Caddy 才会采信对方传来的 &lt;code&gt;X-Forwarded-For&lt;/code&gt;。没套 CDN 的不用管这段。&lt;/p&gt;
&lt;h3&gt;WebSocket：默认就支持，什么都不用写&lt;/h3&gt;
&lt;p&gt;再强调一遍因为太多人从 Nginx 过来会习惯性找这个配置：Caddy 的 &lt;code&gt;reverse_proxy&lt;/code&gt; &lt;strong&gt;天生支持 WebSocket&lt;/strong&gt;，连接升级（Upgrade）是自动透传的。不需要任何额外指令，Nginx 那边要加的三行头在 Caddy 这边不存在。你的应用有实时推送、在线终端这类长连接，直接反代就是能用的。&lt;/p&gt;
&lt;h3&gt;负载均衡：多后端就写多个地址&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;app.example.com {
    reverse_proxy 172.17.0.1:3001 172.17.0.1:3002 172.17.0.1:3003 {
        lb_policy round_robin
        health_uri /healthz
        health_interval 10s
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;同一行空格分隔写多个后端地址，Caddy 自动在它们之间分发请求。&lt;code&gt;lb_policy&lt;/code&gt; 是分发策略，&lt;code&gt;round_robin&lt;/code&gt;（轮询）最常用，还有 &lt;code&gt;least_conn&lt;/code&gt;（谁空闲给谁）、&lt;code&gt;ip_hash&lt;/code&gt;（同一用户固定落到同一后端）等。&lt;code&gt;health_uri&lt;/code&gt; + &lt;code&gt;health_interval&lt;/code&gt; 开主动健康检查：Caddy 每 10 秒探一次每个后端的 &lt;code&gt;/healthz&lt;/code&gt;，探不通的自动摘掉、恢复了再放回来。哪怕不用负载均衡，单个后端也可以只开健康检查图个安心——不过个人部署多后端是少数，这一节知道写法即可。&lt;/p&gt;
&lt;h2&gt;进阶：DNS 验证与通配符证书&lt;/h2&gt;
&lt;p&gt;前面用的都是默认的 HTTP-01 / TLS-ALPN-01 验证，前提是 80/443 能从公网摸到。两种情况这条路走不通：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;你想要一张 &lt;strong&gt;通配符证书&lt;/strong&gt;（&lt;code&gt;*.example.com&lt;/code&gt;，所有子域名共用一张）——CA 规定通配符只能走 DNS 验证；&lt;/li&gt;
&lt;li&gt;服务器的 80 端口被运营商封了，或者机器压根没有公网入口。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;DNS 验证的原理是让 Caddy 调用域名服务商的 API，自动往 DNS 里塞一条 TXT 记录证明域名是你的。但官方镜像&lt;strong&gt;不带任何 DNS 服务商插件&lt;/strong&gt;，需要用官方提供的构建方式把插件编进自己的镜像，这就是 xcaddy 的用途——不用怕，它就是官方镜像的标准扩展姿势：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;FROM caddy:2-builder AS builder
RUN xcaddy build --with github.com/caddy-dns/cloudflare

FROM caddy:2
COPY --from=builder /usr/bin/caddy /usr/bin/caddy
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把 compose 里的 &lt;code&gt;image: caddy:2&lt;/code&gt; 换成 &lt;code&gt;build: .&lt;/code&gt;（Dockerfile 放同目录），再在全局块里声明用哪家 DNS 验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
    email admin@example.com
    acme_dns cloudflare {env.CF_API_TOKEN}
}

*.example.com {
    tls {
        dns cloudflare {env.CF_API_TOKEN}
    }
    reverse_proxy 172.17.0.1:3000
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;API Token 通过 compose 的 &lt;code&gt;environment&lt;/code&gt; 以 &lt;code&gt;CF_API_TOKEN&lt;/code&gt; 注入，别把令牌明文写进 Caddyfile 和 Git。各家服务商的插件名和参数不一样（阿里云、DNSPod 都有社区插件），用之前去 Caddy 官方的下载页确认插件仓库名，不要照抄来路不明的镜像——带插件的第三方预构建镜像等于&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把证书私钥托付给陌生人&amp;lt;/span&amp;gt;，这类供应链风险在安全篇里专门讲过。个人部署如果只是 80 被封，更简单的办法是先想办法放行端口，DNS 验证留给真需要通配符的人。&lt;/p&gt;
&lt;h2&gt;日常运维命令&lt;/h2&gt;
&lt;p&gt;Caddy 的运维全部围绕一个原则：&lt;strong&gt;改宿主机上的 Caddyfile → 校验 → 热重载&lt;/strong&gt;，容器不用重启，正在传输的连接不会断。命令都通过 &lt;code&gt;docker compose exec caddy&lt;/code&gt; 在容器里执行官方 CLI。&lt;/p&gt;
&lt;h3&gt;改完先校验：validate 和 adapt&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 语法校验：配置有错会明确指出第几行什么问题，没问题输出 Valid configuration
docker compose exec caddy caddy validate --config /etc/caddy/Caddyfile

# 把 Caddyfile 翻译成 Caddy 实际运行的 JSON 配置（预览用）
docker compose exec caddy caddy adapt --config /etc/caddy/Caddyfile --pretty
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;validate&lt;/code&gt; 是改配置后的第一道保险，先跑它再 reload，能避免把一份写错的配置推上线。&lt;code&gt;adapt&lt;/code&gt; 则把人类友好的 Caddyfile 展开成底层 JSON——Caddy 内部真正跑的是 JSON，Caddyfile 只是它的「方言」。排障时怀疑某条指令没按预期生效，把 adapt 的输出拿出来看最踏实。顺带记住：既然能 adapt 成 JSON，Caddyfile 不是唯一写法，只是对人最友好的那一种。&lt;/p&gt;
&lt;h3&gt;热重载：reload 不中断&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;reload&lt;/code&gt; 会让 Caddy 平滑换上新配置：新连接走新配置，老连接在旧配置上自然结束，证书该复用的复用，不会重新申请。养成习惯——&lt;strong&gt;改完 Caddyfile 永远先 validate、再 reload，永远不要用重启容器代替 reload&lt;/strong&gt;。重启虽然也能加载新配置，但会断开所有连接，而且一旦新配置有硬错误，容器直接起不来，站点全灭；reload 遇到坏配置则会拒绝应用、继续跑旧配置，安全得多。&lt;/p&gt;
&lt;p&gt;:::warning
如果你把 Caddyfile 以只读（&lt;code&gt;:ro&lt;/code&gt;）方式挂载（本文的 compose 就是这么写的），&lt;code&gt;caddy fmt --overwrite&lt;/code&gt; 这类要回写文件的命令在容器里会失败，这是正常的，不是配置坏了。格式化直接在宿主机上对源文件做，或者不带 &lt;code&gt;--overwrite&lt;/code&gt; 只看输出。只读挂载的好处是容器被攻破也改不了你的配置源文件，这个取舍值得。
:::&lt;/p&gt;
&lt;h3&gt;格式化：caddy fmt&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 输出格式化后的内容（不改文件），先看看它想把缩进改成什么样
docker compose exec caddy caddy fmt /etc/caddy/Caddyfile

# 在宿主机上直接格式化源文件（推荐姿势）
docker run --rm -v ./Caddyfile:/tmp/Caddyfile caddy:2 caddy fmt --overwrite /tmp/Caddyfile
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Caddyfile 对缩进不敏感，但统一格式能让多站点配置一眼看清结构。多人维护或站点多了以后，改完顺手 fmt 一次，diff 会非常干净。&lt;/p&gt;
&lt;h3&gt;看日志：证书都签了什么&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker compose logs -f caddy
docker compose logs --tail 100 caddy | grep -i &quot;certificate&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Caddy 的日志是结构化 JSON，信息量很大。重点认这几行：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;日志关键字&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;certificate obtained successfully&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;签发成功，后面会带域名&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;certificate expires&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不是报错，只是告知到期时间（续期是自动的，看到它不用慌）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;renewed certificate&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;自动续期完成&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;平时不用盯，真出问题时日志基本能直接告诉你卡在哪一步——是 DNS 没解析、是验证被拒、还是限额了。&lt;/p&gt;
&lt;h2&gt;排障全流程&lt;/h2&gt;
&lt;h3&gt;证书签不下来&lt;/h3&gt;
&lt;p&gt;站点打开是证书错误，或者日志里反复出现获取证书失败，按这个顺序查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;解析生效了吗&lt;/strong&gt;：&lt;code&gt;dig +short 你的域名&lt;/code&gt;，返回的必须是这台服务器的公网 IP。刚改的解析等 10 分钟再试，别拿缓存结果误判。用了 CDN 代理（比如 Cloudflare 小黄云）的，先切回仅 DNS 模式签一次，签好再开代理，或者改用 DNS 验证方式，这是最高频的翻车点。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;80/443 真的通吗&lt;/strong&gt;：在另一台机器上 &lt;code&gt;curl -v http://你的域名&lt;/code&gt;，看能不能摸到服务器。云安全组、本机防火墙、运营商封 80，任何一层都能让验证失败。Caddy 的 HTTP-01 验证走 80，TLS-ALPN-01 走 443，两个都堵死必然签不下来。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;端口被别人占了吗&lt;/strong&gt;：&lt;code&gt;sudo ss -tlnp | grep -E &apos;:80|:443&apos;&lt;/code&gt;。宿主机上还跑着一个没关的 Nginx 是经典剧本——Caddy 容器日志里会有 &lt;code&gt;bind: address already in use&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;是不是撞限额了&lt;/strong&gt;：日志里出现 &lt;code&gt;too many certificates already issued&lt;/code&gt; 或 &lt;code&gt;rateLimited&lt;/code&gt; 字样，就是 Let&apos;s Encrypt 限额。最常见的触发方式就是前面 warning 里说的：反复删 &lt;code&gt;caddy_data&lt;/code&gt; 卷反复重签。没有别的办法，只能等窗口过去（以天和周计），期间把卷保护好，别再折腾。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;访问站点返回 502&lt;/h3&gt;
&lt;p&gt;Caddy 本身活着、证书也没问题，但页面是 502，说明它联系不上后端：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;后端起了吗&lt;/strong&gt;：&lt;code&gt;docker compose ps&lt;/code&gt; 或到后端所在项目里看容器状态，后端自己挂了 Caddy 当然只能 502。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;地址写对了吗&lt;/strong&gt;：日志里搜 &lt;code&gt;dial tcp&lt;/code&gt;，后面的报错最说明问题——&lt;code&gt;connection refused&lt;/code&gt; 是目标端口没人听；&lt;code&gt;no such host&lt;/code&gt; 是服务名解析不了（多半是两个容器根本不在同一个 Docker 网络里，或者服务名写错）；连到 &lt;code&gt;127.0.0.1&lt;/code&gt; 却想找宿主机服务，是忘了容器里的 127.0.0.1 是容器自己，该用 &lt;code&gt;172.17.0.1&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;后端监听地址对吗&lt;/strong&gt;：后端只监听 &lt;code&gt;127.0.0.1&lt;/code&gt; 时，同网络的 Caddy 用服务名也连不上它（它只认本机回环）。让后端监听 &lt;code&gt;0.0.0.0&lt;/code&gt;，暴露面靠「不映射 ports + 只经 Caddy 入口」来控制，而不是靠绑回环。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;配置改了不生效&lt;/h3&gt;
&lt;p&gt;十有八九是这三件事之一：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;改完没 reload&lt;/strong&gt;。Caddy 不会监视文件变化，改 Caddyfile 后必须执行 &lt;code&gt;caddy reload&lt;/code&gt;（或重启容器）。这是新手第一大坑，没有之一。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;改错了文件&lt;/strong&gt;。确认你编辑的就是 compose 里挂载的那个 Caddyfile，&lt;code&gt;docker compose config&lt;/code&gt; 能看到实际挂载路径；进容器 &lt;code&gt;cat /etc/caddy/Caddyfile&lt;/code&gt; 对一眼内容是不是你以为的那份。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;reload 的其实是旧配置&lt;/strong&gt;。&lt;code&gt;caddy reload&lt;/code&gt; 要带对 &lt;code&gt;--config&lt;/code&gt; 路径；图省事直接 &lt;code&gt;docker compose restart caddy&lt;/code&gt; 也能加载新配置（代价是断连接），两种方式都无效，就该怀疑改的根本不是同一份文件了。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;HTTP/3 的小坑&lt;/h3&gt;
&lt;p&gt;HTTP/3 默认开着，一般不用管。唯一常见的现象是：某些网络环境（公司网、部分运营商）会拦截或劣化 UDP 流量，表现为个别访客打开网站慢半拍——浏览器会自动回落到 HTTP/2/TCP，不会真打不开，属可接受范围。真遇到整片网络都异常，在全局块里关掉即可：全局块加一行 &lt;code&gt;servers { protocols h1 h2 }&lt;/code&gt; 只保留 HTTP/1.1 和 HTTP/2。这属于极端情况的兜底，正常部署别关，自找麻烦。&lt;/p&gt;
&lt;h2&gt;和 Nginx 怎么选：选型小结&lt;/h2&gt;
&lt;p&gt;把这一篇和 &lt;a href=&quot;/posts/docker-nginx-https/&quot;&gt;Nginx 篇&lt;/a&gt; 合起来看，选型其实很简单：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;推荐&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;个人服务器 / NAS，就想给几个服务套域名上 HTTPS&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Caddy&lt;/strong&gt;：一行配置，证书全自动，省心到底&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;频繁加新站点、改配置&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Caddy&lt;/strong&gt;：加个站点块 + reload，半分钟的事&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;内网服务也要 HTTPS&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Caddy&lt;/strong&gt;：&lt;code&gt;tls internal&lt;/code&gt; 是 Nginx 方案里没有的顺手&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;需要图形后台、点点鼠标就完成&lt;/td&gt;
&lt;td&gt;Nginx Proxy Manager：Caddy 没有官方 GUI&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;高并发静态资源、复杂 rewrite/缓存规则&lt;/td&gt;
&lt;td&gt;Nginx：生态和调优空间更大&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;团队协作、大家只会 Nginx&lt;/td&gt;
&lt;td&gt;Nginx：工具再好，也得团队会用才行&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;现在用的都是 &lt;strong&gt;Caddy 2&lt;/strong&gt;，镜像 &lt;code&gt;caddy:2&lt;/code&gt;，配置是 Caddyfile v2 语法；网上 v1 老教程直接跳过。&lt;/li&gt;
&lt;li&gt;Caddy 的核心竞争力是&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;自动 HTTPS 开箱即用&lt;/strong&gt;&amp;lt;/span&amp;gt;：公网域名自动签发续期、HTTP 自动跳 HTTPS、WebSocket 和 X-Forwarded 头默认就带，Nginx 那边一摞配置在这里通常只剩一行 &lt;code&gt;reverse_proxy&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;部署时两个卷必须持久化，其中 &lt;strong&gt;&lt;code&gt;caddy_data&lt;/code&gt; 是命门&lt;/strong&gt;：丢了会反复重签撞 Let&apos;s Encrypt 限额，内部 CA 的根证书也在里面，只能装自己的设备。&lt;/li&gt;
&lt;li&gt;Caddyfile 三层结构记牢：全局块写 &lt;code&gt;email&lt;/code&gt;、站点块第一行是地址、块里放指令；&lt;code&gt;reverse_proxy&lt;/code&gt;、&lt;code&gt;encode&lt;/code&gt;、&lt;code&gt;header&lt;/code&gt;、&lt;code&gt;redir&lt;/code&gt;、&lt;code&gt;handle_path&lt;/code&gt;、&lt;code&gt;basicauth&lt;/code&gt;、&lt;code&gt;file_server&lt;/code&gt;、&lt;code&gt;tls internal&lt;/code&gt; 这八条覆盖日常九成需求。&lt;/li&gt;
&lt;li&gt;反代组网优先用&lt;strong&gt;服务名直达&lt;/strong&gt;（后端连 ports 都不用开），反代宿主机服务用 &lt;strong&gt;&lt;code&gt;172.17.0.1:&amp;lt;端口&amp;gt;&lt;/code&gt;&lt;/strong&gt; 与业务解耦。&lt;/li&gt;
&lt;li&gt;运维铁律：改配置先 &lt;code&gt;caddy validate&lt;/code&gt; 再 &lt;code&gt;caddy reload&lt;/code&gt;，别拿重启容器当重载；排障先看日志，证书、502、不生效三大类按本文顺序查基本都能定位。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>CI/CD 全流水线：从代码提交到自动上线</title><link>https://www.anexns.cloudns.org/posts/docker-cicd-pipeline/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-cicd-pipeline/</guid><description>把整个系列串成一条自动化链路：GitHub Actions 自动构建镜像并推送到仓库，服务器用 Watchtower 自动拉取上线，标签策略、密钥管理与回滚预案一并讲清，改完代码 push 一下就部署。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;写到这一篇，前面的零件都齐了：Dockerfile 会写了（见 Dockerfile 入门篇），多架构构建会玩了，私有仓库也搭得起来，自动更新也有 Watchtower 盯着。还差最后一件事：把这些零件串成一条自动流水线。&lt;/p&gt;
&lt;p&gt;手动部署过项目的人都懂那种重复劳动：改一行代码，然后 SSH 上服务器，&lt;code&gt;git pull&lt;/code&gt;、构建、停容器、起容器、看日志，十分钟没了，一天来上三五回，人就成了部署工具人。CI/CD 要解决的就是这件事：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;代码 push 到 GitHub，剩下的构建、推送、上线全部自动完成，你只负责看结果。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;这一篇的主线如下：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;先看全景：五个环节各自在干什么；&lt;/li&gt;
&lt;li&gt;选镜像仓库：GHCR、Docker Hub、自建 Registry 三者怎么选；&lt;/li&gt;
&lt;li&gt;写一份完整的 GitHub Actions 工作流，逐段拆解；&lt;/li&gt;
&lt;li&gt;定标签策略与 Secrets 管理这两条纪律；&lt;/li&gt;
&lt;li&gt;服务器侧用 Watchtower 衔接自动上线，并与 SSH 部署路线做对比；&lt;/li&gt;
&lt;li&gt;上线后验证、失败处理与回滚预案；&lt;/li&gt;
&lt;li&gt;最后是排障小节。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;读完这一篇，你的部署动作将只剩一个：&lt;code&gt;git push&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;一、全景图：五个环节各自干什么&lt;/h2&gt;
&lt;p&gt;先把整条链路在脑子里过一遍，后面每一节都是在填其中一个环节的细节。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;环节&lt;/th&gt;
&lt;th&gt;发生在哪&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;th&gt;用到的工具&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1. 提交&lt;/td&gt;
&lt;td&gt;本地电脑&lt;/td&gt;
&lt;td&gt;改代码、&lt;code&gt;git push&lt;/code&gt; 到 GitHub&lt;/td&gt;
&lt;td&gt;Git&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2. 构建&lt;/td&gt;
&lt;td&gt;GitHub 的云端机器&lt;/td&gt;
&lt;td&gt;拉代码、按 Dockerfile 构建镜像&lt;/td&gt;
&lt;td&gt;GitHub Actions + Buildx&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3. 推送&lt;/td&gt;
&lt;td&gt;GitHub 的云端机器&lt;/td&gt;
&lt;td&gt;把镜像推到镜像仓库存好&lt;/td&gt;
&lt;td&gt;GHCR / Docker Hub / 自建 Registry&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4. 上线&lt;/td&gt;
&lt;td&gt;你的服务器&lt;/td&gt;
&lt;td&gt;发现新镜像、拉下来、换掉旧容器&lt;/td&gt;
&lt;td&gt;Watchtower&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5. 验证&lt;/td&gt;
&lt;td&gt;服务器与你&lt;/td&gt;
&lt;td&gt;健康检查通过、服务可访问；失败则回滚&lt;/td&gt;
&lt;td&gt;curl 健康检查 / 回滚命令&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;有几个关键点先说清楚：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;构建不在你的服务器上做&lt;/strong&gt;。构建吃 CPU 和内存，小配置 VPS 构建一次能卡到服务无响应。GitHub Actions 的公共仓库免费额度足够个人项目用，构建在云端跑完，服务器只负责拉现成镜像，又快又稳。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;服务器不存代码、不存密钥&lt;/strong&gt;。服务器上只有一个 Compose 文件和一个 Watchtower，它甚至不需要知道 GitHub 上发生了什么，只盯着镜像仓库看标签有没有变。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;整条链路是单向的&lt;/strong&gt;。代码从本地流向 GitHub，再流向镜像仓库，最后流向服务器。任何一环出问题，都不会把脏东西带回上一环。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这套结构还有一个隐形好处：部署过程全部留痕。哪次上线对应哪个 commit、哪个镜像标签，在 GitHub 的 Actions 页面和镜像仓库里都查得到，出了问题甩不了锅，也赖不掉账。&lt;/p&gt;
&lt;h2&gt;二、镜像推哪：GHCR、Docker Hub 与自建 Registry&lt;/h2&gt;
&lt;p&gt;构建出来的镜像得有个地方存。三个主流选择，先给结论再给对比：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;GHCR（GitHub Container Registry）&lt;/th&gt;
&lt;th&gt;Docker Hub&lt;/th&gt;
&lt;th&gt;自建 Registry&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;地址&lt;/td&gt;
&lt;td&gt;ghcr.io&lt;/td&gt;
&lt;td&gt;docker.io&lt;/td&gt;
&lt;td&gt;你自己的域名&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;费用&lt;/td&gt;
&lt;td&gt;公共镜像免费；私有镜像按 GitHub 套餐额度&lt;/td&gt;
&lt;td&gt;免费版有限制，私有仓库数量受限&lt;/td&gt;
&lt;td&gt;只花服务器与流量成本&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;登录凭证&lt;/td&gt;
&lt;td&gt;GitHub Token（Actions 里自动有）&lt;/td&gt;
&lt;td&gt;Docker Hub 账号密码 / Access Token&lt;/td&gt;
&lt;td&gt;自己配的账号密码&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;与 GitHub 的衔接&lt;/td&gt;
&lt;td&gt;原生一体，权限跟着仓库走&lt;/td&gt;
&lt;td&gt;需要手动配 Secrets&lt;/td&gt;
&lt;td&gt;需要手动配 Secrets&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;拉取速度&lt;/td&gt;
&lt;td&gt;海外节点，国内 VPS 视线路而定&lt;/td&gt;
&lt;td&gt;同上，且有匿名拉取限流历史&lt;/td&gt;
&lt;td&gt;完全自己控制，同机房最快&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;运维成本&lt;/td&gt;
&lt;td&gt;零&lt;/td&gt;
&lt;td&gt;零&lt;/td&gt;
&lt;td&gt;自己维护、自己备份、自己保可用性&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;怎么选，一句话原则：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;项目代码在 GitHub 上，优先用 GHCR；镜像要公开给所有人拉，Docker Hub 更有知名度；镜像不想出内网、或者拉取速度是硬要求，再上自建 Registry。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;自建 Registry 的搭建方法在私有镜像仓库篇里完整写过（见 &lt;a href=&quot;/posts/docker-private-registry/&quot;&gt;私有镜像仓库：Registry 与 Harbor 部署实战&lt;/a&gt;），包括认证、HTTPS 与垃圾回收，这一节不重复。本篇的实战以 GHCR 为主线，因为它和 GitHub Actions 是同一套账号体系，Secrets 都可以省掉大半，第一次搭流水线最不容易卡壳。&lt;/p&gt;
&lt;h2&gt;三、完整 Workflow 实战：逐段拆解&lt;/h2&gt;
&lt;p&gt;在项目仓库根目录建 &lt;code&gt;.github/workflows/docker.yml&lt;/code&gt;，下面是全文。先整体看一遍，后面逐段拆。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;name: Build and Push Image

on:
  push:
    branches:
      - main
    paths:
      - &quot;src/**&quot;
      - &quot;Dockerfile&quot;
      - &quot;.github/workflows/docker.yml&quot;

permissions:
  contents: read
  packages: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=semver,pattern={{version}}
            type=sha,format=short
            type=raw,value=latest,enable={{is_default_branch}}

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;3.1 触发条件：on.push 的分支与 paths&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;on:
  push:
    branches:
      - main
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;只有推到 &lt;code&gt;main&lt;/code&gt; 分支才触发。特性分支、实验分支随便推，不会污染正式镜像。&lt;/p&gt;
&lt;p&gt;再进一步的是 &lt;code&gt;paths&lt;/code&gt; 过滤：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    paths:
      - &quot;src/**&quot;
      - &quot;Dockerfile&quot;
      - &quot;.github/workflows/docker.yml&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;只有这些路径的文件变了才构建。改个 README、改个文档，不再白白跑一次构建。这是个小习惯，但流水线跑多了，省下的时间和额度都是真金白银。注意 &lt;code&gt;paths&lt;/code&gt; 要按你项目的实际结构改，源码目录不叫 &lt;code&gt;src&lt;/code&gt; 的就换成自己的。&lt;/p&gt;
&lt;p&gt;还有一个常见搭配是给版本打 tag 时触发：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;on:
  push:
    tags:
      - &quot;v*&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;推 &lt;code&gt;v1.2.0&lt;/code&gt; 这样的 tag 就自动构建发版。两种触发可以写在同一个 workflow 里，也可以拆成两个文件，新手建议先用分支触发跑通，再加 tag 触发。&lt;/p&gt;
&lt;h3&gt;3.2 actions/checkout：把代码拉下来&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;      - name: Checkout
        uses: actions/checkout@v4
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Actions 的运行环境是一台全新的空机器，什么都没有。第一步永远是把仓库代码 checkout 下来。&lt;code&gt;@v4&lt;/code&gt; 是这个 Action 的大版本号，跟着官方大版本走即可，不要写死小版本号，也不要用 &lt;code&gt;@main&lt;/code&gt; 这种飘忽不定的引用。&lt;/p&gt;
&lt;h3&gt;3.3 docker/setup-buildx-action：准备构建器&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;      - name: Set up Buildx
        uses: docker/setup-buildx-action@v3
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Buildx 是 Docker 的增强构建工具，支持构建缓存导出、多平台构建等现代特性。GitHub 的 runner 自带 Docker，但显式装一遍 Buildx 能保证版本与行为一致，后面要加多架构构建时也是靠它。这一篇里它的主要作用是把构建缓存接入 GitHub Actions 的缓存系统，第二次构建能快一大截。&lt;/p&gt;
&lt;h3&gt;3.4 docker/login-action：登录镜像仓库&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;推镜像之前必须先登录。GHCR 的最大便利在这里：用户名就是触发流水线的 GitHub 账号，密码直接用 Actions 环境自动提供的 &lt;code&gt;GITHUB_TOKEN&lt;/code&gt;，不需要你额外申请、额外保管。配合文件顶部的权限声明：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;permissions:
  contents: read
  packages: write
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这是告诉 GitHub：这个 workflow 里的 &lt;code&gt;GITHUB_TOKEN&lt;/code&gt; 只给两个权限——读代码、写镜像包，其他一律不给。权限最小化不是形式主义，万一某个第三方 Action 被投毒，Token 能干的坏事也被锁死在这个范围里。&lt;/p&gt;
&lt;p&gt;如果换成 Docker Hub，这一段要改成用你自己配的 Secrets：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意密码一栏填的是 Docker Hub 的 Access Token，不是账号登录密码，这两个东西不要混。&lt;/p&gt;
&lt;h3&gt;3.5 docker/metadata-action：自动生成标签&lt;/h3&gt;
&lt;p&gt;这一步是整份 workflow 里最容易被跳过、又最不该跳过的一步。它根据本次提交的上下文，自动算出该给镜像打哪些标签，下一节标签策略会细讲。&lt;code&gt;images&lt;/code&gt; 写镜像全名，&lt;code&gt;tags&lt;/code&gt; 里三行分别对应版本号、commit 短哈希、latest 三种标签。&lt;/p&gt;
&lt;p&gt;顺带说一句，&lt;code&gt;github.repository&lt;/code&gt; 的值形如 &lt;code&gt;你的用户名/仓库名&lt;/code&gt;，GHCR 要求镜像名全小写，仓库名里有大写字母时这里要留意，metadata-action 一般会处理，但推送报错时先查这一项。&lt;/p&gt;
&lt;h3&gt;3.6 docker/build-push-action：构建并推送&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐个参数看：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;context: .&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;构建上下文是仓库根目录，Dockerfile 默认也在根目录找&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;push: true&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;构建完直接推送；关掉它就只构建不推，适合先做 PR 检查&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;tags&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;用上一步 metadata 算出来的标签列表，一次构建打多个标签&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;labels&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;给镜像写入来源仓库、版本等元信息，方便日后溯源&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cache-from: type=gha&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;从 GitHub Actions 缓存里读上一轮的构建缓存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cache-to: type=gha,mode=max&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;把本轮所有中间层缓存都存回去，&lt;code&gt;mode=max&lt;/code&gt; 表示连最终镜像用不到的中间层也缓存，换构建速度&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;本地手动构建时你敲的是 &lt;code&gt;docker build&lt;/code&gt; 加 &lt;code&gt;docker push&lt;/code&gt; 两条命令，这里一个 Action 全包了。至此，push 一次代码，几分钟后 GHCR 里就会躺着一个带版本号、带 commit 哈希的新镜像。&lt;/p&gt;
&lt;h2&gt;四、标签策略：版本号、latest 与 commit sha&lt;/h2&gt;
&lt;p&gt;标签不是随手打的，它是你日后回滚和排障的唯一线索。本系列的立场很明确，一次构建同时打三种标签：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;标签&lt;/th&gt;
&lt;th&gt;例子&lt;/th&gt;
&lt;th&gt;管什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;版本号标签&lt;/td&gt;
&lt;td&gt;&lt;code&gt;v1.2.0&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;对外发布的正式版本，回滚时指哪打哪&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;latest&lt;/td&gt;
&lt;td&gt;&lt;code&gt;latest&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;永远指向主分支最新构建，给尝鲜和 Watchtower 盯梢用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;commit sha&lt;/td&gt;
&lt;td&gt;&lt;code&gt;a1b2c3d&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;精确对应某一次提交，排障时定位到底是哪行代码进的镜像&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;为什么生产环境不能只靠 &lt;code&gt;latest&lt;/code&gt;？因为 &lt;code&gt;latest&lt;/code&gt; 是个会动的指针。今天它指向好版本，明天一次坏构建推上去，它就指向坏版本了。更要命的是出了问题你想退回去，却发现旧镜像没有独立标签，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;没有版本号标签的镜像，等于没有存档点的游戏，坏了只能从头来过。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;版本号标签负责稳定，sha 标签负责精确，latest 负责方便，三者分工明确。服务器上线时，重要服务建议在 Compose 里写死版本号标签，比如 &lt;code&gt;image: ghcr.io/你的用户名/项目名:v1.2.0&lt;/code&gt;；个人小项目图省事可以跟 &lt;code&gt;latest&lt;/code&gt;，但前提是仓库里每个版本都有独立标签存着，随时能退。&lt;/p&gt;
&lt;p&gt;还有一个细节：标签一旦发布就不要覆盖重推。同一个 &lt;code&gt;v1.2.0&lt;/code&gt; 今天是这份代码、明天换成另一份代码，这个版本号就废了。真要修，版本号往上加，发 &lt;code&gt;v1.2.1&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;五、Secrets 管理：密钥只进保险箱&lt;/h2&gt;
&lt;p&gt;凡是 workflow 里要用到的密码、Token，一律放进仓库的 Secrets，路径是仓库页面 &lt;code&gt;Settings → Secrets and variables → Actions → New repository secret&lt;/code&gt;。引用时写 &lt;code&gt;${{ secrets.名字 }}&lt;/code&gt;，GitHub 在日志里还会自动把这些值打码。&lt;/p&gt;
&lt;p&gt;纪律只有三条，但条条要命：&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝不把任何密码、Token、私钥直接写进 workflow 文件或提交进仓库。&amp;lt;/span&amp;gt;仓库历史是永久的，写进去删掉也还在 git 记录里，等于公开广播。真发生了，第一时间去吊销那个凭证换新的，光删文件没有任何用。
:::&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;能用自动 Token 就不用手动凭证&lt;/strong&gt;。推 GHCR 用 &lt;code&gt;GITHUB_TOKEN&lt;/code&gt; 就是最优解，它随任务生、随任务死，泄漏面最小。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;手动凭证要限权、限期&lt;/strong&gt;。Docker Hub 用 Access Token 而不是主密码，Token 只给读写镜像的权限；自建 Registry 的账号也应该是专用账号，不要拿管理员账号到处填。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;定期轮换&lt;/strong&gt;。Secrets 不是配一次管一辈子，隔几个月换一轮，尤其是多人协作的仓库，有人退出就立刻换。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;再补一句容易被忽略的：fork 来的 PR 默认拿不到 Secrets，这是 GitHub 的保护机制，不是配置错了。给外部 PR 跑构建检查时，设计成只构建不推送（&lt;code&gt;push: false&lt;/code&gt;），别为了让它跑通去拆这道防线。&lt;/p&gt;
&lt;h2&gt;六、服务器侧衔接：Watchtower 自动上线&lt;/h2&gt;
&lt;p&gt;镜像推上去了，最后一段路是服务器自己把新镜像换上。这正是自动更新篇的主角 Watchtower（见 &lt;a href=&quot;/posts/linux-docker-auto-update/&quot;&gt;如何在 Linux 自动更新 Docker 容器&lt;/a&gt;），这里只讲它在流水线里怎么对接，部署细节不重复。&lt;/p&gt;
&lt;p&gt;核心就一件事：只让 Watchtower 更新本项目的容器，千万别让它把整台机器的容器全卷进来。做法是靠 label 精确圈定范围。被流水线管理的服务，在 Compose 里加上启用标签：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: ghcr.io/你的用户名/项目名:latest
    labels:
      - &quot;com.centurylinklabs.watchtower.enable=true&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Watchtower 这一侧则开启 label 模式，只盯带标签的容器：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  watchtower:
    image: nickfedor/watchtower:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_LABEL_ENABLE=true
      - WATCHTOWER_POLL_INTERVAL=300
      - WATCHTOWER_CLEANUP=true
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这样对接完成后，链路是全自动的：你 push 代码，Actions 构建推送，Watchtower 在轮询周期内（上面配的是 300 秒）发现 &lt;code&gt;latest&lt;/code&gt; 变了，拉新镜像、用原参数重建容器、清掉旧镜像。整个过程你只需要打开网站看一眼新版本在不在。&lt;/p&gt;
&lt;p&gt;私有镜像 Watchtower 也拉得到，前提是服务器上先 &lt;code&gt;docker login ghcr.io&lt;/code&gt; 登录一次，凭证会存在服务器的 Docker 配置里，Watchtower 挂载 docker.sock 时会沿用。登录用的 Token 在 GitHub 里生成一个只带 &lt;code&gt;read:packages&lt;/code&gt; 权限的就够了，服务器侧只拉不推，权限给多了都是风险。&lt;/p&gt;
&lt;h3&gt;6.1 另一条路线：SSH 远程部署，与 Watchtower 对比&lt;/h3&gt;
&lt;p&gt;除了 Watchtower 轮询，还有一条常见路线：Actions 构建完之后，通过 SSH 登录服务器执行部署命令。大致长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh deploy@你的服务器 &quot;cd /opt/app &amp;amp;&amp;amp; docker compose pull &amp;amp;&amp;amp; docker compose up -d&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两条路线对比着看：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;Watchtower 轮询&lt;/th&gt;
&lt;th&gt;SSH 远程部署&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;实时性&lt;/td&gt;
&lt;td&gt;有轮询间隔，分钟级延迟&lt;/td&gt;
&lt;td&gt;构建完立刻执行，秒级&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;部署动作&lt;/td&gt;
&lt;td&gt;只会拉镜像换容器，动作固定&lt;/td&gt;
&lt;td&gt;任意命令都能跑，可带迁移、清缓存等步骤&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;复杂度&lt;/td&gt;
&lt;td&gt;服务器装一个 Watchtower 就完事&lt;/td&gt;
&lt;td&gt;要配 SSH 密钥、部署账号、脚本健壮性自己兜底&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;安全面&lt;/td&gt;
&lt;td&gt;服务器不开放任何新入口&lt;/td&gt;
&lt;td&gt;要把 SSH 私钥放进 GitHub Secrets，服务器多一个可登录账号&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;失败感知&lt;/td&gt;
&lt;td&gt;它只管换容器，上没上线要自己验证&lt;/td&gt;
&lt;td&gt;命令返回值直接进 Actions 日志，成败一目了然&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合场景&lt;/td&gt;
&lt;td&gt;个人项目、小服务、更新即部署&lt;/td&gt;
&lt;td&gt;部署步骤复杂、要编排多条命令的项目&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选型建议：个人项目默认 Watchtower，省心且攻击面小；等部署流程复杂到「换容器之外还要做好几步」时，再升级到 SSH 路线，而且 SSH 路线务必用专用低权限账号加专用密钥，不要把 root 密钥放进 Secrets——&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;GitHub Secrets 里躺着服务器 root 密钥，等于把家门钥匙挂在别人家墙上。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;七、上线后验证、失败处理与回滚&lt;/h2&gt;
&lt;p&gt;自动化不等于甩手不管，链路的最后一环是确认新版本真的活着。&lt;/p&gt;
&lt;h3&gt;7.1 健康检查：别只看容器在跑&lt;/h3&gt;
&lt;p&gt;容器状态是 &lt;code&gt;Up&lt;/code&gt; 不代表服务正常，进程可能在里面反复崩溃重启。靠谱的做法是等一个健康接口返回 200。服务自己有 &lt;code&gt;/health&lt;/code&gt; 接口最好，没有的话用首页或任意稳定路径凑合。验证脚本的思路如下，可以放在服务器上手动跑，也可以接进通知流程：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
URL=&quot;http://127.0.0.1:8080/health&quot;
for i in $(seq 1 30); do
  code=$(curl -s -o /dev/null -w &quot;%{http_code}&quot; &quot;$URL&quot;)
  if [ &quot;$code&quot; = &quot;200&quot; ]; then
    echo &quot;OK: 服务已就绪&quot;
    exit 0
  fi
  echo &quot;第 $i 次检查，状态码 $code，继续等……&quot;
  sleep 5
done
echo &quot;超时：服务未在 150 秒内就绪&quot;
exit 1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;30 次、每次隔 5 秒，给足两分半的启动窗口。检查不过，先看容器日志再下结论：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose logs --tail=100 app
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;7.2 Actions 失败怎么看日志&lt;/h3&gt;
&lt;p&gt;构建或推送挂了，去仓库的 &lt;code&gt;Actions&lt;/code&gt; 页点开那次运行，红叉标在哪个 step 就展开哪个 step 看尾部日志，报错基本都在最后几十行。几个高频点位：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;checkout 之后就挂，多半是 workflow 的 YAML 缩进写错，先在线校验一遍语法；&lt;/li&gt;
&lt;li&gt;build 阶段挂，八成是 Dockerfile 在本地就构建不过，先在本地 &lt;code&gt;docker build&lt;/code&gt; 复现，别在云端反复试；&lt;/li&gt;
&lt;li&gt;push 阶段挂，看下一节排障，多半是权限和登录问题。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;还有个习惯值得养成：失败的运行不要急着删，重跑之前先把日志看完。Actions 支持 Re-run jobs，但同样的错重跑一百遍还是错。&lt;/p&gt;
&lt;h3&gt;7.3 回滚：把标签改回去，就这么简单&lt;/h3&gt;
&lt;p&gt;新版本上线后发现致命问题，不用慌，这正是第四节坚持打版本号标签的回报。回滚不需要重新构建，只是把部署指回上一个好版本：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/app
# 把 compose 里的镜像标签改回上一个版本
sed -i &apos;s|image: ghcr.io/你的用户名/项目名:.*|image: ghcr.io/你的用户名/项目名:v1.1.0|&apos; docker-compose.yml
docker compose pull
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三条命令，一分钟回到旧版本。如果你的 Compose 跟的是 &lt;code&gt;latest&lt;/code&gt;，回滚前先把 &lt;code&gt;latest&lt;/code&gt; 对应的好版本镜像在仓库里确认好，再手动 &lt;code&gt;docker pull&lt;/code&gt; 指定版本号标签并改 Compose 钉死版本。等故障处理完、根因找到了，再发新版本号重新走流水线。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;切记：回滚是改标签重新部署，不是去服务器上改代码救火&amp;lt;/span&amp;gt;，在服务器上热改的东西下次部署全被覆盖，还会让线上版本和仓库代码对不上账，后患无穷。&lt;/p&gt;
&lt;h2&gt;八、进阶：一句带过的两个提速与扩展点&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;多架构构建&lt;/strong&gt;。想让镜像同时支持 x86 和 ARM（比如还要跑在树莓派或 ARM 云主机上），在 build-push-action 里加一行 platforms 即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;        with:
          platforms: linux/amd64,linux/arm64
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;原理、QEMU 模拟构建的注意事项和 manifest 清单的验证方法，在多平台构建篇里完整讲过（见 &lt;a href=&quot;/posts/docker-buildx-multiarch/&quot;&gt;多平台镜像构建实战：buildx 双架构&lt;/a&gt;），这里不展开。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;构建缓存用 type=gha&lt;/strong&gt;。第三节 workflow 里已经埋了这两行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;          cache-from: type=gha
          cache-to: type=gha,mode=max
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它把 Docker 的层缓存存进 GitHub Actions 自带的缓存空间，下次构建直接复用没变的层。依赖多、构建慢的项目，第一次构建五分钟、第二次可能只要几十秒。注意 Actions 缓存有容量上限（默认 10 GB，超了自动淘汰最旧的），缓存偶尔失效重跑一次全量构建属于正常现象，不用排查。&lt;/p&gt;
&lt;p&gt;再往前一步，还可以给 workflow 加上 PR 触发的只构建不推送检查、镜像漏洞扫描等环节，但那都是锦上添花。主链先跑稳，再谈扩展。&lt;/p&gt;
&lt;h2&gt;九、排障小节&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. login 失败：&lt;code&gt;unauthorized&lt;/code&gt; 或 &lt;code&gt;permission_denied&lt;/code&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;按顺序查三件事：一是 workflow 顶部有没有写 &lt;code&gt;permissions: packages: write&lt;/code&gt;，没写的话 &lt;code&gt;GITHUB_TOKEN&lt;/code&gt; 默认权限可能不给推包；二是镜像名是不是全小写，GHCR 对大小写很较真；三是如果用的是个人访问令牌（PAT），确认它勾了 &lt;code&gt;write:packages&lt;/code&gt; 权限且没有过期。用 Docker Hub 或自建仓库的，则检查 Secrets 里的用户名和 Token 有没有复制串行、Token 有没有被吊销。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. build-push-action 推不上去：构建成功但 push 报错&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;先分清是构建挂了还是推送挂了，日志里 &lt;code&gt;ERROR: failed to push&lt;/code&gt; 才是推送问题。常见原因：登录步骤被跳过或失败但没中断（检查 login-action 那一步是不是绿的）；镜像名和仓库对不上，比如 metadata-action 生成的名字和 login 的 registry 不是同一家；网络抽风偶发失败，直接 Re-run 一次能过的大多是这类。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 服务器没更新：镜像推上去了，容器纹丝不动&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;这是 Watchtower 对接最经典的坑，逐项对：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;服务的 Compose 里 label 写了吗？键名必须是 &lt;code&gt;com.centurylinklabs.watchtower.enable=true&lt;/code&gt;，拼错一个字母都不认；&lt;/li&gt;
&lt;li&gt;Watchtower 自己有没有开 &lt;code&gt;WATCHTOWER_LABEL_ENABLE=true&lt;/code&gt;，一边开一边没开等于没对接；&lt;/li&gt;
&lt;li&gt;容器跟的标签对不对：Watchtower 只认你部署时用的那个标签有没有新版，Compose 里钉的是版本号标签，那推 &lt;code&gt;latest&lt;/code&gt; 推一万次它也不会动；&lt;/li&gt;
&lt;li&gt;私有镜像有没有在服务器上 &lt;code&gt;docker login&lt;/code&gt; 过，没登录它拉不到，只会在日志里默默报错，去看 Watchtower 自己的日志：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;docker logs watchtower --tail=50
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;4. 镜像拉下来了但容器反复重启&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;这不是流水线的问题，是新版本本身起不来。看应用日志定位，别回滚了事也别放着不管：确认是代码 bug 就修完发新版，是配置缺失（环境变量、数据卷没跟上）就补齐部署配置。实在顶不住先按第七节回滚保命，再慢慢查。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. Actions 额度或缓存异常&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;公共仓库的 Actions 分钟数免费且宽裕，私有仓库有月度额度，跑超了流水线会被暂停，去 &lt;code&gt;Settings → Billing&lt;/code&gt; 看用量。缓存突然全失效一般是缓存被容量淘汰，属正常现象。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇把整个系列收了个尾，回顾一下链路：本地 &lt;code&gt;git push&lt;/code&gt; 触发 GitHub Actions，checkout、Buildx、登录、打标签、构建推送一气呵成，镜像躺进 GHCR 并带着版本号、latest、commit sha 三种标签；服务器上的 Watchtower 盯着标签把新容器换上；健康检查确认服务活着，出事就改标签一分钟回滚。&lt;/p&gt;
&lt;p&gt;真正要带走的其实是三条纪律：构建放云端、服务器只拉镜像；标签必须留存档、生产别只靠 &lt;code&gt;latest&lt;/code&gt;；密钥只进 Secrets、权限只给刚好够用的。这三条守住，你的部署就从手艺活变成了流水线，改代码只管改，上线交给机器。&lt;/p&gt;
&lt;p&gt;至此 Docker 系列从安装、更新、命令、数据、网络、Compose、Dockerfile、日志、安全、反代，一路写到自动化流水线，一条完整的路走通了。下一篇可以横向扩展到监控与编排，或者就停在这里，把这条流水线先在自己项目里跑上一个月，体感会比多看十篇教程都实在。&lt;/p&gt;
</content:encoded></item><item><title>Docker 常用命令速查与排障实战</title><link>https://www.anexns.cloudns.org/posts/docker-commands-troubleshooting/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-commands-troubleshooting/</guid><description>按场景整理的 Docker 命令速查手册：容器、镜像、网络、数据卷、系统清理五大类高频命令，外加启动失败、反复重启、端口冲突、磁盘爆满、网络不通五条排障实战链路。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;装好 Docker、把服务跑起来之后，日常打交道最多的其实不是写配置，而是&lt;strong&gt;查状态、看日志、找问题&lt;/strong&gt;。容器起不来先敲什么？磁盘满了是谁吃的？端口冲突怎么定位？这一篇就是干这个的：前半部分是按场景整理的命令速查表，后半部分是五条最常见的排障实战链路。建议收藏，出问题时按图索骥即可。&lt;/p&gt;
&lt;p&gt;前置阅读：还没装 Docker 的先看 &lt;a href=&quot;/posts/linux-docker-compose/&quot;&gt;《如何在Linux部署Docker&amp;amp;Compose》&lt;/a&gt;；本文所有命令默认你已经能正常执行 &lt;code&gt;docker&lt;/code&gt; 命令（在 Docker 组里或用 sudo）。&lt;/p&gt;
&lt;p&gt;先记住一条贯穿全文的&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;万能起手式&lt;/strong&gt;&amp;lt;/span&amp;gt;，任何容器出问题都先走这三连：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker ps -a              # 1. 它到底是什么状态？（Exited？Restarting？Up？）
docker logs &amp;lt;容器名&amp;gt;       # 2. 它自己说了什么？（应用日志九成能定位）
docker inspect &amp;lt;容器名&amp;gt;    # 3. 它的配置和死因是什么？（退出码、挂载、端口）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三连走完还没头绪，再翻到本文后面的排障实战部分对号入座。&lt;/p&gt;
&lt;h2&gt;容器类命令速查&lt;/h2&gt;
&lt;p&gt;容器是每天操作最多的对象。先看状态类：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker ps&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列出&lt;strong&gt;正在运行&lt;/strong&gt;的容器&lt;/td&gt;
&lt;td&gt;最常用，没有之一&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker ps -a&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列出&lt;strong&gt;全部&lt;/strong&gt;容器（含已退出）&lt;/td&gt;
&lt;td&gt;容器「消失了」先用它找，多半是退出了&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker ps -a -q&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只输出容器 ID&lt;/td&gt;
&lt;td&gt;配合批量操作，如 &lt;code&gt;docker rm $(docker ps -a -q)&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker ps --format &quot;table {{.Names}}\t{{.Status}}\t{{.Ports}}&quot;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;自定义输出列&lt;/td&gt;
&lt;td&gt;嫌默认列太宽时用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker start &amp;lt;容器名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;启动已存在的容器&lt;/td&gt;
&lt;td&gt;和 &lt;code&gt;run&lt;/code&gt; 不同，start 不新建容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker stop &amp;lt;容器名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;优雅停止（先 SIGTERM，超时后 SIGKILL）&lt;/td&gt;
&lt;td&gt;默认等 10 秒，可用 &lt;code&gt;-t 30&lt;/code&gt; 改等待时长&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker restart &amp;lt;容器名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;重启容器&lt;/td&gt;
&lt;td&gt;改了挂载文件、想让应用重读配置时用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker kill &amp;lt;容器名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;直接 SIGKILL 强杀&lt;/td&gt;
&lt;td&gt;stop 不动时再用，会丢未落盘数据&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker rm &amp;lt;容器名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;删除&lt;strong&gt;已停止&lt;/strong&gt;的容器&lt;/td&gt;
&lt;td&gt;运行中的要先 stop，或 &lt;code&gt;rm -f&lt;/code&gt; 强删（慎用）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker rename &amp;lt;旧名&amp;gt; &amp;lt;新名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;给容器改名&lt;/td&gt;
&lt;td&gt;不用重建容器就能改&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;docker run&lt;/code&gt; 的参数组合太多，单独拉一张表，这是实际最常用的几个：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数组合&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker run -d --name app nginx&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;后台运行并命名&lt;/td&gt;
&lt;td&gt;&lt;code&gt;-d&lt;/code&gt; 是 detach，不加会占住终端&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker run -d --restart unless-stopped ...&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;宿主机重启后自动拉起&lt;/td&gt;
&lt;td&gt;服务器部署必加；&lt;code&gt;always&lt;/code&gt; 与它的区别是手动 stop 后开机是否还拉起&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker run -p 8080:80 ...&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;端口映射 宿主机:容器&lt;/td&gt;
&lt;td&gt;只想本机访问写 &lt;code&gt;-p 127.0.0.1:8080:80&lt;/code&gt;，更安全&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker run -v /宿主机目录:/容器目录 ...&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;绑定挂载目录&lt;/td&gt;
&lt;td&gt;配置、数据持久化都靠它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker run -e TZ=Asia/Shanghai ...&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;传环境变量&lt;/td&gt;
&lt;td&gt;时区、密码类配置常用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker run --rm -it ubuntu bash&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;退出即删，进交互终端&lt;/td&gt;
&lt;td&gt;临时测试镜像时用，不留垃圾&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker run -it --entrypoint sh &amp;lt;镜像&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;覆盖入口点进 shell 排查&lt;/td&gt;
&lt;td&gt;镜像起不来、想进去看看文件时用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;进容器和传文件：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker exec -it &amp;lt;容器名&amp;gt; bash&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;进正在运行的容器开终端&lt;/td&gt;
&lt;td&gt;没有 bash 的精简镜像换 &lt;code&gt;sh&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker exec &amp;lt;容器名&amp;gt; &amp;lt;命令&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不进终端、直接在容器里执行一条命令&lt;/td&gt;
&lt;td&gt;脚本里常用，如 &lt;code&gt;docker exec db pg_isready&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker cp &amp;lt;容器名&amp;gt;:/路径 /宿主机路径&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;从容器里拷文件出来&lt;/td&gt;
&lt;td&gt;拷日志、拷配置出来看很方便&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker cp /宿主机路径 &amp;lt;容器名&amp;gt;:/路径&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;把文件拷进容器&lt;/td&gt;
&lt;td&gt;临时塞个配置文件进去测试&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker logs -f --tail 100 &amp;lt;容器名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;实时追踪最近 100 行日志&lt;/td&gt;
&lt;td&gt;日志的完整用法见日志管理专篇，这里只列最常用的一条&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker update --restart unless-stopped &amp;lt;容器名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;不重建&lt;/strong&gt;容器、直接改它的重启策略&lt;/td&gt;
&lt;td&gt;老容器当年忘了加 &lt;code&gt;--restart&lt;/code&gt;，用它补，不用删了重建&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker update --memory 512m --cpus 1 &amp;lt;容器名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;动态调整资源上限&lt;/td&gt;
&lt;td&gt;临时救急可以，长期还是写回 compose 文件&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::tip
容器名和容器 ID 可以混用，ID 只写前几位能唯一匹配即可。但脚本里强烈建议用&lt;strong&gt;容器名&lt;/strong&gt;，可读性好得多。前提是部署时都用 &lt;code&gt;--name&lt;/code&gt; 或 compose 的 &lt;code&gt;container_name&lt;/code&gt; 起好名字，别用系统随机生成的那串单词。
:::&lt;/p&gt;
&lt;h2&gt;镜像类命令速查&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker images&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列出本机镜像&lt;/td&gt;
&lt;td&gt;看 TAG 和 SIZE，排查磁盘占用先看它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker pull nginx:1.27&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;拉取指定版本镜像&lt;/td&gt;
&lt;td&gt;务必带版本号，别无脑 &lt;code&gt;latest&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker tag &amp;lt;旧标签&amp;gt; &amp;lt;新标签&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;给镜像多打一个标签&lt;/td&gt;
&lt;td&gt;推送到自己仓库前必须先 tag 成仓库地址格式&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker rmi &amp;lt;镜像&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;删除镜像&lt;/td&gt;
&lt;td&gt;有容器在用（哪怕已停止）会拒绝，先删容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker history &amp;lt;镜像&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;看镜像每一层是怎么来的、多大&lt;/td&gt;
&lt;td&gt;排查「镜像为什么这么大」&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker inspect &amp;lt;镜像&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;看镜像的完整元数据&lt;/td&gt;
&lt;td&gt;重点看 Entrypoint、Cmd、ExposedPorts、Env&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker build -t myapp:1.0 .&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;用当前目录 Dockerfile 构建镜像&lt;/td&gt;
&lt;td&gt;打包自己的应用时用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker save -o app.tar myapp:1.0&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;把镜像导出成 tar 文件&lt;/td&gt;
&lt;td&gt;离线搬运、无外网环境传镜像&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker load -i app.tar&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;从 tar 文件导入镜像&lt;/td&gt;
&lt;td&gt;与 save 配对使用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker image prune&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;删除悬空镜像（&lt;code&gt;&amp;lt;none&amp;gt;&lt;/code&gt; 那些）&lt;/td&gt;
&lt;td&gt;安全，只清构建/更新留下的无标签残层&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;离线搬运的完整流程（A 机导出、U盘/内网传过去、B 机导入）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# A 机：导出
docker save -o myapp-1.0.tar myapp:1.0

# B 机：导入，镜像名和标签原样恢复
docker load -i myapp-1.0.tar
docker images | grep myapp
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;docker save/load&lt;/code&gt; 搬的是&lt;strong&gt;镜像&lt;/strong&gt;，不包含容器里的数据卷。要搬整个服务（含数据），正确做法是：save 镜像 + 单独打包数据卷目录 + 带上 compose 文件，到目标机先恢复数据再 &lt;code&gt;docker compose up -d&lt;/code&gt;。只 save 镜像过去，数据库数据是不会跟着走的。
:::&lt;/p&gt;
&lt;h2&gt;docker inspect 精讲&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;docker inspect&lt;/code&gt; 输出一大坨 JSON，是排查时信息量最大的命令。直接看全量输出太累，记住下面几个最常看的字段和 &lt;code&gt;--format&lt;/code&gt; 取值写法就够了。&lt;/p&gt;
&lt;p&gt;整体结构里最常翻的四块：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段路径&lt;/th&gt;
&lt;th&gt;看什么&lt;/th&gt;
&lt;th&gt;典型用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.State.Status&lt;/code&gt; / &lt;code&gt;.State.ExitCode&lt;/code&gt; / &lt;code&gt;.State.OOMKilled&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;运行状态、退出码、是否被内存杀手干掉&lt;/td&gt;
&lt;td&gt;容器退出第一时间看这里&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.NetworkSettings.Ports&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;端口映射实际生效情况&lt;/td&gt;
&lt;td&gt;写了 &lt;code&gt;-p&lt;/code&gt; 却访问不了，先确认映射在不在&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.NetworkSettings.IPAddress&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器在默认 bridge 上的 IP&lt;/td&gt;
&lt;td&gt;自定义网络下要看 &lt;code&gt;.NetworkSettings.Networks&lt;/code&gt; 里对应网络&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.Mounts&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;数据卷/绑定挂载的源和目标&lt;/td&gt;
&lt;td&gt;「我改了宿主机文件容器里没变」多半是挂载路径写错&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.Config.Env&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器实际拿到的环境变量&lt;/td&gt;
&lt;td&gt;密码、时区没生效，先看这里是不是传进去了&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.HostConfig.RestartPolicy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;重启策略&lt;/td&gt;
&lt;td&gt;容器开机没自启，看它是不是 &lt;code&gt;no&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;用 &lt;code&gt;--format&lt;/code&gt; 只取想要的值，输出干净利落：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 取容器 IP（默认 bridge）
docker inspect -f &apos;{{.NetworkSettings.IPAddress}}&apos; &amp;lt;容器名&amp;gt;

# 取退出码和状态，一行说清死因
docker inspect -f &apos;{{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}}&apos; &amp;lt;容器名&amp;gt;

# 取自定义网络下的 IP（网络名换成自己的）
docker inspect -f &apos;{{index .NetworkSettings.Networks &quot;mynet&quot; &quot;IPAddress&quot;}}&apos; &amp;lt;容器名&amp;gt;

# 列出全部挂载：源 -&amp;gt; 目标
docker inspect -f &apos;{{range .Mounts}}{{.Source}} -&amp;gt; {{.Destination}}{{&quot;\n&quot;}}{{end}}&apos; &amp;lt;容器名&amp;gt;

# 看重启策略
docker inspect -f &apos;{{.HostConfig.RestartPolicy.Name}}&apos; &amp;lt;容器名&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::tip
查 JSON 字段还有个笨办法但很稳：&lt;code&gt;docker inspect &amp;lt;容器名&amp;gt; | grep -A2 -B2 关键词&lt;/code&gt;。比如想不起来 IP 字段在哪，就 grep &lt;code&gt;IPAddress&lt;/code&gt;。先解决问题，再慢慢记字段路径。
:::&lt;/p&gt;
&lt;h2&gt;资源与状态命令&lt;/h2&gt;
&lt;p&gt;服务跑久了要回答三个问题：谁在吃 CPU/内存？磁盘被谁占了？刚才发生了什么事？对应四组命令：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker stats&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;实时滚动显示所有容器的 CPU、内存、网络、磁盘 IO&lt;/td&gt;
&lt;td&gt;像 top 一样常驻，按 Ctrl+C 退出&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker stats --no-stream&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只输出&lt;strong&gt;一次&lt;/strong&gt;当前资源占用&lt;/td&gt;
&lt;td&gt;脚本采集、快速看一眼时用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker stats &amp;lt;容器名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只看指定容器&lt;/td&gt;
&lt;td&gt;怀疑某个容器吃资源时锁定它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker top &amp;lt;容器名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;看容器里到底有哪些进程&lt;/td&gt;
&lt;td&gt;等于在宿主机视角看容器的进程树&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker events&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;实时事件流：容器启停、死亡、镜像拉取等&lt;/td&gt;
&lt;td&gt;排查「容器半夜自己重启了」时回放时间线（可加 &lt;code&gt;--since 1h&lt;/code&gt;）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker system df&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;汇总镜像、容器、数据卷、构建缓存各占多少磁盘&lt;/td&gt;
&lt;td&gt;磁盘排查的起点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker system df -v&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;详细列出每个镜像/卷各占多少&lt;/td&gt;
&lt;td&gt;找出具体是哪个卷/镜像在膨胀&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;pre&gt;&lt;code&gt;# 一次性看所有容器资源，按内存从大到小排个序（配合 sort）
docker stats --no-stream --format &quot;table {{.Name}}\t{{.MemPerc}}\t{{.MemUsage}}&quot;

# 看最近 2 小时内所有容器的死亡和重启事件
docker events --since 2h --filter event=die --filter event=restart

# 磁盘总账
docker system df
# 典型输出：
# TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
# Images          23        8         6.2GB     3.1GB (50%)
# Containers      10        9         120MB     0B
# Local Volumes   6         4         18GB      2GB (11%)
# Build Cache     15        0         800MB     800MB
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;docker system df&lt;/code&gt; 只告诉你「哪一类」占得多，真要定位到具体目录，接着用宿主机的 &lt;code&gt;du&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# Docker 的全部家当都在这里，按子目录看大小
sudo du -h --max-depth=1 /var/lib/docker | sort -hr | head

# 容器日志单独有多大（日志爆磁盘的头号嫌疑人）
sudo du -sh /var/lib/docker/containers/*/*-json.log | sort -hr | head
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;网络与数据卷常用命令&lt;/h2&gt;
&lt;p&gt;这两类平时动得少，出问题时容易手生，各备一小表。&lt;/p&gt;
&lt;p&gt;网络：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker network ls&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列出所有网络&lt;/td&gt;
&lt;td&gt;默认有 bridge、host、none 三个&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker network inspect &amp;lt;网络名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;看子网、网关、挂了哪些容器及其 IP&lt;/td&gt;
&lt;td&gt;容器互访不通时先看是不是在同一个网络里&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker network create mynet&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;建自定义网络&lt;/td&gt;
&lt;td&gt;自定义网络自带 DNS，容器可按&lt;strong&gt;名字&lt;/strong&gt;互访&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker network connect mynet &amp;lt;容器名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;把运行中的容器接入某网络&lt;/td&gt;
&lt;td&gt;不用重建容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker network disconnect mynet &amp;lt;容器名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;把容器从某网络断开&lt;/td&gt;
&lt;td&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker network rm mynet&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;删除网络&lt;/td&gt;
&lt;td&gt;还有容器挂着时会拒绝&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;数据卷：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker volume ls&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列出所有数据卷&lt;/td&gt;
&lt;td&gt;那一串随机哈希名的是匿名卷&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker volume inspect &amp;lt;卷名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;看卷的宿主机实际路径（Mountpoint）&lt;/td&gt;
&lt;td&gt;备份数据就是去打包这个目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker volume create mydata&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;建命名卷&lt;/td&gt;
&lt;td&gt;重要数据一律用命名卷，别用匿名卷&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker volume rm &amp;lt;卷名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;删除卷&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;数据真删，不可恢复&lt;/strong&gt;&amp;lt;/span&amp;gt;，见下方警告&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker volume prune&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;删除所有未被容器使用的卷&lt;/td&gt;
&lt;td&gt;同样危险，老版本 Docker 无确认提示&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
数据卷相关的删除命令是整个 Docker 里&lt;strong&gt;最不可逆&lt;/strong&gt;的操作：&lt;code&gt;docker volume rm&lt;/code&gt; 和 &lt;code&gt;docker volume prune&lt;/code&gt; 删的是真实数据目录，没有回收站。删之前务必先 &lt;code&gt;docker volume inspect&lt;/code&gt; 确认 Mountpoint、把数据打包备份一份，再动手。生产环境的数据库卷，看到名字先停手三秒。
:::&lt;/p&gt;
&lt;h2&gt;Compose 常用命令速查&lt;/h2&gt;
&lt;p&gt;实际部署大多用 Compose，它的命令和原生 &lt;code&gt;docker&lt;/code&gt; 命令是两套，排障时经常混着用，这里单独备一表（在 Compose 文件所在目录执行）：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose up -d&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;按文件创建并启动全部服务&lt;/td&gt;
&lt;td&gt;改了配置再执行一次，它只重建有变化的服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose ps&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;看本项目的容器状态&lt;/td&gt;
&lt;td&gt;比 &lt;code&gt;docker ps&lt;/code&gt; 多一列 SERVICE，定位更快&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose logs -f &amp;lt;服务名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;追踪某个服务的日志&lt;/td&gt;
&lt;td&gt;不写服务名是全部服务混在一起看&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose down&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;停掉并删除本项目容器和网络&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;不加 &lt;code&gt;-v&lt;/code&gt; 不会删数据卷&lt;/strong&gt;；加了 &lt;code&gt;-v&lt;/code&gt; 连卷一起删，慎用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose restart &amp;lt;服务名&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只重启某个服务&lt;/td&gt;
&lt;td&gt;改了挂载的配置文件时常用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose exec &amp;lt;服务名&amp;gt; sh&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;进某个服务的容器&lt;/td&gt;
&lt;td&gt;和 &lt;code&gt;docker exec&lt;/code&gt; 等效，但用服务名不用记容器名&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose pull&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;批量拉取文件里所有镜像的新版&lt;/td&gt;
&lt;td&gt;配合 &lt;code&gt;up -d&lt;/code&gt; 就是手动更新全套服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose config&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;把最终生效的配置打印出来检查&lt;/td&gt;
&lt;td&gt;变量替换、多文件合并的结果都以它为准，排障神器&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::tip
Compose 排障有个高频误会：改了 Compose 文件后直接 &lt;code&gt;docker compose restart&lt;/code&gt; 没效果——restart 只是重启旧容器，&lt;strong&gt;不会按新配置重建&lt;/strong&gt;。改配置（端口、环境变量、挂载）后必须 &lt;code&gt;docker compose up -d&lt;/code&gt;，它会发现差异并重建对应服务。
:::&lt;/p&gt;
&lt;h2&gt;清理命令与红线&lt;/h2&gt;
&lt;p&gt;磁盘紧张时要清理，但 Docker 的清理命令威力分级很陡，必须先看再清、从轻到重：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;清什么&lt;/th&gt;
&lt;th&gt;危险程度&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker image prune&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只清悬空镜像（无标签、无容器引用）&lt;/td&gt;
&lt;td&gt;低，放心用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker image prune -a&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;清&lt;strong&gt;所有&lt;/strong&gt;未被容器使用的镜像&lt;/td&gt;
&lt;td&gt;中：下次启动要重新拉取，离线环境慎用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker container prune&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;清所有已停止的容器&lt;/td&gt;
&lt;td&gt;中：停止的容器如果还想 start 回来，先别清&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker builder prune&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;清构建缓存&lt;/td&gt;
&lt;td&gt;低，经常 build 的机器能清出不少&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker volume prune&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;清未被使用的卷&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;高：删真实数据&lt;/strong&gt;&amp;lt;/span&amp;gt;，见上一节警告&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker system prune&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;组合清：停止的容器 + 悬空镜像 + 无用网络&lt;/td&gt;
&lt;td&gt;中高，用前看清提示里列的清单&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker system prune -a --volumes&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;上面全部 + 所有未用镜像 + 所有未用卷&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;极高，新手禁用&lt;/strong&gt;&amp;lt;/span&amp;gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;正确的清理姿势是三步走：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker system df # 第一步：先看账，哪类占得多、能回收多少
docker image prune # 第二步：只清最安全的悬空镜像
docker system df # 第三步：复查效果，不够再考虑下一档
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;strong&gt;红线：绝不要把 &lt;code&gt;docker system prune -a&lt;/code&gt; 当日常命令随手敲。&lt;/strong&gt; 它会删掉所有当前没有容器在用的镜像——包括你特意保留的旧版本镜像、离线 save 进来的镜像、暂时停掉准备回滚的版本。网上很多「Docker 清理教程」上来就教这条，在单机玩票环境无所谓，在装了正经服务的服务器上敲一次，轻则全站重新拉镜像断网半小时，重则配合 &lt;code&gt;--volumes&lt;/code&gt; &amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把数据库数据一起送走&amp;lt;/span&amp;gt;。清理永远从 &lt;code&gt;docker system df&lt;/code&gt; 开始，按需逐项清。
:::&lt;/p&gt;
&lt;h2&gt;排障实战一：容器启动即退出&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;症状&lt;/strong&gt;：&lt;code&gt;docker compose up -d&lt;/code&gt; 显示 Started，但 &lt;code&gt;docker ps&lt;/code&gt; 里找不到，过一会儿 &lt;code&gt;docker ps -a&lt;/code&gt; 里状态是 &lt;code&gt;Exited (x)&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步看什么&lt;/strong&gt;：日志和退出码，两个命令定生死：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker logs &amp;lt;容器名&amp;gt; # 应用自己报的错，九成在这里
docker inspect -f &apos;{{.State.ExitCode}}&apos; &amp;lt;容器名&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;退出码含义速查&lt;/strong&gt;：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;退出码&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;常见根因&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;0&lt;/td&gt;
&lt;td&gt;正常结束&lt;/td&gt;
&lt;td&gt;不是故障：程序本身就是一次性的，或者主进程干完活自己退了&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;通用错误&lt;/td&gt;
&lt;td&gt;应用层报错：配置写错、连不上数据库、文件不存在，看 logs&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;参数/用法错误&lt;/td&gt;
&lt;td&gt;启动命令参数写错、shell 脚本语法问题&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;126&lt;/td&gt;
&lt;td&gt;命令不可执行&lt;/td&gt;
&lt;td&gt;入口脚本没有执行权限（chmod +x 没做）、或不是可执行文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;127&lt;/td&gt;
&lt;td&gt;命令不存在&lt;/td&gt;
&lt;td&gt;Cmd/Entrypoint 里写的程序镜像里根本没有，如精简镜像里调用 bash&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;137&lt;/td&gt;
&lt;td&gt;被 SIGKILL 强杀&lt;/td&gt;
&lt;td&gt;头号嫌疑是 &lt;strong&gt;OOM&lt;/strong&gt;（内存爆了被内核杀），用 inspect 看 OOMKilled 是否为 true&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;143&lt;/td&gt;
&lt;td&gt;收到 SIGTERM 后退出&lt;/td&gt;
&lt;td&gt;有人/有程序执行了 stop，或宿主机在关机流程里，这不算异常&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;定位链路&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 先看日志最后 50 行
docker logs --tail 50 &amp;lt;容器名&amp;gt;

# 2. 确认是不是 OOM
docker inspect -f &apos;{{.State.OOMKilled}}&apos; &amp;lt;容器名&amp;gt; # true 就是内存不够被杀

# 3. 怀疑镜像本身有问题：覆盖入口点进去看
docker run --rm -it --entrypoint sh &amp;lt;镜像名&amp;gt;
ls /app # 看文件在不在
./start.sh # 手动执行启动脚本，看它当场报什么错
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;常见根因汇总&lt;/strong&gt;：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;常见根因&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;配置文件路径写错&lt;/td&gt;
&lt;td&gt;挂载没生效&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据库还没起来应用先连了&lt;/td&gt;
&lt;td&gt;Compose 里加 healthcheck + depends_on 的 condition&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;脚本是 Windows 换行符&lt;/td&gt;
&lt;td&gt;&lt;code&gt;\r&lt;/code&gt; 会让 shebang 失效，报错很隐蔽，用 &lt;code&gt;dos2unix&lt;/code&gt; 处理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据目录权限不对&lt;/td&gt;
&lt;td&gt;容器内非 root 用户写不进挂载目录&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;排障实战二：容器反复 Restarting&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;症状&lt;/strong&gt;：&lt;code&gt;docker ps&lt;/code&gt; 里状态一直是 &lt;code&gt;Restarting (1) x seconds ago&lt;/code&gt;，或者 Up 几秒又变 Restarting，循环往复。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步看什么&lt;/strong&gt;：先分清是「崩溃重启」还是「策略性重启」：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker logs --tail 100 &amp;lt;容器名&amp;gt; # 看每次启动是不是同一个报错
docker inspect -f &apos;{{.RestartCount}} 重启策略={{.HostConfig.RestartPolicy.Name}}&apos; &amp;lt;容器名&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;定位链路&lt;/strong&gt;：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;日志每次都是同一个错&lt;/strong&gt; → 本质还是「启动即退出」问题，只是 restart 策略在不停重试。按实战一的方法修根因，修好自然停。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;日志没报错但就是重启&lt;/strong&gt; → 检查主进程是不是「假装在运行」：比如启动脚本最后用了后台运行 &lt;code&gt;&amp;amp;&lt;/code&gt; 又立刻结束，Docker 认为主进程已退出，于是按策略重启。对策是让主进程前台阻塞（如 Nginx 的 &lt;code&gt;daemon off;&lt;/code&gt;、用 &lt;code&gt;tail -f /dev/null&lt;/code&gt; 临时顶住做验证）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Compose 里两个服务互相 depends_on&lt;/strong&gt; → A 等 B、B 又等 A，形成循环依赖，Compose 会直接报错或行为异常。把依赖关系画出来，环上必有一条是多余的，删掉它；实在需要双向，就拆掉其中一条改用应用层重试。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;常见根因&lt;/strong&gt;：应用启动就崩（占九成）、主进程后台化、循环依赖、健康检查误杀（healthcheck 命令在精简镜像里不存在，容器被判 unhealthy 后被编排反复重建——先临时去掉 healthcheck 验证）。&lt;/p&gt;
&lt;p&gt;临时止血：先把重启策略改掉，别让它无限刷日志：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker update --restart no &amp;lt;容器名&amp;gt;
docker stop &amp;lt;容器名&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;排障实战三：端口已被占用&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;症状&lt;/strong&gt;：启动时报 &lt;code&gt;Bind for 0.0.0.0:8080 failed: port is already allocated&lt;/code&gt;，或者 &lt;code&gt;address already in use&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步看什么&lt;/strong&gt;：谁占了这个端口，一条命令见分晓：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo ss -tlnp | grep 8080
# 输出里的 users:((&quot;nginx&quot;,pid=1234,...)) 就是占用者
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;定位链路&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 情况 A：是另一个容器占的
docker ps --format &quot;{{.Names}} {{.Ports}}&quot; | grep 8080
# 处理：改其中一个的宿主机端口，如 8080 -&amp;gt; 8081，容器内端口不用动

# 情况 B：是宿主机上的普通进程占的（如系统自带 nginx、apache）
sudo systemctl stop nginx # 确认不再需要它，再考虑 disable
# 或者干脆给容器换个宿主机端口，互不打扰

# 情况 C：ss 查不到占用，但 Docker 还报占用
# 多半是残留的代理进程，重启 Docker 服务可解（会影响全部容器，挑低峰期）
sudo systemctl restart docker
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;常见根因&lt;/strong&gt;：同一套 Compose 起了两遍（旧容器没删）、宿主机原生装的同类服务没关、别的项目图省事都用了 8080/3306 这类热门端口。养成习惯：每个服务规划固定的宿主机端口段，写进 compose 文件留档。&lt;/p&gt;
&lt;h2&gt;排障实战四：磁盘爆满&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;症状&lt;/strong&gt;：服务器磁盘 100%，容器开始报错、数据库写不进去、&lt;code&gt;docker&lt;/code&gt; 命令本身都可能变慢或失败。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步看什么&lt;/strong&gt;：先分清是 Docker 吃的还是系统其他地方吃的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;df -h # 哪个分区满了
docker system df # Docker 内部的账
sudo du -h --max-depth=1 /var/lib/docker | sort -hr | head # Docker 里谁最大
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;定位链路&lt;/strong&gt;（Docker 场景下两大元凶）：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;元凶一：容器日志无限膨胀。&lt;/strong&gt; 默认 json-file 驱动不做轮转，一个话痨容器能写出几十 GB 的日志。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 找出最大的几个日志文件
sudo find /var/lib/docker/containers -name &quot;*-json.log&quot; -exec du -h {} + | sort -hr | head

# 应急：清空某个容器的日志文件（不要直接删文件，用 truncate）
sudo truncate -s 0 /var/lib/docker/containers/&amp;lt;容器ID&amp;gt;/&amp;lt;容器ID&amp;gt;-json.log

# 根治：给 daemon.json 配置日志轮转 max-size/max-file 后重启 Docker（只对新建容器生效，
# 存量容器要重建才吃到新配置，细节见日志管理专篇）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;元凶二：镜像和构建缓存堆积。&lt;/strong&gt; 反复更新、反复 build 的机器尤其明显。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker images | wc -l # 镜像数量是否离谱
docker system df -v | head -50 # 逐个看大小
docker image prune # 先清悬空镜像
docker builder prune # 再清构建缓存
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;常见根因&lt;/strong&gt;：日志没轮转（占大头）、自动更新工具没开清理旧镜像、频繁构建镜像没清缓存、数据卷里应用自己囤了大量文件（这种情况 Docker 命令清不掉，要进卷目录处理应用数据）。注意：如果 &lt;code&gt;df&lt;/code&gt; 显示满了但 &lt;code&gt;du&lt;/code&gt; 加起来对不上，多半是&lt;strong&gt;已删除但被进程占着的文件&lt;/strong&gt;，用 &lt;code&gt;sudo lsof +L1&lt;/code&gt; 找出来，重启对应容器即可释放。&lt;/p&gt;
&lt;h2&gt;排障实战五：容器间网络不通&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;症状&lt;/strong&gt;：应用连不上同机的数据库容器，日志里全是 &lt;code&gt;Connection refused&lt;/code&gt;、&lt;code&gt;Name or service not known&lt;/code&gt; 或超时。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步看什么&lt;/strong&gt;：确认两个容器在不在&lt;strong&gt;同一个网络&lt;/strong&gt;里，这是前提：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker network inspect &amp;lt;网络名&amp;gt; | grep -A1 &apos;&quot;Name&quot;&apos; # 看成员名单
# 或者分别看两个容器挂了哪些网络
docker inspect -f &apos;{{range $k,$v:=.NetworkSettings.Networks}}{{$k}} {{end}}&apos; &amp;lt;容器名&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;定位链路&lt;/strong&gt;（按顺序逐项排除）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 名字解析：在应用容器里 ping 一下数据库的服务名/容器名
docker exec -it &amp;lt;应用容器&amp;gt; ping -c2 db
# 解析不了 -&amp;gt; 不在同一个自定义网络，或用了默认 bridge（默认 bridge 不支持按名解析）

# 2. 端口对不对：容器间互访用的是，不是映射到宿主机的端口
# 数据库容器内监听 5432，应用就连 db:5432，哪怕宿主机映射的是 15432:5432
docker exec -it &amp;lt;应用容器&amp;gt; sh -c &apos;wget -qO- http://api:3000/health || curl -v http://api:3000/health&apos;
# 精简镜像没工具时，用宿主机侧验证：
docker exec &amp;lt;数据库容器&amp;gt; ss -tlnp # 确认服务真的在容器内监听了

# 3. 服务本身活没活
docker logs --tail 50 &amp;lt;数据库容器&amp;gt; # 数据库自己没起来，网络再通也没用
docker ps -a | grep db # 确认状态是 Up 不是 Exited
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;常见根因&lt;/strong&gt;：两个容器不在同一网络（占多数）、连错端口（拿宿主机映射端口在容器间互访）、用默认 bridge 还指望按容器名解析、目标服务根本没启动成功、目标服务只监听了 &lt;code&gt;127.0.0.1&lt;/code&gt;（在容器内只绑回环，同网络的其他容器也连不进，要改绑 &lt;code&gt;0.0.0.0&lt;/code&gt;）。&lt;/p&gt;
&lt;p&gt;:::warning
容器间通信永远记住三句话：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;同网络、喊名字、用容器端口&lt;/strong&gt;&amp;lt;/span&amp;gt;。映射端口（&lt;code&gt;-p&lt;/code&gt;）是给宿主机和外网用的，跟容器互访没关系。把这三句贴在显示器边上，这类问题能少八成。
:::&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;任何故障先走万能三连：&lt;code&gt;docker ps -a&lt;/code&gt; 看状态 → &lt;code&gt;docker logs&lt;/code&gt; 看自述 → &lt;code&gt;docker inspect&lt;/code&gt; 看死因和配置。&lt;/li&gt;
&lt;li&gt;退出码是最快的分诊台：137 先查内存，127/126 查命令和权限，1 回日志里找应用报错。&lt;/li&gt;
&lt;li&gt;清理的铁律是&lt;strong&gt;先 &lt;code&gt;docker system df&lt;/code&gt; 看账、从最安全的档位逐级清&lt;/strong&gt;；&lt;code&gt;docker system prune -a&lt;/code&gt; 和删卷命令永远不要当顺手命令敲。&lt;/li&gt;
&lt;li&gt;磁盘爆满先查日志文件和镜像两大头；端口冲突用 &lt;code&gt;ss -tlnp&lt;/code&gt; 一锤定音；网络不通按「同网络 → 服务名 → 容器端口」顺序排查。&lt;/li&gt;
&lt;li&gt;命令记不住没关系，记住每类问题&lt;strong&gt;第一个该敲的命令&lt;/strong&gt;，剩下的查表就行——这篇就是干这个用的。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>Docker Compose 进阶：环境变量、健康检查与多环境</title><link>https://www.anexns.cloudns.org/posts/docker-compose-advanced/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-compose-advanced/</guid><description>把 Compose 用到进阶：.env 与变量插值、env_file 的区别与敏感信息管理、healthcheck 健康检查配合 depends_on 实现有序启动、profiles 多环境划分、多文件 override 合并与常用进阶命令。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;第一篇 &lt;a href=&quot;/posts/linux-docker-compose/&quot;&gt;《如何在Linux部署Docker&amp;amp;Compose》&lt;/a&gt; 里，我们用一份最基础的 &lt;code&gt;docker-compose.yml&lt;/code&gt; 把 Nginx 和 Redis 跑了起来。真到了日常用的时候，问题很快就来了：数据库密码写死在 compose 文件里，换台机器就要改一遍；应用比数据库先启动，数据库还没初始化完，应用连不上直接报错退出；同一份配置想在测试机和正式机上跑，端口和镜像标签又不一样……这篇就专门解决这三个问题：&lt;strong&gt;环境变量&lt;/strong&gt;（配置和文件分离）、&lt;strong&gt;健康检查 + 启动顺序&lt;/strong&gt;（让服务按正确的节奏起来）、&lt;strong&gt;profiles 与多文件&lt;/strong&gt;（一份配置多处用）。全篇的例子都可以直接抄。&lt;/p&gt;
&lt;h2&gt;一、环境变量三件套：先分清谁是谁&lt;/h2&gt;
&lt;p&gt;Compose 里跟「变量」有关的东西有三个，新手最容易混：&lt;code&gt;environment&lt;/code&gt;、&lt;code&gt;env_file&lt;/code&gt;、项目根目录的 &lt;code&gt;.env&lt;/code&gt; 文件。它们的作用完全不同，先看对比表：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方式&lt;/th&gt;
&lt;th&gt;写在哪&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;会不会进容器&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.env&lt;/code&gt; 文件&lt;/td&gt;
&lt;td&gt;项目目录（和 compose 文件同级）&lt;/td&gt;
&lt;td&gt;给 &lt;strong&gt;compose 文件本身&lt;/strong&gt;做变量插值，替换 &lt;code&gt;${...}&lt;/code&gt; 占位符&lt;/td&gt;
&lt;td&gt;不会，它的值不会自动变成容器环境变量&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;env_file&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;compose 里服务的属性，指向一个或多个 env 文件&lt;/td&gt;
&lt;td&gt;把文件里的键值对批量注入&lt;strong&gt;容器内部&lt;/strong&gt;的环境变量&lt;/td&gt;
&lt;td&gt;会&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;environment&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;compose 里服务的属性&lt;/td&gt;
&lt;td&gt;在 compose 文件里直接写键值对，注入&lt;strong&gt;容器内部&lt;/strong&gt;的环境变量&lt;/td&gt;
&lt;td&gt;会&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一句话记忆：&lt;strong&gt;&lt;code&gt;.env&lt;/code&gt; 是给 compose 文件看的，&lt;code&gt;env_file&lt;/code&gt; 和 &lt;code&gt;environment&lt;/code&gt; 是给容器看的。&lt;/strong&gt;&lt;/p&gt;
&lt;h3&gt;1. &lt;code&gt;.env&lt;/code&gt; 文件：只负责插值&lt;/h3&gt;
&lt;p&gt;在 compose 文件同目录建一个 &lt;code&gt;.env&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# .env
NGINX_PORT=8080
IMAGE_TAG=1.27
DB_PASSWORD=example_password_123
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;compose 文件里用 &lt;code&gt;${...}&lt;/code&gt; 引用它：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  web:
    image: nginx:${IMAGE_TAG}
    ports:
      - &quot;${NGINX_PORT}:80&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;运行 &lt;code&gt;docker compose up -d&lt;/code&gt; 时，Compose 会先读 &lt;code&gt;.env&lt;/code&gt;，把 &lt;code&gt;${IMAGE_TAG}&lt;/code&gt; 换成 &lt;code&gt;1.27&lt;/code&gt;、&lt;code&gt;${NGINX_PORT}&lt;/code&gt; 换成 &lt;code&gt;8080&lt;/code&gt;，再去执行。注意：&lt;code&gt;NGINX_PORT&lt;/code&gt; 这个变量&lt;strong&gt;不会&lt;/strong&gt;出现在容器内部，你在容器里执行 &lt;code&gt;printenv&lt;/code&gt; 是看不到它的——它只参与了拼凑 compose 文件这一步。&lt;/p&gt;
&lt;h3&gt;2. &lt;code&gt;env_file&lt;/code&gt;：批量把变量塞进容器&lt;/h3&gt;
&lt;p&gt;应用真正要读的配置（数据库地址、密码、开关等）一般这样给：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# app.env
DATABASE_URL=postgres://app:secret@db:5432/appdb
LOG_LEVEL=info
FEATURE_X=on
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    env_file:
      - app.env
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;容器启动后，在容器内执行 &lt;code&gt;printenv&lt;/code&gt; 就能看到 &lt;code&gt;DATABASE_URL&lt;/code&gt; 等变量。一个服务可以挂多个 &lt;code&gt;env_file&lt;/code&gt;，写成列表即可；多个文件里有同名变量时，&lt;strong&gt;后写的文件覆盖先写的&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;env_file&lt;/code&gt; 里也可以做插值（Compose 2.24 以后支持，需要在文件里用 &lt;code&gt;${...}&lt;/code&gt; 并配合 &lt;code&gt;env_file&lt;/code&gt; 的长语法 &lt;code&gt;required&lt;/code&gt; 等属性，一般场景用不到，先知道有这回事）。&lt;/p&gt;
&lt;h3&gt;3. &lt;code&gt;environment&lt;/code&gt;：直接写在 compose 里&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    environment:
      - TZ=Asia/Shanghai
      - LOG_LEVEL=debug
      - EMPTY_VALUE=
      - PASSTHROUGH_VAR
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两种写法：上面这种列表写法里，&lt;code&gt;KEY=VALUE&lt;/code&gt; 是直接赋值；只写 &lt;code&gt;KEY&lt;/code&gt; 不带等号（如 &lt;code&gt;PASSTHROUGH_VAR&lt;/code&gt;）表示&lt;strong&gt;把宿主机当前 shell 里的同名变量透传进容器&lt;/strong&gt;，宿主机没有这个变量时它在容器里就是空值（并会给出一条警告）。也可以写成映射写法，效果一样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    environment:
      TZ: Asia/Shanghai
      LOG_LEVEL: debug
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;4. 三者优先级&lt;/h3&gt;
&lt;p&gt;当同一个变量在多处出现时，谁说了算：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;注入容器时&lt;/strong&gt;：&lt;code&gt;environment&lt;/code&gt; 的优先级高于 &lt;code&gt;env_file&lt;/code&gt;。两边都有 &lt;code&gt;LOG_LEVEL&lt;/code&gt;，容器里拿到的是 &lt;code&gt;environment&lt;/code&gt; 写的值。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;插值时&lt;/strong&gt;：&lt;code&gt;${...}&lt;/code&gt; 的取值来源优先级是 &lt;strong&gt;宿主机 shell 环境变量 &amp;gt; &lt;code&gt;.env&lt;/code&gt; 文件&lt;/strong&gt;。也就是说，你临时想换个端口，不用改 &lt;code&gt;.env&lt;/code&gt;，直接：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;NGINX_PORT=9090 docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这一行 shell 里给的值会盖过 &lt;code&gt;.env&lt;/code&gt; 里的 &lt;code&gt;8080&lt;/code&gt;。这也是为什么 &lt;code&gt;.env&lt;/code&gt; 里放默认值、命令行临时覆盖，是很常见的用法。&lt;/p&gt;
&lt;h2&gt;二、变量插值语法详解&lt;/h2&gt;
&lt;p&gt;插值是把 compose 文件写活的关键，语法不多，但每个符号差别很大，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;用错了会静默出错&amp;lt;/span&amp;gt;。以下假设变量名为 &lt;code&gt;TAG&lt;/code&gt;：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;语法&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;${TAG}&lt;/code&gt; 或 &lt;code&gt;$TAG&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;直接替换；变量不存在时替换成空字符串，并打印一条警告&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;${TAG:-1.27}&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;变量&lt;strong&gt;未设置或为空&lt;/strong&gt;时用默认值 &lt;code&gt;1.27&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;${TAG-1.27}&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只有变量&lt;strong&gt;未设置&lt;/strong&gt;时才用默认值；设了空字符串就用空字符串&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;${TAG:?错误信息}&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;变量&lt;strong&gt;未设置或为空&lt;/strong&gt;时直接报错退出，并显示错误信息&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;${TAG?错误信息}&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只有变量&lt;strong&gt;未设置&lt;/strong&gt;时才报错&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;${TAG:+latest}&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;变量&lt;strong&gt;已设置且非空&lt;/strong&gt;时替换成 &lt;code&gt;latest&lt;/code&gt;，否则替换成空（进阶用法，偶尔用来拼可选片段）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;$$&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;转义，输出一个字面量的 &lt;code&gt;$&lt;/code&gt;，不做插值&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;冒号的区别就一条：&lt;strong&gt;带冒号连「空值」也算没设，不带冒号只有「压根没设」才算。&lt;/strong&gt; 拿不准就用带冒号的版本，符合大多数人的直觉。&lt;/p&gt;
&lt;p&gt;一个把这些全用上的完整例子：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    # DB_PASSWORD 没配就直接报错，不让它带着空密码启动
    image: myapp:${APP_VERSION:-1.0.0}
    environment:
      - DB_PASSWORD=${DB_PASSWORD:?请先在 .env 里设置 DB_PASSWORD}
      # $$ 转义：容器里要用的字面量 $ 符号，比如提示符或正则
      - PROMPT_SYMBOL=$$
    ports:
      # 端口也允许外部覆盖，不写死
      - &quot;${APP_PORT:-8080}:8080&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
插值只发生在 compose 文件里，容器内部的 shell 不会再处理这些 &lt;code&gt;${...}&lt;/code&gt;。另外 &lt;code&gt;$TAG&lt;/code&gt; 这种不带花括号的写法在值紧挨着其他字符时容易粘连出错，正式文件里统一用 &lt;code&gt;${TAG}&lt;/code&gt; 花括号写法。
:::&lt;/p&gt;
&lt;h2&gt;三、敏感信息：密码到底放哪&lt;/h2&gt;
&lt;p&gt;先说必须养成的习惯：&lt;strong&gt;&lt;code&gt;.env&lt;/code&gt;、&lt;code&gt;app.env&lt;/code&gt; 这类装着密码的文件，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不要提交进 Git&amp;lt;/span&amp;gt;。&lt;/strong&gt; 在项目里建 &lt;code&gt;.gitignore&lt;/code&gt; 并写上：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;.env
*.env
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后提交一份不含真实值的模板 &lt;code&gt;.env.example&lt;/code&gt; 给自己（或协作者）参考：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# .env.example —— 复制为 .env 后填入真实值
DB_PASSWORD=
APP_PORT=8080
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果密码已经不小心提交进 Git，光删文件没用，记录还在历史里，正确做法是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;直接改掉那个密码&lt;/strong&gt;&amp;lt;/span&amp;gt;，把泄露的凭据作废。&lt;/p&gt;
&lt;p&gt;再进一步，Compose 还提供了 &lt;code&gt;secrets&lt;/code&gt; 机制：把敏感值放在单独文件里，Compose 在运行时把它们挂载到容器的 &lt;code&gt;/run/secrets/&amp;lt;名字&amp;gt;&lt;/code&gt; 路径下，程序从文件读，而不是从环境变量读。好处是环境变量能被 &lt;code&gt;docker inspect&lt;/code&gt; 直接看到，而 secrets 文件相对隐蔽一些：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    secrets:
      - db_password

secrets:
  db_password:
    file: ./db_password.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;db_password.txt&lt;/code&gt; 里只放密码本身一行。注意：这要求你的应用支持「从文件读密码」（不少官方镜像支持，比如 PostgreSQL 镜像的 &lt;code&gt;POSTGRES_PASSWORD_FILE&lt;/code&gt; 环境变量就是干这个的）。日常个人项目里，把 &lt;code&gt;.env&lt;/code&gt; 管好、不进 Git、不写进镜像，已经能挡住绝大多数问题；&lt;code&gt;secrets&lt;/code&gt; 作为进阶选项了解即可。&lt;/p&gt;
&lt;h2&gt;四、healthcheck：让 Compose 知道服务「真的好了」&lt;/h2&gt;
&lt;p&gt;容器 &lt;code&gt;Up&lt;/code&gt; 只代表进程起来了，不代表服务能用了——PostgreSQL 进程在跑，但它还在做初始化、还没开始接受连接，这时候应用连过去就是报错。&lt;code&gt;healthcheck&lt;/code&gt; 就是让 Docker 周期性地「体检」容器，把状态细分成 &lt;code&gt;starting&lt;/code&gt;（体检中）、&lt;code&gt;healthy&lt;/code&gt;（可用）、&lt;code&gt;unhealthy&lt;/code&gt;（体检连续失败）。&lt;/p&gt;
&lt;h3&gt;1. 五个字段逐个讲&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;    healthcheck:
      test: [&quot;CMD&quot;, &quot;pg_isready&quot;, &quot;-U&quot;, &quot;postgres&quot;]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
&lt;/code&gt;&lt;/pre&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;test&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;体检命令。&lt;code&gt;[&quot;CMD&quot;, ...]&lt;/code&gt; 是直接执行程序（推荐）；&lt;code&gt;[&quot;CMD-SHELL&quot;, &quot;...&quot;]&lt;/code&gt; 是走一层 shell，可以用管道和 &lt;code&gt;&amp;amp;&amp;amp;&lt;/code&gt;；&lt;code&gt;[&quot;NONE&quot;]&lt;/code&gt; 表示禁用健康检查&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;interval&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;两次体检的间隔&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;timeout&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;单次体检的超时时间，超时算失败&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;retries&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;连续失败几次才标记为 &lt;code&gt;unhealthy&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;start_period&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;启动宽限期：这段时间内的失败不计数，给慢启动的服务留活路&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;还有个较新的字段 &lt;code&gt;start_interval&lt;/code&gt;：在 &lt;code&gt;start_period&lt;/code&gt; 期间用更密的间隔体检，好让服务一旦就绪就尽快转 &lt;code&gt;healthy&lt;/code&gt;，日常可以不写。&lt;/p&gt;
&lt;p&gt;体检命令的判定标准只有一个：&lt;strong&gt;退出码为 0 算通过，非 0 算失败。&lt;/strong&gt;&lt;/p&gt;
&lt;h3&gt;2. 三个可直接抄的例子&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;PostgreSQL&lt;/strong&gt;（镜像自带 &lt;code&gt;pg_isready&lt;/code&gt;）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  db:
    image: postgres:16
    environment:
      - POSTGRES_PASSWORD=${DB_PASSWORD:?请先在 .env 里设置 DB_PASSWORD}
    healthcheck:
      test: [&quot;CMD-SHELL&quot;, &quot;pg_isready -U postgres -d postgres&quot;]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;MySQL&lt;/strong&gt;（镜像自带 &lt;code&gt;mysqladmin&lt;/code&gt;；MySQL 8 的镜像也可以用 &lt;code&gt;mysqladmin ping&lt;/code&gt;）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  mysql:
    image: mysql:8.4
    environment:
      - MYSQL_ROOT_PASSWORD=${MYSQL_PASSWORD:?请先设置 MYSQL_PASSWORD}
    healthcheck:
      test: [&quot;CMD&quot;, &quot;mysqladmin&quot;, &quot;ping&quot;, &quot;-h&quot;, &quot;localhost&quot;, &quot;-uroot&quot;, &quot;-p$$MYSQL_ROOT_PASSWORD&quot;]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 30s
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意这里的 &lt;code&gt;$$MYSQL_ROOT_PASSWORD&lt;/code&gt;：双写 &lt;code&gt;$&lt;/code&gt; 是转义，意思是让&lt;strong&gt;容器内部&lt;/strong&gt;的 shell/程序去读它自己的环境变量，而不是让 Compose 在宿主机上插值。&lt;code&gt;mysqladmin ping&lt;/code&gt; 不带密码在开了密码认证时也能返回部分结果，为了严谨建议带上密码测。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;HTTP 服务&lt;/strong&gt;（用 &lt;code&gt;curl&lt;/code&gt; 或 &lt;code&gt;wget&lt;/code&gt; 探一个健康接口）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  web:
    image: myapp:latest
    healthcheck:
      test: [&quot;CMD-SHELL&quot;, &quot;curl -f http://localhost:8080/health || exit 1&quot;]
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 15s
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;curl -f&lt;/code&gt; 在 HTTP 状态码是 4xx/5xx 时返回非 0 退出码，正好符合体检的判定方式。&lt;/p&gt;
&lt;p&gt;:::warning
体检命令依赖容器镜像里&lt;strong&gt;有&lt;/strong&gt;这个工具。很多精简镜像（alpine、distroless）里既没有 &lt;code&gt;curl&lt;/code&gt; 也没有 &lt;code&gt;wget&lt;/code&gt;，这时 healthcheck 会一直失败，误报 &lt;code&gt;unhealthy&lt;/code&gt;。解决办法：优先用服务自带的探针（如 &lt;code&gt;pg_isready&lt;/code&gt;），实在没有就换带工具的镜像标签，或者在 Dockerfile 里把 &lt;code&gt;curl&lt;/code&gt; 装进去。
:::&lt;/p&gt;
&lt;h2&gt;五、depends_on：让启动有顺序，尤其是等数据库&lt;/h2&gt;
&lt;p&gt;光有体检还不够，要让体检结果参与编排，就靠 &lt;code&gt;depends_on&lt;/code&gt; 的条件。它有三种：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;condition&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;典型用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;service_started&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;依赖的容器&lt;strong&gt;进程启动&lt;/strong&gt;就算数（默认行为）&lt;/td&gt;
&lt;td&gt;只要求对方先拉起来，不关心能不能用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;service_healthy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;依赖的容器&lt;strong&gt;健康检查通过&lt;/strong&gt;才启动自己&lt;/td&gt;
&lt;td&gt;等数据库、缓存真正能连接了再启动应用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;service_completed_successfully&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;依赖的容器&lt;strong&gt;运行完并以 0 退出&lt;/strong&gt;才启动自己&lt;/td&gt;
&lt;td&gt;等一次性初始化/迁移任务跑完&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;注意：只要用到条件，就必须用&lt;strong&gt;长语法&lt;/strong&gt;（把依赖写成映射），短语法 &lt;code&gt;depends_on: [db]&lt;/code&gt; 只有 &lt;code&gt;service_started&lt;/code&gt; 的效果。&lt;/p&gt;
&lt;h3&gt;经典问题：数据库没就绪，应用启动就报错&lt;/h3&gt;
&lt;p&gt;没有健康检查配合时，经典翻车现场是这样的：&lt;code&gt;depends_on&lt;/code&gt; 只保证 db 容器先启动，app 紧跟着起来，第一件事连数据库——而 PostgreSQL 还在初始化数据目录——连接被拒，app 直接崩溃退出，日志里全是 &lt;code&gt;connection refused&lt;/code&gt;。以前大家靠在应用里写重试循环或者塞个 &lt;code&gt;sleep&lt;/code&gt; 硬扛，现在标准解法是 &lt;strong&gt;healthcheck + &lt;code&gt;service_healthy&lt;/code&gt;&lt;/strong&gt;，一份完整的例子：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  db:
    image: postgres:16
    environment:
      - POSTGRES_USER=app
      - POSTGRES_PASSWORD=${DB_PASSWORD:?请先在 .env 里设置 DB_PASSWORD}
      - POSTGRES_DB=appdb
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: [&quot;CMD-SHELL&quot;, &quot;pg_isready -U app -d appdb&quot;]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 15s

  migrate:
    image: myapp:latest
    command: ./run-migrations.sh
    depends_on:
      db:
        condition: service_healthy
    environment:
      - DATABASE_URL=postgres://app:${DB_PASSWORD}@db:5432/appdb

  app:
    image: myapp:latest
    ports:
      - &quot;${APP_PORT:-8080}:8080&quot;
    depends_on:
      db:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully
    environment:
      - DATABASE_URL=postgres://app:${DB_PASSWORD}@db:5432/appdb

volumes:
  db_data:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这份配置的启动顺序是：db 先起 → 体检通过（真的能连了）→ migrate 迁移任务开跑 → 迁移以 0 退出 → app 才启动。三个条件一次全用上了。&lt;/p&gt;
&lt;p&gt;两个必须知道的边界：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;depends_on&lt;/code&gt; 只管「启动这一刻」&lt;/strong&gt;。运行中途 db 重启了，app 不会跟着等它健康，要靠应用自身的连接重试兜底——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;编排解决顺序，代码解决健壮性&amp;lt;/span&amp;gt;，两回事。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;短语法在 Compose 老版本（V1）里还有「等网络就绪」的错觉&lt;/strong&gt;，V2 里短语法就是纯粹的先后拉起，别指望更多。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::warning
&lt;code&gt;docker compose down&lt;/code&gt; 时的停止顺序正好和启动相反：先停 app，再停 db，这个不用你操心。但如果某个服务体检一直不过（比如探针命令写错），依赖它的服务会一直等着，&lt;code&gt;up&lt;/code&gt; 看起来像卡死——先去看被依赖服务的健康状态，别干等，排查方法在最后一节。
:::&lt;/p&gt;
&lt;h2&gt;六、profiles：一份文件，按需点菜&lt;/h2&gt;
&lt;p&gt;有些服务不是每次都要：调试用的数据库管理面板（Adminer）、压测工具、一次性的数据导入脚本……把它们写进 compose 文件、又不想每次 &lt;code&gt;up&lt;/code&gt; 都跟着启动，就用 &lt;code&gt;profiles&lt;/code&gt; 给服务分组：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    ports:
      - &quot;8080:8080&quot;

  adminer:
    image: adminer:latest
    profiles:
      - debug
    ports:
      - &quot;8081:8080&quot;

  importer:
    image: myapp:latest
    command: ./import-data.sh
    profiles:
      - tools
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;行为规则很简单：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;没写 &lt;code&gt;profiles&lt;/code&gt; 的服务&lt;/strong&gt;（如 &lt;code&gt;app&lt;/code&gt;）：永远是默认成员，普通 &lt;code&gt;docker compose up -d&lt;/code&gt; 就启动。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;写了 &lt;code&gt;profiles&lt;/code&gt; 的服务&lt;/strong&gt;：默认&lt;strong&gt;不启动&lt;/strong&gt;，只有显式点名才算数。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;点名的方式有两种：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 方式一：命令行参数，可以叠加多个
docker compose --profile debug up -d
docker compose --profile debug --profile tools up -d

# 方式二：环境变量，适合写进当前 shell 或 CI
COMPOSE_PROFILES=debug docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;还有一个省心细节：&lt;strong&gt;被依赖会自动激活&lt;/strong&gt;。如果某个默认服务 &lt;code&gt;depends_on&lt;/code&gt; 了带 profile 的服务，那个服务会被连带拉起来，不需要你再手动加 &lt;code&gt;--profile&lt;/code&gt;。另外 &lt;code&gt;docker compose --profile debug ps&lt;/code&gt;、&lt;code&gt;down&lt;/code&gt; 等命令同理，操作带 profile 的服务时记得把 &lt;code&gt;--profile&lt;/code&gt; 带上，不然会「找不到」它们。&lt;/p&gt;
&lt;p&gt;适合 profiles 的场景再总结一下：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;典型成员&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;调试工具&lt;/td&gt;
&lt;td&gt;Adminer、日志查看器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;一次性任务&lt;/td&gt;
&lt;td&gt;迁移、导入、备份脚本&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本地开发才需要的模拟服务&lt;/td&gt;
&lt;td&gt;假邮件服务器、mock 接口&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;正式环境不用 profile、测试环境点开，一份文件两边跑。&lt;/p&gt;
&lt;h2&gt;七、多文件：base + override 拆开写&lt;/h2&gt;
&lt;p&gt;配置再大一点，就轮到多文件拆分了。约定是这样的：项目里同时存在 &lt;code&gt;docker-compose.yml&lt;/code&gt;（或 &lt;code&gt;compose.yaml&lt;/code&gt;）和 &lt;code&gt;docker-compose.override.yml&lt;/code&gt; 时，执行 &lt;code&gt;docker compose&lt;/code&gt; 命令会&lt;strong&gt;自动把 override 合并进来&lt;/strong&gt;，不用任何参数。&lt;/p&gt;
&lt;p&gt;典型分工：base 写公共部分，override 只写当前环境的差异：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# docker-compose.yml —— 公共配置，提交进 Git
services:
  app:
    image: myapp:${APP_VERSION:-1.0.0}
    environment:
      - LOG_LEVEL=info
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;# docker-compose.override.yml —— 本地开发专用，不提交
services:
  app:
    ports:
      - &quot;8080:8080&quot;
    volumes:
      - ./src:/app/src
    environment:
      - LOG_LEVEL=debug
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;本地 &lt;code&gt;docker compose up -d&lt;/code&gt; 自动得到：镜像和版本来自 base，端口映射和源码挂载来自 override，&lt;code&gt;LOG_LEVEL&lt;/code&gt; 被 override 的 &lt;code&gt;debug&lt;/code&gt; 盖掉。&lt;/p&gt;
&lt;p&gt;不用 override 约定、想完全自己指定文件时，用 &lt;code&gt;-f&lt;/code&gt;（可多次，&lt;strong&gt;顺序很重要，后写的盖先写的&lt;/strong&gt;）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;合并规则记个大概就够日常用了：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;单值选项&lt;/strong&gt;（&lt;code&gt;image&lt;/code&gt;、&lt;code&gt;command&lt;/code&gt;、单个 &lt;code&gt;environment&lt;/code&gt; 键）：后一个文件的值&lt;strong&gt;覆盖&lt;/strong&gt;前面的。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;映射类&lt;/strong&gt;（&lt;code&gt;environment&lt;/code&gt;、&lt;code&gt;labels&lt;/code&gt;）：按 key &lt;strong&gt;合并&lt;/strong&gt;，同 key 后者胜。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;列表类&lt;/strong&gt;（&lt;code&gt;ports&lt;/code&gt;、&lt;code&gt;volumes&lt;/code&gt;、&lt;code&gt;expose&lt;/code&gt;）：&lt;strong&gt;拼接&lt;/strong&gt;而不是覆盖，所以两边都映射了端口会全部生效（端口冲突了会在启动时报错）。&lt;/li&gt;
&lt;li&gt;完全不想合并、想让某个文件彻底接管，就别用 &lt;code&gt;-f&lt;/code&gt; 叠加，老实实只指定一份。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;八、进阶命令：先看清楚，再动手&lt;/h2&gt;
&lt;p&gt;Compose 用熟了之后，下面这几个命令能帮你少踩很多坑：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;校验并预览最终配置&lt;/strong&gt;——排查问题的第一招，把插值、合并、多文件全部算完后的「最终版」打印出来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose config
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;某个变量到底被替换成了什么、override 合并对不对，看这个输出一清二楚。只想确认语法没错不想看全文，可以加 &lt;code&gt;-q&lt;/code&gt;（quiet，只报错不输出）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose config -q
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;只列服务名或卷名也有专门参数：&lt;code&gt;docker compose config --services&lt;/code&gt;、&lt;code&gt;docker compose config --volumes&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;看日志&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 跟随输出，只看最后 100 行，重启后接着排查最常用
docker compose logs -f --tail=100

# 只看某个服务，并带时间戳
docker compose logs -f -t app
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;进容器执行命令&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 进正在运行的容器开个 shell 调试
docker compose exec app sh

# 不进交互，直接看容器里实际的环境变量（验证注入是否成功）
docker compose exec app printenv
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;看容器内的进程和整体状态&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose top
docker compose ps

# 自定义输出格式，只看名字和状态，写脚本时很好用
docker compose ps --format &quot;table {{.Name}}\t{{.State}}\t{{.Status}}&quot;

# 只看某个服务是否健康（输出里带 (healthy) / (unhealthy) 字样）
docker compose ps app
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;九、排障：两个高频问题&lt;/h2&gt;
&lt;h3&gt;1. 变量没生效&lt;/h3&gt;
&lt;p&gt;按这个顺序查，基本都能定位：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;先看最终配置&lt;/strong&gt;：&lt;code&gt;docker compose config&lt;/code&gt;，找到对应服务，看变量被替换成了什么。如果这里就是错的，问题在插值层：检查 &lt;code&gt;.env&lt;/code&gt; 在不在 compose 文件同目录、变量名有没有写错、是不是被 shell 里同名变量盖掉了（shell 优先级更高）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;再看容器内部&lt;/strong&gt;：&lt;code&gt;docker compose exec &amp;lt;服务名&amp;gt; printenv | grep &amp;lt;变量名&amp;gt;&lt;/code&gt;。最终配置对、容器里没有，是注入层的问题：&lt;code&gt;env_file&lt;/code&gt; 路径写错、或者变量只写在 &lt;code&gt;.env&lt;/code&gt; 里——再强调一遍，&lt;strong&gt;&lt;code&gt;.env&lt;/code&gt; 不进容器&lt;/strong&gt;，要给容器用必须走 &lt;code&gt;env_file&lt;/code&gt; 或 &lt;code&gt;environment&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;改了没重启&lt;/strong&gt;：改完 &lt;code&gt;.env&lt;/code&gt; 或 compose 文件后，已经跑着的容器不会自动更新，必须重新 &lt;code&gt;docker compose up -d&lt;/code&gt; 让它重建，光 &lt;code&gt;restart&lt;/code&gt; 不会重新读配置。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;2. healthcheck 一直 unhealthy&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;docker compose ps&lt;/code&gt; 里状态一直 &lt;code&gt;(health: starting)&lt;/code&gt; 或者 &lt;code&gt;(unhealthy)&lt;/code&gt;，这样查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;看健康检查的原始记录&lt;/strong&gt;，Docker 把每次体检的退出码和输出都存了：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;docker inspect --format=&apos;{{json .State.Health}}&apos; &amp;lt;容器名&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出里的 &lt;code&gt;Log&lt;/code&gt; 数组是最近几次体检记录，重点看 &lt;code&gt;ExitCode&lt;/code&gt; 和 &lt;code&gt;Output&lt;/code&gt;——命令不存在会报 &lt;code&gt;executable file not found&lt;/code&gt;，连接失败会直接把错误打在 &lt;code&gt;Output&lt;/code&gt; 里，一看便知。&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;手动在容器里跑一遍体检命令&lt;/strong&gt;，复现它到底卡在哪：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;docker compose exec db pg_isready -U app -d appdb
echo $?   # 0 是通，非 0 是不通
&lt;/code&gt;&lt;/pre&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;对一下时间参数&lt;/strong&gt;：服务本来就要启动 40 秒，你 &lt;code&gt;start_period&lt;/code&gt; 只给了 10 秒、&lt;code&gt;retries&lt;/code&gt; 又小，它会在还没就绪时就被判死刑。慢启动的服务（数据库首次初始化、Java 应用）把 &lt;code&gt;start_period&lt;/code&gt; 给足、 &lt;code&gt;retries&lt;/code&gt; 给大。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;确认命令在镜像里存在&lt;/strong&gt;：精简镜像没 &lt;code&gt;curl&lt;/code&gt; 是最常见的乌龙，按第四节警告里的方法换探针。&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;变量三件套分工明确：&lt;code&gt;.env&lt;/code&gt; 管插值、&lt;code&gt;env_file&lt;/code&gt; 批量注入、&lt;code&gt;environment&lt;/code&gt; 单个指定且优先级最高；shell 变量能临时盖过 &lt;code&gt;.env&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;插值记住四件套：&lt;code&gt;${VAR:-默认值}&lt;/code&gt; 给退路、&lt;code&gt;${VAR:?报错}&lt;/code&gt; 把必填项卡死、&lt;code&gt;$$&lt;/code&gt; 转义给容器留字面量。&lt;/li&gt;
&lt;li&gt;密码不进 Git、不写死在 compose 里，进阶可用 &lt;code&gt;secrets&lt;/code&gt; 从文件读。&lt;/li&gt;
&lt;li&gt;healthcheck 回答「服务能不能用」，&lt;code&gt;depends_on&lt;/code&gt; 的 &lt;code&gt;service_healthy&lt;/code&gt; 把这个答案变成启动条件，数据库没就绪应用先等着，这是本篇&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;最值得抄走的一招&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;li&gt;profiles 管「要不要启动」，多文件管「不同环境怎么变」，再配合 &lt;code&gt;docker compose config&lt;/code&gt; 先预览再动手，Compose 的进阶用法就齐了。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>容器排障深挖：nsenter 与 strace</title><link>https://www.anexns.cloudns.org/posts/docker-deep-troubleshooting/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-deep-troubleshooting/</guid><description>容器里没有 shell、没有工具时怎么办：用 nsenter 从宿主机进入容器的网络与挂载命名空间，用 strace 跟踪系统调用定位卡死与报错，再加上 tcpdump 进容器抓包的完整排障手法。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h1&gt;容器排障深挖：nsenter 与 strace&lt;/h1&gt;
&lt;p&gt;容器进程突然不响应了，你敲下 &lt;code&gt;docker exec&lt;/code&gt;，结果只有一行报错：镜像里根本没有 shell。精简镜像、distroless 镜像、scratch 镜像在生产环境越来越常见，它们把攻击面和体积都压到了最小，代价是排障时你连 &lt;code&gt;ls&lt;/code&gt;、&lt;code&gt;ps&lt;/code&gt;、&lt;code&gt;curl&lt;/code&gt; 都没有。更麻烦的是，很多问题压根不在容器「里面」——进程卡死在某个系统调用上、网络命名空间里的路由不对、cgroup 限额早就顶满了，这些在容器内部用常规命令根本看不见。&lt;/p&gt;
&lt;p&gt;这一篇讲的是一套不依赖容器内部工具的深挖手法，全部从宿主机侧下手：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;用 &lt;code&gt;docker inspect&lt;/code&gt; 拿到容器主进程在宿主机上的真实 Pid；&lt;/li&gt;
&lt;li&gt;用 &lt;code&gt;nsenter&lt;/code&gt; 钻进容器的网络、挂载、进程等命名空间，借宿主机的工具排查；&lt;/li&gt;
&lt;li&gt;用 &lt;code&gt;strace&lt;/code&gt; 直接跟踪进程的系统调用，看它到底卡在哪一行；&lt;/li&gt;
&lt;li&gt;用 &lt;code&gt;tcpdump&lt;/code&gt; 在容器的网络命名空间里抓包，确认流量到底通没通。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;基础的命令速查和常规排障链路，可以先看《Docker 常用命令速查与排障实战》：/posts/docker-commands-troubleshooting/ 。这一篇是它的进阶篇，处理的是常规命令失效之后的疑难杂症。&lt;/p&gt;
&lt;h2&gt;为什么需要这套手法&lt;/h2&gt;
&lt;p&gt;先把场景说清楚。日常排障里最顺手的路径是 &lt;code&gt;docker exec -it &amp;lt;容器&amp;gt; sh&lt;/code&gt;，进容器里慢慢看。但这条路在下面几种情况下直接断掉：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;为什么 exec 进不去或没用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;distroless 镜像（如 gcr.io/distroless 系列）&lt;/td&gt;
&lt;td&gt;只有应用本体和运行时，没有 shell、没有 coreutils&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;scratch 镜像（Go 静态编译常见）&lt;/td&gt;
&lt;td&gt;镜像里只有一个二进制文件，连 libc 都没有&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;容器主进程已卡死&lt;/td&gt;
&lt;td&gt;exec 需要在容器里 fork 新进程，进程空间异常时直接超时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;生产环境规范严格&lt;/td&gt;
&lt;td&gt;不允许往容器里临时装工具、不允许改镜像，排障不能动现场&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;问题在命名空间层面&lt;/td&gt;
&lt;td&gt;容器内工具看到的视图本身就是「案发现场」，需要从宿主机侧交叉验证&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;还有一个更根本的原因：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;容器不是虚拟机，它在宿主机上就是一组被命名空间和 cgroup 包起来的普通进程&amp;lt;/span&amp;gt;。既然是普通进程，宿主机上针对普通进程的全部武器——&lt;code&gt;nsenter&lt;/code&gt;、&lt;code&gt;strace&lt;/code&gt;、&lt;code&gt;/proc&lt;/code&gt; 文件系统——就全都能用，而且视角更高、信息更全。这套手法的本质，就是跳出容器给你的那一小块视图，回到宿主机层面看全局。&lt;/p&gt;
&lt;p&gt;:::warning
这套手法全部需要宿主机 root 权限，且只能用在你自己有完全控制权的机器上。&lt;code&gt;nsenter&lt;/code&gt; 和 &lt;code&gt;strace&lt;/code&gt; 能看到进程的全部内存视图、网络流量和文件访问，给别人机器上的容器用属于越权操作，别碰。
:::&lt;/p&gt;
&lt;h2&gt;原理速通：容器进程在宿主机上长什么样&lt;/h2&gt;
&lt;p&gt;动手之前，先建立一个正确的 mental model，后面所有命令都是它的推论。&lt;/p&gt;
&lt;p&gt;Linux 用命名空间（namespace）给进程做视图隔离。同一个进程，在容器里看自己是 1 号进程、网卡只有 eth0、根目录是镜像那一层；在宿主机上看，它有一个真实的 Pid（比如 12847）、真实的网络在宿主机的网络栈里、真实的文件落在 overlay2 的目录里。隔离的维度一共有七类，本篇用得上的是前四个：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命名空间&lt;/th&gt;
&lt;th&gt;隔离内容&lt;/th&gt;
&lt;th&gt;排障时的意义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;mount（mnt）&lt;/td&gt;
&lt;td&gt;挂载点与文件系统视图&lt;/td&gt;
&lt;td&gt;决定进程看到的根目录和挂载卷&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;net&lt;/td&gt;
&lt;td&gt;网卡、路由、iptables、端口&lt;/td&gt;
&lt;td&gt;决定进程的网络连通性&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;pid&lt;/td&gt;
&lt;td&gt;进程编号与进程树视图&lt;/td&gt;
&lt;td&gt;决定 &lt;code&gt;ps&lt;/code&gt; 能看到哪些进程&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;uts&lt;/td&gt;
&lt;td&gt;主机名与域名&lt;/td&gt;
&lt;td&gt;决定 &lt;code&gt;hostname&lt;/code&gt; 的输出&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ipc&lt;/td&gt;
&lt;td&gt;进程间通信（信号量、共享内存）&lt;/td&gt;
&lt;td&gt;少数中间件排障会用到&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;user&lt;/td&gt;
&lt;td&gt;用户与组 ID 映射&lt;/td&gt;
&lt;td&gt;rootless 场景相关&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;cgroup&lt;/td&gt;
&lt;td&gt;cgroup 视图&lt;/td&gt;
&lt;td&gt;影响进程读到的限额信息&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;找到容器主进程的真实 Pid 是第一步，命令固定：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 取容器主进程在宿主机上的 Pid
docker inspect -f &apos;{{.State.Pid}}&apos; myapp

# 输出示例
12847
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拿到这个 Pid 之后，宿主机上立刻多出三个信息入口：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 进程的完整状态都在这个目录里
ls /proc/12847/

# 2. 进程眼里的根目录，就是这个符号链接指向的位置
ls -l /proc/12847/root

# 3. 进程所属的每个命名空间，都是一个可进入的句柄
ls -l /proc/12847/ns/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;/proc/&amp;lt;pid&amp;gt;/ns/&lt;/code&gt; 目录下每个文件都对应一个命名空间，&lt;code&gt;nsenter&lt;/code&gt; 做的事情，本质上就是调用 &lt;code&gt;setns()&lt;/code&gt; 系统调用把自己「塞进」这些命名空间里。理解了这一点，下面所有操作都不需要死记硬背。&lt;/p&gt;
&lt;h2&gt;nsenter 全套：借宿主机的工具进容器的空间&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;nsenter&lt;/code&gt; 属于 util-linux 包，绝大多数发行版默认自带。先确认一下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;which nsenter || apt-get install -y util-linux
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;参数对照表&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;nsenter&lt;/code&gt; 的核心参数就两个：&lt;code&gt;-t&lt;/code&gt; 指定目标进程 Pid，后面跟的字母决定进哪个命名空间。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;进入的命名空间&lt;/th&gt;
&lt;th&gt;典型用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-m&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;mount（挂载）&lt;/td&gt;
&lt;td&gt;看容器眼里的文件系统、挂载卷&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-n&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;net（网络）&lt;/td&gt;
&lt;td&gt;查网卡、路由、监听端口、抓包&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-p&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;pid（进程）&lt;/td&gt;
&lt;td&gt;配合 &lt;code&gt;-m&lt;/code&gt; 看容器内的进程树&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-u&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;uts&lt;/td&gt;
&lt;td&gt;看/改容器眼里的主机名，极少用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-i&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;ipc&lt;/td&gt;
&lt;td&gt;查共享内存、信号量，偶尔用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-U&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;user&lt;/td&gt;
&lt;td&gt;rootless 容器排障时配合用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-a&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;全部&lt;/td&gt;
&lt;td&gt;一次性进入所有命名空间&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;无字母，仅 &lt;code&gt;-t&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不进任何空间&lt;/td&gt;
&lt;td&gt;只以目标进程为锚点运行命令（配合读 /proc 用）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;进网络命名空间：排查连通性&lt;/h3&gt;
&lt;p&gt;这是最高频的用法。目标：在容器的网络视图里，用宿主机上现成的 &lt;code&gt;ip&lt;/code&gt;、&lt;code&gt;ss&lt;/code&gt;、&lt;code&gt;curl&lt;/code&gt; 干活。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;PID=$(docker inspect -f &apos;{{.State.Pid}}&apos; myapp)

# 进入容器的网络命名空间，后续命令都在容器的网络视图里执行
nsenter -t $PID -n ip addr
nsenter -t $PID -n ip route
nsenter -t $PID -n ss -tlnp
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个关键检查点，按顺序看：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 容器自己的 IP 和网卡状态（UP 还是 DOWN）
nsenter -t $PID -n ip -br addr

# 默认网关在不在、指向对不对
nsenter -t $PID -n ip route show default

# 从容器视角直连网关和外部目标
nsenter -t $PID -n ping -c 2 172.17.0.1
nsenter -t $PID -n curl -v --connect-timeout 3 http://172.17.0.5:3306
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意最后一个细节：在网络命名空间里用宿主机的 &lt;code&gt;curl&lt;/code&gt; 去连数据库端口，验证的是「容器网络视角下这条路通不通」，而 &lt;code&gt;curl&lt;/code&gt; 二进制本身来自宿主机文件系统——因为我们只进了 net 空间，没进 mount 空间，文件系统用的还是宿主机的。这正是 &lt;code&gt;nsenter&lt;/code&gt; 的精妙之处：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;每个命名空间可以单独进，只借需要的那个视图，其余全用宿主机的环境和工具&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h3&gt;进挂载与进程空间：看容器眼里的世界&lt;/h3&gt;
&lt;p&gt;想完整复现容器内部的视图，用 &lt;code&gt;-m -p&lt;/code&gt; 组合，再 chroot 到进程的根目录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;PID=$(docker inspect -f &apos;{{.State.Pid}}&apos; myapp)

# 进入挂载+进程+网络空间，并切换根目录到容器的根
nsenter -t $PID -m -p -n chroot /proc/$PID/root /bin/sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
这条命令对 scratch 镜像同样无效——容器根目录里没有 &lt;code&gt;/bin/sh&lt;/code&gt;，chroot 进去也没有 shell 可跑。它的价值在于 distroless 之外、镜像里有 shell 但 &lt;code&gt;docker exec&lt;/code&gt; 通道坏了的场合。scratch 镜像请直接用后面的 &lt;code&gt;/proc/&amp;lt;pid&amp;gt;/root&lt;/code&gt; 静态查看法。
:::&lt;/p&gt;
&lt;p&gt;只看文件、不需要交互时，更轻量的办法是直接读目录，后面备选手法一节会展开。&lt;/p&gt;
&lt;h3&gt;在容器的网络空间里抓包&lt;/h3&gt;
&lt;p&gt;判断「请求到底有没有到达容器」「容器发出去了没有」，抓包是最硬的证据：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;PID=$(docker inspect -f &apos;{{.State.Pid}}&apos; myapp)

# 在容器网络命名空间里抓 eth0 的包，只看 8080 端口
nsenter -t $PID -n tcpdump -i eth0 -nn port 8080

# 抓下来存文件，拿回宿主机用 Wireshark 慢慢看
nsenter -t $PID -n tcpdump -i eth0 -nn -w /tmp/app.pcap port 8080
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;读抓包结果时盯住三件事：有没有 SYN 进来（请求是否到达）、有没有 SYN-ACK 回去（应用是否在监听并响应）、握手之后有没有立刻 RST（应用层主动拒绝还是防火墙拦截）。这三点能把「网络不通」这个笼统结论拆成具体的断点位置。&lt;/p&gt;
&lt;h2&gt;没有 nsenter 时的备选手法：/proc 大法&lt;/h2&gt;
&lt;p&gt;老系统、精简宿主机上可能没有 &lt;code&gt;nsenter&lt;/code&gt;，或者版本太旧缺参数。这时 &lt;code&gt;/proc&lt;/code&gt; 文件系统就是备选通道，下面三招不需要任何额外工具：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;PID=$(docker inspect -f &apos;{{.State.Pid}}&apos; myapp)

# 招式一：直接浏览容器眼里的整个文件系统（只读查看足够排障）
ls /proc/$PID/root/etc/
cat /proc/$PID/root/etc/resolv.conf

# 招式二：看进程的挂载表，确认卷挂对了没有
cat /proc/$PID/mounts

# 招式三：看进程实际加载的环境变量（排查配置注入失败极好用）
tr &apos;\0&apos; &apos;\n&apos; &amp;lt; /proc/$PID/environ
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;其中招式三特别值得记住：容器启动后改了 Compose 文件但没重建、或者 &lt;code&gt;--env-file&lt;/code&gt; 没生效时，&lt;code&gt;/proc/&amp;lt;pid&amp;gt;/environ&lt;/code&gt; 里是进程真正吃到的环境变量，一个字都做不了假。&lt;/p&gt;
&lt;p&gt;还有一招是看命名空间本身的归属关系，判断两个容器是否在同一网络空间（比如 sidecar 模式）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 比较两个进程的 net 命名空间 inode，一样就是共享网络
ls -l /proc/12847/ns/net /proc/13502/ns/net
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;strace 入门：看进程到底卡在哪一行&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;nsenter&lt;/code&gt; 解决的是「视图」问题，&lt;code&gt;strace&lt;/code&gt; 解决的是「行为」问题：进程不响应、不报错、不退出，它到底在等什么？&lt;code&gt;strace&lt;/code&gt; 把进程发出的每一个系统调用都打印出来，这是 Linux 排障里最接近「读心术」的工具。&lt;/p&gt;
&lt;h3&gt;基本姿势：附加到运行中的进程&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;PID=$(docker inspect -f &apos;{{.State.Pid}}&apos; myapp)

# 附加跟踪，按 Ctrl+C 停止（只是停止跟踪，不影响目标进程）
strace -p $PID

# 带时间戳和调用耗时，输出更易读
strace -tt -T -p $PID
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;strace&lt;/code&gt; 附加到生产进程会让它明显变慢——每个系统调用都要被拦截两次。高并发进程上&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要长时间挂着 strace&amp;lt;/span&amp;gt;，看清卡点就立刻撤；更不要在流量高峰对核心交易进程使用。
:::&lt;/p&gt;
&lt;p&gt;几个必备参数：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-p &amp;lt;pid&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;附加到已运行进程&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-f&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;跟踪子进程与线程（多线程程序必加）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-tt&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每行打印微秒级时间戳&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-T&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每行末尾打印该调用的耗时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-e trace=network&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只看网络类调用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-e trace=file&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只看文件类调用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-e trace=%file&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;同上（新版写法）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-o file.log&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;输出写文件，避免刷屏&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-s 200&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;字符串打印长度上限，默认 32 太短&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;实战例一：卡在 connect，连不上数据库&lt;/h3&gt;
&lt;p&gt;进程假死，&lt;code&gt;strace -p&lt;/code&gt; 挂上去，满屏重复同一行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;connect(7, {sa_family=AF_INET, sin_port=htons(3306), sin_addr=inet_addr(&quot;172.17.0.5&quot;)}, 16) = -1 EINPROGRESS (Operation now in progress)
poll([{fd=7, events=POLLOUT}], 1, 5000) = 0 (Timeout)
close(7) = 0
socket(AF_INET, SOCK_STREAM, IPPROTO_IP) = 7
connect(7, {sa_family=AF_INET, sin_port=htons(3306), sin_addr=inet_addr(&quot;172.17.0.5&quot;)}, 16) = -1 EINPROGRESS
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;读法：进程在不停地新建连接、等 5 秒超时、关掉重来。结论非常明确——&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不是应用逻辑死锁，是目标 172.17.0.5 的 3306 端口根本连不上&amp;lt;/span&amp;gt;，应用在无限重试。下一步就该去查数据库容器是不是挂了、网络通不通（正好接回 &lt;code&gt;nsenter -n&lt;/code&gt; 那一套），而不是去翻应用代码。&lt;/p&gt;
&lt;h3&gt;实战例二：反复 open 一个不存在的文件&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;openat(AT_FDCWD, &quot;/app/config/prod.yaml&quot;, O_RDONLY) = -1 ENOENT (No such file or directory)
openat(AT_FDCWD, &quot;/app/config/prod.yaml&quot;, O_RDONLY) = -1 ENOENT (No such file or directory)
openat(AT_FDCWD, &quot;/app/config/prod.yaml&quot;, O_RDONLY) = -1 ENOENT (No such file or directory)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回值 &lt;code&gt;-1 ENOENT&lt;/code&gt; 就是文件不存在。进程在循环重试读同一个路径，说明挂载或配置注入出了问题：卷没挂上、路径拼错、或者环境变量指错了环境。配合前面的 &lt;code&gt;cat /proc/&amp;lt;pid&amp;gt;/mounts&lt;/code&gt; 和 &lt;code&gt;ls /proc/&amp;lt;pid&amp;gt;/root/app/config/&lt;/code&gt; 两条命令，五分钟内就能锁定到底是没挂还是挂错了。&lt;/p&gt;
&lt;p&gt;常见返回值速查：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;返回值&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;常见原因&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ENOENT&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;文件/路径不存在&lt;/td&gt;
&lt;td&gt;挂载缺失、路径写错&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;EACCES&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;权限不足&lt;/td&gt;
&lt;td&gt;文件属主、只读挂载、能力限制&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ECONNREFUSED&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;连接被拒绝&lt;/td&gt;
&lt;td&gt;对端端口没监听&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ETIMEDOUT&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;连接超时&lt;/td&gt;
&lt;td&gt;防火墙丢包、路由不通&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;EAGAIN&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;资源暂时不可用&lt;/td&gt;
&lt;td&gt;非阻塞调用没就绪，常与 poll 配合出现&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;实战例三：futex 满屏，进程在等锁&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;futex(0x7f8c4c0a3d80, FUTEX_WAIT_BITSET_PRIVATE|FUTEX_CLOCK_REALTIME, 0, NULL, FUTEX_BITSET_MATCH_ANY) = -1 ETIMEDOUT (Connection timed out)
futex(0x7f8c4c0a3d80, FUTEX_WAIT_BITSET_PRIVATE|FUTEX_CLOCK_REALTIME, 0, NULL, FUTEX_BITSET_MATCH_ANY) = -1 ETIMEDOUT
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;futex&lt;/code&gt; 是线程同步的底层机制。满屏 &lt;code&gt;FUTEX_WAIT&lt;/code&gt; 且没有其他调用，说明线程在等一把锁或一个条件变量——这是应用层死锁或线程池耗尽的典型特征，宿主机侧能做的到此为止，结论是「带上线程栈快照回去查代码」，而不是继续在系统层打转。判断「问题在系统层还是应用层」，本身就是 &lt;code&gt;strace&lt;/code&gt; 最重要的产出之一。&lt;/p&gt;
&lt;h3&gt;只看某一类调用：按类别过滤&lt;/h3&gt;
&lt;p&gt;全量输出太吵时，用 &lt;code&gt;-e trace=&lt;/code&gt; 只盯一类：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 只看网络：进程在跟谁通信、连得上连不上
strace -f -e trace=network -p $PID

# 只看文件：进程在读哪些配置、写哪些路径
strace -f -e trace=%file -p $PID

# 只看内存与进程控制：排查疯狂 fork 或 mmap 的问题
strace -f -e trace=%memory,%process -p $PID
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;其他深挖工具：每个一段，够用为止&lt;/h2&gt;
&lt;h3&gt;docker top：容器进程在宿主机上的全貌&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker top myapp aux
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它列出容器内所有进程在宿主机视角下的 Pid、CPU、内存占用。容器里 &lt;code&gt;ps&lt;/code&gt; 看不到宿主机 Pid，这里一清二楚，多进程容器（主进程加 sidecar）排障时先用它摸清进程构成。&lt;/p&gt;
&lt;h3&gt;/proc/&amp;lt;pid&amp;gt;/status 与 limits：状态与真实限额&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;PID=$(docker inspect -f &apos;{{.State.Pid}}&apos; myapp)

# 线程数、内存峰值、进程状态（R/S/D 哪个字母很关键）
grep -E &apos;State|Threads|VmRSS&apos; /proc/$PID/status

# 进程真实生效的资源限制（打开文件数、进程数上限都在这）
cat /proc/$PID/limits
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;State&lt;/code&gt; 是 &lt;code&gt;D&lt;/code&gt;（不可中断睡眠）要特别留意，通常意味着卡在 I/O 上，多半是存储或网络文件系统出了问题。&lt;code&gt;limits&lt;/code&gt; 里的 &lt;code&gt;Max open files&lt;/code&gt; 则是排查「too many open files」时最权威的数字，比任何配置文件都准。&lt;/p&gt;
&lt;h3&gt;cgroup v2 文件：看限额与实际用量&lt;/h3&gt;
&lt;p&gt;Compose 里写了 &lt;code&gt;mem_limit&lt;/code&gt;、CPU 配额，到底生效没有、用了多少，去 cgroup 文件系统里看原始数据：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;PID=$(docker inspect -f &apos;{{.State.Pid}}&apos; myapp)

# 找到进程所在的 cgroup 路径
cat /proc/$PID/cgroup

# 路径形如 0::/system.slice/docker-&amp;lt;容器ID&amp;gt;.scope，拼出目录后查看
CG=/sys/fs/cgroup/system.slice/docker-$(docker inspect -f &apos;{{.Id}}&apos; myapp).scope
cat $CG/memory.max      # 内存上限（max 表示不限）
cat $CG/memory.current  # 当前实际用量
cat $CG/memory.events   # 重点看 oom_kill 计数：大于 0 就是被 OOM 杀过
cat $CG/cpu.stat        # 看 nr_throttled：被 CPU 限流的次数
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;memory.events&lt;/code&gt; 里的 &lt;code&gt;oom_kill&lt;/code&gt; 和 &lt;code&gt;cpu.stat&lt;/code&gt; 里的 &lt;code&gt;nr_throttled&lt;/code&gt;、&lt;code&gt;throttled_usec&lt;/code&gt; 是两个黄金指标：容器「莫名重启」先看前者，容器「莫名变卡」先看后者，不用猜。&lt;/p&gt;
&lt;h3&gt;ss：在容器的网络空间里查监听&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;PID=$(docker inspect -f &apos;{{.State.Pid}}&apos; myapp)

# 容器里到底哪些端口在监听、被哪个进程占着
nsenter -t $PID -n ss -tlnp

# 已建立的连接全景：连了谁、状态如何
nsenter -t $PID -n ss -tnp state established
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;应用自称监听 8080、&lt;code&gt;ss&lt;/code&gt; 里却只有 8000——这种配置与现实不一致的情况，&lt;code&gt;ss&lt;/code&gt; 一眼就能戳穿，比翻日志快得多。&lt;/p&gt;
&lt;h2&gt;完整排障剧本：一个 502 的全程定位&lt;/h2&gt;
&lt;p&gt;把上面的工具串起来，走一遍真实场景：Nginx 反向代理返回 502，怀疑后端容器有问题，但后端镜像是 distroless，没有 shell。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步：确认后端容器进程还活着、状态如何。&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker ps --filter name=backend
docker inspect -f &apos;{{.State.Status}} {{.State.Pid}}&apos; backend
# 输出：running 12847 —— 进程在，但活着不等于在干活
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第二步：看它有没有在监听该监听的端口。&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;nsenter -t 12847 -n ss -tlnp
# 输出里只有 :::8000，没有预期的 8080 —— 第一个疑点出现
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第三步：确认应用实际吃的配置是什么。&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;tr &apos;\0&apos; &apos;\n&apos; &amp;lt; /proc/12847/environ | grep -i port
# 输出：APP_PORT=8000 —— 配置注入的是 8000，而反代按 8080 转发
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第四步（如果端口对得上，就继续往深挖）：看进程卡在哪。&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;strace -f -tt -T -p 12847 2&amp;gt;&amp;amp;1 | head -50
# 若满屏 connect 超时或 futex 等待，按前面实战例的读法判断断点
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第五步：交叉验证网络通路。&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 从反代容器的网络空间出发，连后端地址验证整条链路
RPID=$(docker inspect -f &apos;{{.State.Pid}}&apos; nginx-proxy)
nsenter -t $RPID -n curl -v --connect-timeout 3 http://172.18.0.3:8000/health
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这个剧本的价值不在某一条命令，而在顺序：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;先确认进程、再确认监听、再确认配置、最后才深挖行为&amp;lt;/span&amp;gt;，每一层排除掉一类问题，不跳步、不猜测。本例的结论是端口配置不一致——改反代目标端口或改注入变量，二选一，重启生效，502 消失。全程没有进过容器内部一次。&lt;/p&gt;
&lt;h2&gt;排障速查：症状到工具的映射&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;症状&lt;/th&gt;
&lt;th&gt;第一手工具&lt;/th&gt;
&lt;th&gt;看什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;exec 进不去、镜像没 shell&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker inspect&lt;/code&gt; + &lt;code&gt;nsenter&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;用宿主机工具进各命名空间&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;进程活着但不响应&lt;/td&gt;
&lt;td&gt;&lt;code&gt;strace -p&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;卡在 connect、futex 还是 read&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;容器莫名重启&lt;/td&gt;
&lt;td&gt;cgroup &lt;code&gt;memory.events&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;oom_kill&lt;/code&gt; 是否大于 0&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;容器莫名变卡&lt;/td&gt;
&lt;td&gt;cgroup &lt;code&gt;cpu.stat&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;nr_throttled&lt;/code&gt; 是否在涨&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;端口连不上&lt;/td&gt;
&lt;td&gt;&lt;code&gt;nsenter -n ss -tlnp&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;到底监听了哪个端口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;不知道请求到没到容器&lt;/td&gt;
&lt;td&gt;&lt;code&gt;nsenter -n tcpdump&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;有没有 SYN 进来&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;怀疑配置没生效&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/proc/&amp;lt;pid&amp;gt;/environ&lt;/code&gt;、&lt;code&gt;/proc/&amp;lt;pid&amp;gt;/mounts&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;进程真实吃到的变量与挂载&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件读写报错&lt;/td&gt;
&lt;td&gt;&lt;code&gt;strace -e trace=%file&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;ENOENT 还是 EACCES、具体哪个路径&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
排障时最容易犯的错，是在没留证据的情况下先重启容器「试试看」。进程一重启，&lt;code&gt;strace&lt;/code&gt; 现场、连接状态、cgroup 计数全部清零，问题可能一周后原样复发。正确顺序永远是：先取证，再处置。
:::&lt;/p&gt;
&lt;h2&gt;安全与权限提醒&lt;/h2&gt;
&lt;p&gt;这套手法威力大，边界也要清楚：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;全部操作需要宿主机 root。能 &lt;code&gt;nsenter&lt;/code&gt; 进任意容器的网络空间，就等于能截获这台机器上所有容器的流量；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;strace&lt;/code&gt; 能看到进程读写的一切数据，包括正在处理的密钥和请求内容，输出日志不要随手外发；&lt;/li&gt;
&lt;li&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;只在自己有完全控制权的机器上使用&amp;lt;/span&amp;gt;。公司共享宿主机、客户的机器上，先走授权流程；&lt;/li&gt;
&lt;li&gt;抓包文件 &lt;code&gt;.pcap&lt;/code&gt; 里可能含明文凭据，排障结束及时删除，别留在 &lt;code&gt;/tmp&lt;/code&gt; 里过夜。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇的核心其实只有一句话：容器在宿主机上就是普通进程，宿主机排障的全部工具都适用。具体落到操作上，记住这条链就够了——&lt;code&gt;docker inspect&lt;/code&gt; 取 Pid 是钥匙，&lt;code&gt;nsenter&lt;/code&gt; 按需借视图（网络问题进 &lt;code&gt;-n&lt;/code&gt;、文件问题看 &lt;code&gt;/proc/&amp;lt;pid&amp;gt;/root&lt;/code&gt;），&lt;code&gt;strace&lt;/code&gt; 看行为（connect 看网络、openat 看文件、futex 看锁），cgroup 文件看限额的真实账目。把「先取证、再处置、先外围、后深挖」的顺序养成习惯，distroless 和 scratch 镜像就不再是排障的黑盒，而是少了一层干扰的透明现场。&lt;/p&gt;
</content:encoded></item><item><title>GPU 容器实战：NVIDIA Container Toolkit</title><link>https://www.anexns.cloudns.org/posts/docker-gpu-nvidia/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-gpu-nvidia/</guid><description>让容器直接用上显卡：NVIDIA Container Toolkit 的安装与原理、docker run 与 Compose 两种调用 GPU 的写法、nvidia-smi 验证，以及驱动版本、运行时配置这几个最常见的坑。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;上一篇 &lt;a href=&quot;/posts/linux-docker-compose/&quot;&gt;《如何在Linux部署Docker&amp;amp;Compose》&lt;/a&gt; 把 Docker 的地基打好了，容器跑起来没问题。但只要你的业务沾上 AI 推理、视频转码、生图，就会撞上一个新问题：&lt;strong&gt;容器里默认根本看不见显卡&lt;/strong&gt;。宿主机上明明插着一张 NVIDIA GPU，&lt;code&gt;nvidia-smi&lt;/code&gt; 在宿主机跑得好好的，一进容器就报找不到设备。&lt;/p&gt;
&lt;p&gt;这篇就把这条路彻底打通：先讲清容器为什么默认用不了 GPU、NVIDIA Container Toolkit 在中间扮演什么角色，再一步步走完安装、&lt;code&gt;docker run&lt;/code&gt; 与 Compose 两种调用写法、环境变量调优，最后是排障。走完这一篇，你的容器就能像宿主机进程一样直接调用显卡了。&lt;/p&gt;
&lt;h2&gt;先搞清楚：容器为什么默认用不了 GPU&lt;/h2&gt;
&lt;p&gt;普通容器能直接用的硬件其实非常有限：CPU、内存、磁盘、网络，这些都是内核原生支持隔离和分配的。但 GPU 不一样，它没有进 Linux 内核的统一抽象层，应用程序要通过 NVIDIA 的&lt;strong&gt;闭源驱动&lt;/strong&gt;和一整套用户态库（CUDA 运行库、&lt;code&gt;libnvidia-ml&lt;/code&gt; 等）才能跟显卡对话。&lt;/p&gt;
&lt;p&gt;容器与宿主机共享同一个内核，但文件系统是隔离的。容器镜像里通常只有应用自己带的那点东西，既没有宿主机的驱动库，也没有 &lt;code&gt;/dev/nvidia0&lt;/code&gt;、&lt;code&gt;/dev/nvidiactl&lt;/code&gt; 这些设备节点的访问通道。所以默认状态下，容器里的程序去找显卡，只会一无所获。&lt;/p&gt;
&lt;p&gt;NVIDIA Container Toolkit 解决的就是这个问题。它的工作方式可以概括为三件事：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;环节&lt;/th&gt;
&lt;th&gt;做了什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;运行时钩子&lt;/td&gt;
&lt;td&gt;容器启动前，&lt;code&gt;nvidia-container-runtime&lt;/code&gt; 拦截创建流程，在容器真正跑起来之前先做注入&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;设备注入&lt;/td&gt;
&lt;td&gt;把 &lt;code&gt;/dev/nvidia0&lt;/code&gt;、&lt;code&gt;/dev/nvidia-uvm&lt;/code&gt; 等设备节点映射进容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;驱动库注入&lt;/td&gt;
&lt;td&gt;把&lt;strong&gt;宿主机上&lt;/strong&gt;的驱动用户态库（如 &lt;code&gt;libcuda.so&lt;/code&gt;、&lt;code&gt;libnvidia-ml.so&lt;/code&gt;）挂载进容器&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这里有个关键认知，整篇的坑基本都从它派生出来：&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;驱动永远在宿主机，容器里只需要 CUDA 运行库。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;也就是说，你&lt;strong&gt;不需要&lt;/strong&gt;、也&lt;strong&gt;不应该&lt;/strong&gt;在容器镜像里装 NVIDIA 驱动。镜像里只需要带上应用依赖的 CUDA 运行库（比如 PyTorch 镜像自带的 CUDA 版本），真正的驱动由 Toolkit 在运行时从宿主机注入。这也是为什么官方 CUDA 镜像（如 &lt;code&gt;nvidia/cuda:12.4.1-base-ubuntu22.04&lt;/code&gt;）体积不大、且能在不同驱动的机器上跑——前提是宿主机驱动足够新，这就是下一节的版本对应关系。&lt;/p&gt;
&lt;h2&gt;版本对应关系：驱动决定 CUDA 上限&lt;/h2&gt;
&lt;p&gt;注入机制带来一条硬性约束：&lt;strong&gt;容器里用的 CUDA 版本，不能高于宿主机驱动支持的 CUDA 上限&lt;/strong&gt;。驱动太旧、镜像太新，容器一调用 CUDA 就会报错（最典型的就是后面排障里要讲的 Driver/library version mismatch）。&lt;/p&gt;
&lt;p&gt;宿主机驱动与可支持的最高 CUDA 版本大致对应如下（Linux x86_64）：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;宿主机驱动版本&lt;/th&gt;
&lt;th&gt;最高支持的 CUDA 版本&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;470.xx（Kepler 末代）&lt;/td&gt;
&lt;td&gt;CUDA 11.4&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;525.xx&lt;/td&gt;
&lt;td&gt;CUDA 12.0&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;535.xx&lt;/td&gt;
&lt;td&gt;CUDA 12.2&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;550.xx&lt;/td&gt;
&lt;td&gt;CUDA 12.4&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;560.xx&lt;/td&gt;
&lt;td&gt;CUDA 12.6&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;570.xx&lt;/td&gt;
&lt;td&gt;CUDA 12.8&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;580.xx&lt;/td&gt;
&lt;td&gt;CUDA 13.0&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;不用死记这张表，装之前在&lt;strong&gt;宿主机&lt;/strong&gt;上跑一次 &lt;code&gt;nvidia-smi&lt;/code&gt; 就能看到答案：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;nvidia-smi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出右上角有一行 &lt;code&gt;CUDA Version: 12.4&lt;/code&gt;，注意它的含义是「这台机器的驱动最高支持到 CUDA 12.4」，不是你装了 CUDA 12.4。选容器镜像时，镜像标签里的 CUDA 版本&lt;strong&gt;小于等于&lt;/strong&gt;这个数就安全；大于它，先升级宿主机驱动再说。&lt;/p&gt;
&lt;p&gt;:::warning
宿主机还没装 NVIDIA 驱动的话，先把驱动装好再谈容器。Debian/Ubuntu 上推荐用发行版仓库的驱动包（如 &lt;code&gt;nvidia-driver&lt;/code&gt; 元包或 Software &amp;amp; Updates 里的专有驱动），不要去官网下载 .run 文件手动装——手动装的驱动每次内核升级都要重装一遍，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;内核一升级驱动就失效&amp;lt;/span&amp;gt;是新手最常见的翻车点。驱动装完务必重启一次，并在宿主机确认 &lt;code&gt;nvidia-smi&lt;/code&gt; 能正常输出显卡信息，再继续下面的步骤。
:::&lt;/p&gt;
&lt;h2&gt;安装 NVIDIA Container Toolkit&lt;/h2&gt;
&lt;p&gt;以下流程适用于 Debian / Ubuntu，装的是 NVIDIA 官方仓库的 &lt;code&gt;nvidia-container-toolkit&lt;/code&gt; 包。前置条件：宿主机驱动已装好、&lt;code&gt;nvidia-smi&lt;/code&gt; 正常、Docker 已按第一篇的方法装好。&lt;/p&gt;
&lt;h3&gt;第一步：添加官方仓库&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed &apos;s#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g&apos; | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;验证点：&lt;code&gt;/etc/apt/sources.list.d/nvidia-container-toolkit.list&lt;/code&gt; 文件存在，内容是一行带 &lt;code&gt;signed-by&lt;/code&gt; 的 deb 源地址。&lt;/p&gt;
&lt;h3&gt;第二步：安装软件包&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;验证点：装完后这两个命令能找到就对了：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;which nvidia-ctk nvidia-container-runtime
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第三步：把 NVIDIA 运行时注册进 Docker&lt;/h3&gt;
&lt;p&gt;这是最容易漏掉、漏掉就必报错的一步。用官方的 &lt;code&gt;nvidia-ctk&lt;/code&gt; 工具自动改 Docker 的配置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo nvidia-ctk runtime configure --runtime=docker
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它会往 &lt;code&gt;/etc/docker/daemon.json&lt;/code&gt; 里写入 NVIDIA 运行时的定义。可以打开确认一眼：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cat /etc/docker/daemon.json
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;应该能看到类似内容（你原有的其他配置会被保留合并）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
    &quot;runtimes&quot;: {
        &quot;nvidia&quot;: {
            &quot;args&quot;: [],
            &quot;path&quot;: &quot;nvidia-container-runtime&quot;
        }
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;nvidia-ctk runtime configure&lt;/code&gt; 是&lt;strong&gt;覆盖式合并&lt;/strong&gt;：它会重写 &lt;code&gt;daemon.json&lt;/code&gt; 里 &lt;code&gt;runtimes&lt;/code&gt; 这一段。如果你之前手写过其他运行时配置，改完要通读一遍整个文件再重启。另外，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要再手工往 daemon.json 里加已经过时的 default-runtime 写法&amp;lt;/span&amp;gt;——老教程里常见的 &lt;code&gt;&quot;default-runtime&quot;: &quot;nvidia&quot;&lt;/code&gt; 是 nvidia-docker 时代的产物，现在既没必要也会让所有容器都强行走 GPU 注入，普通容器反而容易出问题。
:::&lt;/p&gt;
&lt;h3&gt;第四步：重启 Docker 使配置生效&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl restart docker
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;验证点：&lt;code&gt;docker info | grep -i runtime&lt;/code&gt; 的输出里能看到 &lt;code&gt;nvidia&lt;/code&gt; 字样，说明运行时注册成功。注意重启 Docker 会重启所有设置了重启策略的容器，生产机上请挑低峰期操作。&lt;/p&gt;
&lt;h2&gt;docker run 调用 GPU&lt;/h2&gt;
&lt;p&gt;配置生效后，给 &lt;code&gt;docker run&lt;/code&gt; 加一个 &lt;code&gt;--gpus&lt;/code&gt; 参数就能把显卡交给容器。&lt;/p&gt;
&lt;h3&gt;全部显卡都给容器&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意选镜像版本时对照第二节的表：我这里宿主机驱动支持到 CUDA 12.4，所以选了 &lt;code&gt;12.4.1&lt;/code&gt; 的镜像。如果一切正常，输出就是熟悉的 &lt;code&gt;nvidia-smi&lt;/code&gt; 表格：显卡型号、驱动版本、显存占用（0MiB）整整齐齐——&lt;strong&gt;在容器里看到这张表，就等于整条链路全部打通了&lt;/strong&gt;。这个命令建议你装完 Toolkit 后第一时间跑，它是最快的端到端验证。&lt;/p&gt;
&lt;h3&gt;只给指定的卡&lt;/h3&gt;
&lt;p&gt;多卡机器（或者只想留一张卡给宿主机上的其他任务）可以按编号分配，注意引号不能省：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run --rm --gpus &apos;&quot;device=0&quot;&apos; nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;多张一起给用逗号：&lt;code&gt;--gpus &apos;&quot;device=0,1&quot;&apos;&lt;/code&gt;。编号就是宿主机 &lt;code&gt;nvidia-smi&lt;/code&gt; 里左边的 GPU 序号（0 起）。容器里看到的显卡会被重新从 0 编号，不用奇怪。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;--gpus&lt;/code&gt; 还支持按数量给，比如 &lt;code&gt;--gpus 1&lt;/code&gt; 表示随便分配一张。生产环境更推荐写死 &lt;code&gt;device=&lt;/code&gt; 编号，行为可预期，排障时也清楚哪张卡归谁。&lt;/p&gt;
&lt;h3&gt;一个最小的实用例子&lt;/h3&gt;
&lt;p&gt;光看 &lt;code&gt;nvidia-smi&lt;/code&gt; 不过瘾的话，可以跑一个真正的计算镜像确认 CUDA 能算：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run --rm --gpus all nvidia/cuda:12.4.1-sample-ubuntu22.04 vectorAdd
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;（示例镜像的标签各 CUDA 版本略有差异，拉不到时换 &lt;code&gt;nvidia/cuda:12.4.1-devel-ubuntu22.04&lt;/code&gt; 里自带的示例同理。）输出最后出现 &lt;code&gt;Test PASSED&lt;/code&gt; 就说明不只是「看得见」，而是真的能算。&lt;/p&gt;
&lt;h2&gt;Compose 写法：把 GPU 写进编排文件&lt;/h2&gt;
&lt;p&gt;实际项目都是用 Compose 管理的，GPU 分配写在服务的 &lt;code&gt;deploy.resources.reservations.devices&lt;/code&gt; 段里：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    ports:
      - &quot;11434:11434&quot;
    volumes:
      - ./ollama-data:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个字段逐个说清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;driver: nvidia&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;用哪个设备的驱动框架，NVIDIA 显卡固定写 nvidia&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;count: all&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;分配几张卡，&lt;code&gt;all&lt;/code&gt; 是全部，也可以写数字如 &lt;code&gt;count: 1&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;device_ids: [&apos;0&apos;]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;指定卡编号，与 &lt;code&gt;count&lt;/code&gt; 二选一，不能同时写&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;capabilities: [gpu]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;声明需要的设备能力，GPU 计算固定要带 &lt;code&gt;gpu&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;只给一张指定卡的写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: [&apos;0&apos;]
              capabilities: [gpu]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
网上很多老文章在 Compose 里写 &lt;code&gt;runtime: nvidia&lt;/code&gt;，那是 Docker Compose v1 加 nvidia-docker2 时代的写法。现在 Compose v2 已经&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不再认 runtime 字段指定 GPU&amp;lt;/span&amp;gt;，照抄老配置的结果是显卡压根没分配进去，程序只能用 CPU 跑，还不报错、特别难查。认准 &lt;code&gt;deploy.resources.reservations.devices&lt;/code&gt; 这一套新写法。顺带说一句：&lt;code&gt;deploy&lt;/code&gt; 段在 Swarm 里是编排参数，但在普通 &lt;code&gt;docker compose up&lt;/code&gt; 下，&lt;code&gt;resources.reservations.devices&lt;/code&gt; 这部分是生效的，不用担心被忽略。
:::&lt;/p&gt;
&lt;p&gt;改完配置照常 &lt;code&gt;docker compose up -d&lt;/code&gt;，然后进容器验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose exec ollama nvidia-smi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;有些精简镜像里没有 &lt;code&gt;nvidia-smi&lt;/code&gt; 这个命令，可以换成看设备节点：&lt;code&gt;docker compose exec ollama ls /dev/nvidia*&lt;/code&gt;，能列出 &lt;code&gt;nvidia0&lt;/code&gt;、&lt;code&gt;nvidiactl&lt;/code&gt; 等节点即说明注入成功。&lt;/p&gt;
&lt;h2&gt;环境变量精调&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;--gpus&lt;/code&gt; 和 Compose 的 devices 段决定「给不给、给哪张」，还有两个环境变量决定「给了之后怎么用」，出问题时经常要动它们：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;环境变量&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;常用取值&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;NVIDIA_VISIBLE_DEVICES&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;限定容器能看到哪几张卡&lt;/td&gt;
&lt;td&gt;&lt;code&gt;all&lt;/code&gt;（默认）、&lt;code&gt;0&lt;/code&gt;、&lt;code&gt;0,1&lt;/code&gt;、&lt;code&gt;none&lt;/code&gt;（不给卡）、&lt;code&gt;void&lt;/code&gt;（给驱动但不给设备）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;NVIDIA_DRIVER_CAPABILITIES&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;开放驱动的哪些能力组&lt;/td&gt;
&lt;td&gt;&lt;code&gt;compute&lt;/code&gt;、&lt;code&gt;utility&lt;/code&gt;、&lt;code&gt;graphics&lt;/code&gt;、&lt;code&gt;video&lt;/code&gt;、&lt;code&gt;display&lt;/code&gt;，多个用逗号连&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;NVIDIA_DRIVER_CAPABILITIES&lt;/code&gt; 的能力项各管一摊事，按需开，别无脑全开：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;能力项&lt;/th&gt;
&lt;th&gt;管什么&lt;/th&gt;
&lt;th&gt;谁需要它&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;compute&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;CUDA 计算、cuDNN 等计算库&lt;/td&gt;
&lt;td&gt;所有 AI / 科学计算场景，必备&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;utility&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;nvidia-smi&lt;/code&gt; 等管理查询工具&lt;/td&gt;
&lt;td&gt;想在容器里查显卡状态时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;video&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;NVENC / NVDEC 硬件编解码&lt;/td&gt;
&lt;td&gt;FFmpeg 转码、Jellyfin 等媒体服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;graphics&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;OpenGL / Vulkan 图形渲染&lt;/td&gt;
&lt;td&gt;图形渲染、部分生图与游戏串流场景&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;display&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;显示输出相关库&lt;/td&gt;
&lt;td&gt;容器直接接显示器输出时，服务器场景基本用不上&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;举个例子，一个纯转码的 FFmpeg 容器这样写就够了，计算能力也可以顺手带上：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=compute,video,utility
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;而跑大模型推理的容器通常只需要 &lt;code&gt;compute,utility&lt;/code&gt;。能力开得越少，注入的库越少，镜像行为越干净，排障面也越小。默认值是 &lt;code&gt;compute,utility&lt;/code&gt;，所以很多镜像什么都不写也能跑——因为它们正好只需要这两项；一旦你的场景涉及转码而又没开 &lt;code&gt;video&lt;/code&gt;，就会出现「显卡看得见但 NVENC 用不了」的怪问题，先查这里。&lt;/p&gt;
&lt;h2&gt;典型场景速配&lt;/h2&gt;
&lt;p&gt;把上面的写法套到常见服务上，基本都是十分钟的事：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;AI 推理（Ollama 等）&lt;/strong&gt;：用上面 Compose 例子的结构，&lt;code&gt;count: all&lt;/code&gt; ＋ 默认能力即可。Ollama 官方镜像自带 CUDA 运行库，GPU 分配进去后日志里会出现 &lt;code&gt;inference compute&lt;/code&gt; 并识别出显卡型号；如果日志显示走的是 CPU，九成是 devices 段没生效或驱动版本不够。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;硬件转码（Jellyfin / FFmpeg）&lt;/strong&gt;：关键是给足 &lt;code&gt;NVIDIA_DRIVER_CAPABILITIES=compute,video,utility&lt;/code&gt;，然后在 Jellyfin 后台的播放设置里把硬件加速选成 NVIDIA NVENC。FFmpeg 场景用带 CUDA 的镜像，编码时指定 &lt;code&gt;-hwaccel cuda -c:v h264_nvenc&lt;/code&gt; 这类参数。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;生图（Stable Diffusion 类）&lt;/strong&gt;：这类镜像基本基于 PyTorch，镜像自带 CUDA，宿主机只管驱动够新。分配写法同推理场景，另外显存是硬约束，&lt;code&gt;nvidia-smi&lt;/code&gt; 先确认显存够不够模型用，不够就换小模型或开低显存模式，容器化解决不了显存不足。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;运维补充：盯住显存占用&lt;/h2&gt;
&lt;p&gt;GPU 分给容器之后，日常最常问的问题是「哪个容器吃了多少显存」。先说一个反直觉的事实：&lt;code&gt;docker stats&lt;/code&gt; &lt;strong&gt;不显示 GPU 数据&lt;/strong&gt;，它只有 CPU、内存、网络和磁盘四类。看 GPU 还是得回到宿主机的 &lt;code&gt;nvidia-smi&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;nvidia-smi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;进程列表里显示的是容器内进程在宿主机上的 PID 和显存占用，把 PID 拿去 &lt;code&gt;docker top &amp;lt;容器名&amp;gt;&lt;/code&gt; 或者 &lt;code&gt;docker inspect&lt;/code&gt; 里对照，就能定位到具体是哪个容器。想持续盯着看可以用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;nvidia-smi dmon -s u
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它会滚动输出每张卡的算力利用率、显存利用率和功耗，排查「某个服务把卡占满、其他服务排队」时很直观。&lt;/p&gt;
&lt;p&gt;还有一个经常被问的点：&lt;strong&gt;能不能像限制内存那样，给某个容器限死显存上限？&lt;/strong&gt; 标准 Docker 加 Toolkit 的组合里没有这个原生参数——GPU 的分配粒度就是「整张卡给或不给」，&lt;code&gt;--gpus&lt;/code&gt; 只能选卡和选数量。真要做显存级切分，得上数据中心卡才支持的 MIG（Multi-Instance GPU，把一张物理卡切成多个硬件隔离的实例，再用 &lt;code&gt;device&lt;/code&gt; 指定 MIG 实例分配），或者在应用层自己控制（比如 PyTorch 里设 &lt;code&gt;per_process_gpu_memory_fraction&lt;/code&gt;）。普通单卡家用和中小服务器场景，按服务分卡、错峰使用就够了，不要在这上面钻牛角尖。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;h3&gt;docker: Error response from daemon: could not select device driver&lt;/h3&gt;
&lt;p&gt;完整报错一般是 &lt;code&gt;could not select device driver &quot;nvidia&quot; with capabilities: [[gpu]]&lt;/code&gt;。这是 Toolkit 链路没通的标志性错误，按顺序查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;宿主机 &lt;code&gt;nvidia-smi&lt;/code&gt; 是否正常——宿主机都不行，容器免谈；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;nvidia-container-toolkit&lt;/code&gt; 装了没有：&lt;code&gt;dpkg -l | grep nvidia-container-toolkit&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;nvidia-ctk runtime configure --runtime=docker&lt;/code&gt; 执行过没有，&lt;code&gt;daemon.json&lt;/code&gt; 里有没有 &lt;code&gt;runtimes.nvidia&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;配置之后&lt;strong&gt;重启过 Docker 没有&lt;/strong&gt;——改完配置不重启是最常见的乌龙；&lt;/li&gt;
&lt;li&gt;用的还是不是老写法：&lt;code&gt;docker run&lt;/code&gt; 漏了 &lt;code&gt;--gpus&lt;/code&gt;，或 Compose 还在写 &lt;code&gt;runtime: nvidia&lt;/code&gt;。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;容器里 nvidia-smi 报 Driver/library version mismatch&lt;/h3&gt;
&lt;p&gt;全称 &lt;code&gt;Failed to initialize NVML: Driver/library version mismatch&lt;/code&gt;。意思是容器里被注入的用户态驱动库版本和宿主机内核驱动对不上。常见诱因：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;宿主机刚升级了驱动但&lt;strong&gt;没重启&lt;/strong&gt;，内核里跑的还是旧驱动模块，而磁盘上的库已经是新版——重启宿主机即可；&lt;/li&gt;
&lt;li&gt;容器镜像的 CUDA 版本超过了驱动上限（回到第二节对照表，换低版本镜像或升级驱动）；&lt;/li&gt;
&lt;li&gt;宿主机驱动是 .run 文件手动装的，发行版包又装了一份，库文件混杂——清理成只保留一种安装方式。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;重启 Docker 后 GPU 丢失&lt;/h3&gt;
&lt;p&gt;之前好好的，一次 &lt;code&gt;systemctl restart docker&lt;/code&gt; 或系统更新后 &lt;code&gt;--gpus&lt;/code&gt; 又报错。优先怀疑 &lt;code&gt;daemon.json&lt;/code&gt; 被改动：某些工具或手工编辑会把 &lt;code&gt;runtimes&lt;/code&gt; 段冲掉。重新执行一遍：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;最后一条验证命令能过，就说明链路恢复。&lt;/p&gt;
&lt;h3&gt;程序报 CUDA error: no device / 容器里看不到卡&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;nvidia-smi&lt;/code&gt; 在容器里能跑、但应用说找不到 GPU，或者反过来应用能跑但你想确认它到底用了哪张卡，先查环境变量：是不是某个环节把 &lt;code&gt;NVIDIA_VISIBLE_DEVICES&lt;/code&gt; 设成了 &lt;code&gt;none&lt;/code&gt; 或 &lt;code&gt;void&lt;/code&gt;（有些基础镜像或上层编排会带这个变量），再查 Compose 的 devices 段 &lt;code&gt;count&lt;/code&gt; 是否写了 0。把变量显式写成 &lt;code&gt;NVIDIA_VISIBLE_DEVICES=all&lt;/code&gt; 或具体编号覆盖掉，是最快的验证办法。&lt;/p&gt;
&lt;h3&gt;设备节点与权限检查&lt;/h3&gt;
&lt;p&gt;怀疑注入本身没发生时，直接看设备节点。宿主机上应该有这些文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ls -l /dev/nvidia*
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;能看到 &lt;code&gt;nvidia0&lt;/code&gt;（每张卡一个）、&lt;code&gt;nvidiactl&lt;/code&gt;、&lt;code&gt;nvidia-uvm&lt;/code&gt;、&lt;code&gt;nvidia-modeset&lt;/code&gt; 才算驱动加载正常；连宿主机都没有这些节点，是驱动层的问题，先修驱动。再看容器里：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run --rm --gpus all --entrypoint ls nvidia/cuda:12.4.1-base-ubuntu22.04 -l /dev/nvidia*
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;容器里缺节点而宿主机有，就是 Toolkit 注入环节的问题，回到前两条排查。&lt;/p&gt;
&lt;p&gt;:::warning
不要用给容器加 &lt;code&gt;--privileged&lt;/code&gt; 或者把 &lt;code&gt;/dev&lt;/code&gt; 整个挂进去的方式来「解决」GPU 不可见的问题。这样做等于&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把宿主机的全部设备权限都交给容器&amp;lt;/span&amp;gt;，安全边界荡然无存，而且掩盖了真正的配置错误。Toolkit 的注入是精准映射，装好配好之后根本不需要特权模式。
:::&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;容器用不了 GPU 是因为驱动和设备节点被隔离在外，NVIDIA Container Toolkit 在容器启动时把宿主机的驱动库和设备精准注入进来；&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;容器镜像只带 CUDA 运行库，永远不装驱动&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;li&gt;版本红线只有一条：容器镜像的 CUDA 版本 ≤ 宿主机 &lt;code&gt;nvidia-smi&lt;/code&gt; 右上角显示的 CUDA 上限。&lt;/li&gt;
&lt;li&gt;安装四步：加官方仓库 → 装 &lt;code&gt;nvidia-container-toolkit&lt;/code&gt; → &lt;code&gt;nvidia-ctk runtime configure --runtime=docker&lt;/code&gt; → 重启 Docker，缺一不可。&lt;/li&gt;
&lt;li&gt;调用写法：&lt;code&gt;docker run&lt;/code&gt; 用 &lt;code&gt;--gpus all&lt;/code&gt; 或 &lt;code&gt;--gpus &apos;&quot;device=0&quot;&apos;&lt;/code&gt;；Compose 用 &lt;code&gt;deploy.resources.reservations.devices&lt;/code&gt;，别再抄 &lt;code&gt;runtime: nvidia&lt;/code&gt; 的老写法。&lt;/li&gt;
&lt;li&gt;精调靠两个环境变量：&lt;code&gt;NVIDIA_VISIBLE_DEVICES&lt;/code&gt; 管给哪张卡，&lt;code&gt;NVIDIA_DRIVER_CAPABILITIES&lt;/code&gt; 管开哪些能力，转码记得开 &lt;code&gt;video&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;排障先分层：宿主机 &lt;code&gt;nvidia-smi&lt;/code&gt; → Toolkit 与 &lt;code&gt;daemon.json&lt;/code&gt; → 容器内验证，一层层缩小范围，别一上来就重装。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;链路打通之后，GPU 在 Docker 里就和 CPU、内存一样成了可编排的资源：想给哪个服务、给几张卡、什么时候收回，都是一行配置的事。&lt;/p&gt;
</content:encoded></item><item><title>Docker 日志管理：轮转、限制与集中查看</title><link>https://www.anexns.cloudns.org/posts/docker-logging/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-logging/</guid><description>管好容器日志：docker logs 全参数用法、json-file 日志轮转配置（全局 daemon.json 与单容器两种）、日志把磁盘写满的应急处理、Dozzle 网页端集中看日志的部署与安全加固。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;容器跑起来之后，日志就是你的眼睛：服务为什么挂了、请求为什么报错、程序到底有没有按预期在跑，全靠日志说话。但日志也是个双刃剑——不管它，它能悄悄把磁盘写满，让整台机器的服务一起陪葬；管得太死，真出事的时候又发现什么都没留下。这篇把 Docker 日志从「怎么看」到「怎么管」一次讲透：先讲 &lt;code&gt;docker logs&lt;/code&gt; 的全参数用法，再讲日志到底存在哪、json-file 驱动是怎么回事，然后是轮转配置的两种写法（全局 daemon.json 和单容器 compose），最后是磁盘写满的应急处理和用 Dozzle 在网页上集中看日志的部署与安全加固。&lt;/p&gt;
&lt;p&gt;如果你还没装好 Docker，先看 &lt;a href=&quot;/posts/linux-docker-compose/&quot;&gt;《如何在Linux部署Docker&amp;amp;Compose》&lt;/a&gt;；容器已经在自动更新的，也可以配合 &lt;a href=&quot;/posts/linux-docker-auto-update/&quot;&gt;《如何在Linux自动更新Docker容器》&lt;/a&gt; 一起看——更新后容器起不来时，第一件事就是查日志。&lt;/p&gt;
&lt;h2&gt;docker logs 全参数用法&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;docker logs&lt;/code&gt; 是最常用的查日志命令，但很多人只会最基础的 &lt;code&gt;docker logs 容器名&lt;/code&gt;，把全部历史日志一股脑刷屏。其实它有一整套参数，组合好了定位问题非常快。&lt;/p&gt;
&lt;h3&gt;基础与实时跟踪：-f&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 查看容器全部日志（标准输出 + 标准错误）
docker logs nginx

# 实时跟踪新日志，类似 tail -f，Ctrl+C 退出（不会停掉容器）
docker logs -f nginx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;-f&lt;/code&gt;（&lt;code&gt;--follow&lt;/code&gt;）是最常用的参数：先把已有日志打出来，然后挂着等新日志。调试「请求进来之后发生了什么」时，先开一个终端 &lt;code&gt;docker logs -f&lt;/code&gt; 挂着，再去发请求，日志实时滚动，问题一目了然。&lt;/p&gt;
&lt;h3&gt;只看最后 N 行：--tail&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 只看最后 100 行
docker logs --tail 100 nginx

# 和 -f 组合：先显示最后 50 行，再实时跟踪
docker logs -f --tail 50 nginx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;容器跑了几个月，日志可能有几十万行，直接 &lt;code&gt;docker logs&lt;/code&gt; 会刷屏半天。养成习惯：先 &lt;code&gt;--tail&lt;/code&gt; 看尾巴，确认大概是什么问题，再决定要不要翻历史。&lt;/p&gt;
&lt;h3&gt;按时间范围查：--since / --until&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 看最近 10 分钟的日志
docker logs --since 10m nginx

# 看最近 1 小时的日志
docker logs --since 1h nginx

# 看某个时间点之后的日志（RFC3339 格式）
docker logs --since 2026-11-15T08:00:00 nginx

# 两个组合：看 08:00 到 09:00 这一小时的日志
docker logs --since 2026-11-15T08:00:00 --until 2026-11-15T09:00:00 nginx

# 看某个时间点之前的日志
docker logs --until 30m nginx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--since&lt;/code&gt; / &lt;code&gt;--until&lt;/code&gt; 接受两种格式：相对时长（&lt;code&gt;10m&lt;/code&gt;、&lt;code&gt;1h&lt;/code&gt;、&lt;code&gt;24h&lt;/code&gt;）和绝对时间戳（RFC3339，如 &lt;code&gt;2026-11-15T08:00:00&lt;/code&gt;）。「用户说昨晚 9 点左右网站打不开」这种场景，&lt;code&gt;--since&lt;/code&gt; + &lt;code&gt;--until&lt;/code&gt; 把时间窗一卡，日志量立刻从几十万行缩到几百行。&lt;/p&gt;
&lt;h3&gt;显示时间戳：-t&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker logs -t --tail 20 nginx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出会变成这样，每行前面多出日志产生的时间：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;2026-11-15T00:12:31.123456789Z 192.168.1.10 - - &quot;GET / HTTP/1.1&quot; 200 612
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;-t&lt;/code&gt;（&lt;code&gt;--timestamps&lt;/code&gt;）显示的是日志条目的时间戳（UTC 时间，注意换算时区）。应用本身日志不带时间、或者想和别的系统日志对时间线时，这个参数非常有用。&lt;/p&gt;
&lt;h3&gt;显示驱动附加信息：--details&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker logs --details nginx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--details&lt;/code&gt; 会把日志驱动附加的额外信息（attributes）一并显示出来，比如通过 &lt;code&gt;docker run --log-opt labels=xxx&lt;/code&gt; 打上的标签信息。日常用得不多，排查「这条日志到底从哪个环境来的」时能派上用场。&lt;/p&gt;
&lt;h3&gt;组合场景速查&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;刚部署完，实时盯启动过程&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker logs -f --tail 50 容器名&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;服务突然挂了，看死前发生了什么&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker logs --tail 200 容器名&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;用户报某个时间段出问题&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker logs --since 时间 --until 时间 容器名&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;日志太多，先粗筛关键词&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker logs --since 1h 容器名 2&amp;gt;&amp;amp;1 | grep -i error&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;把日志存下来慢慢看&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker logs --since 24h 容器名 &amp;gt; app.log 2&amp;gt;&amp;amp;1&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
&lt;code&gt;docker logs&lt;/code&gt; 看到的是容器的&lt;strong&gt;标准输出（stdout）和标准错误（stderr）&lt;/strong&gt;。如果应用把日志写进了容器内部的文件（比如 &lt;code&gt;/var/log/app.log&lt;/code&gt;），&lt;code&gt;docker logs&lt;/code&gt; 是看不到的——这也是后面排障小节里最常见的「没输出」原因。
:::&lt;/p&gt;
&lt;h3&gt;进阶技巧：过滤、统计与导出&lt;/h3&gt;
&lt;p&gt;参数之外，再配合 shell 的文本工具，&lt;code&gt;docker logs&lt;/code&gt; 还能玩出不少花样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 只看标准错误（1 是 stdout，2 是 stderr；docker logs 默认两者都输出）
docker logs 容器名 2&amp;gt;/dev/null   # 只要标准输出
docker logs 容器名 1&amp;gt;/dev/null   # 只要标准错误

# 统计最近一小时 ERROR 出现了多少次
docker logs --since 1h 容器名 2&amp;gt;&amp;amp;1 | grep -c &quot;ERROR&quot;

# 按状态码粗筛访问日志（以 Nginx 为例，看所有 5xx）
docker logs --since 24h nginx 2&amp;gt;&amp;amp;1 | grep &apos;&quot; 5&apos;

# 导出某天的完整日志留档
docker logs --since 2026-11-14T00:00:00 --until 2026-11-14T23:59:59 容器名 &amp;gt; nginx-1114.log 2&amp;gt;&amp;amp;1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里有个容易踩的小坑：&lt;code&gt;docker logs&lt;/code&gt; 输出时，容器写到 stderr 的内容在终端里也是走 stderr 通道的，所以管道给 &lt;code&gt;grep&lt;/code&gt; 之前记得加 &lt;code&gt;2&amp;gt;&amp;amp;1&lt;/code&gt;，否则错误日志会漏掉一大半。很多应用恰恰是把正常日志写 stdout、把错误日志写 stderr，只过滤一半等于白查。&lt;/p&gt;
&lt;h2&gt;容器日志到底存在哪&lt;/h2&gt;
&lt;p&gt;理解日志的存放位置，才能理解轮转和磁盘占用的问题出在哪。&lt;/p&gt;
&lt;p&gt;在默认的 &lt;code&gt;json-file&lt;/code&gt; 日志驱动下，每个容器的日志都存在宿主机上一个固定的文件里：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/var/lib/docker/containers/&amp;lt;容器ID&amp;gt;/&amp;lt;容器ID&amp;gt;-json.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;查看某个容器日志文件的实际大小：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 先拿到容器完整 ID
docker inspect -f &apos;{{.Id}}&apos; nginx

# 再看对应日志文件
ls -lh /var/lib/docker/containers/&amp;lt;容器ID&amp;gt;/&amp;lt;容器ID&amp;gt;-json.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;也可以一条命令直接定位：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker inspect -f &apos;{{.LogPath}}&apos; nginx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;json-file&lt;/code&gt; 驱动的工作原理很朴素：Docker 守护进程把容器的 stdout/stderr 一行一行包装成 JSON（每行包含日志内容、来源是 stdout 还是 stderr、时间戳），追加写进这个文件。&lt;code&gt;docker logs&lt;/code&gt; 本质上就是把这个文件读出来、拆掉 JSON 包装再打印。&lt;/p&gt;
&lt;p&gt;朴素的代价是：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;默认不做任何轮转&lt;/strong&gt;&amp;lt;/span&amp;gt;。只要容器还在输出，这个文件就只会变大，永远不会自己变小。一个话痨容器（比如开了 debug 级别日志的服务）几天写出几十 GB 日志，是非常真实的事故——这正是下一节要解决的问题。&lt;/p&gt;
&lt;h2&gt;日志轮转：全局配置 daemon.json&lt;/h2&gt;
&lt;p&gt;给所有容器统一设置日志上限，改的是 Docker 守护进程的配置文件 &lt;code&gt;/etc/docker/daemon.json&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;log-driver&quot;: &quot;json-file&quot;,
  &quot;log-opts&quot;: {
    &quot;max-size&quot;: &quot;20m&quot;,
    &quot;max-file&quot;: &quot;3&quot;
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个参数的含义：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;max-size: 20m&lt;/code&gt;：单个日志文件最大 20MB，写满了就滚动到下一个文件；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;max-file: 3&lt;/code&gt;：最多保留 3 个文件（当前文件 + 2 个历史文件）。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;也就是说每个容器最多占用约 60MB 磁盘，写得再多也封顶，老日志自动丢弃。&lt;/p&gt;
&lt;p&gt;改完之后要重启 Docker 守护进程才生效：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl restart docker
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;验证配置是否被守护进程接受（改错 JSON 语法会导致 Docker 起不来，重启后先确认服务状态）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl status docker
docker info | grep -A2 &quot;Logging Driver&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;strong&gt;最关键的坑：daemon.json 的日志配置&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;只对「新建的容器」生效&amp;lt;/span&amp;gt;。&lt;/strong&gt; 已经在跑的老容器，创建时用的是旧配置，重启 Docker、甚至重启容器本身都不会改变它的日志设置——必须把容器删除重建（&lt;code&gt;docker compose up -d --force-recreate&lt;/code&gt; 或先 &lt;code&gt;docker rm&lt;/code&gt; 再重新创建），新配置才套得上。所以改完 daemon.json 别急着以为万事大吉，逐个确认重要容器的实际配置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker inspect -f &apos;{{.HostConfig.LogConfig}}&apos; 容器名
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出里能看到该容器实际生效的 &lt;code&gt;max-size&lt;/code&gt; 和 &lt;code&gt;max-file&lt;/code&gt;，没有就说明它还是无限制状态。另外提醒一句：&lt;code&gt;systemctl restart docker&lt;/code&gt; 会影响所有容器，没有配 &lt;code&gt;live-restore&lt;/code&gt; 的话容器会被全部重启，请挑低峰期操作。
:::&lt;/p&gt;
&lt;h2&gt;日志轮转：单容器配置（Compose）&lt;/h2&gt;
&lt;p&gt;全局配置管所有容器，但有些容器你想区别对待：核心服务想多留点日志（max-file 给大些），一次性的小工具干脆少留。这时在 &lt;code&gt;docker-compose.yml&lt;/code&gt; 里给单个服务写 &lt;code&gt;logging&lt;/code&gt; 段，它会&lt;strong&gt;覆盖&lt;/strong&gt;全局 daemon.json 的设置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    logging:
      driver: json-file
      options:
        max-size: &quot;50m&quot;
        max-file: &quot;5&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这个服务就会按单文件 50MB、保留 5 个来轮转，总上限约 250MB，不受全局 20m×3 的影响。&lt;/p&gt;
&lt;p&gt;用 &lt;code&gt;docker run&lt;/code&gt; 时对应的是 &lt;code&gt;--log-opt&lt;/code&gt; 参数，效果一样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d \
  --log-driver json-file \
  --log-opt max-size=20m \
  --log-opt max-file=3 \
  nginx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两种写法的分工很简单：&lt;strong&gt;daemon.json 定基线，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;保证任何容器都不会写爆磁盘&amp;lt;/span&amp;gt;；compose 的 logging 段做个别调整&lt;/strong&gt;，给需要特殊对待的服务开小灶。&lt;/p&gt;
&lt;h3&gt;轮转参数的几个细节&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;单位&lt;/strong&gt;：&lt;code&gt;max-size&lt;/code&gt; 支持 &lt;code&gt;k&lt;/code&gt;（KB）、&lt;code&gt;m&lt;/code&gt;（MB）、&lt;code&gt;g&lt;/code&gt;（GB），比如 &lt;code&gt;500k&lt;/code&gt;、&lt;code&gt;20m&lt;/code&gt;、&lt;code&gt;1g&lt;/code&gt; 都合法，不带单位默认是字节，千万别手滑写成纯数字。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;到底占多少&lt;/strong&gt;：一个容器的日志上限约等于 &lt;code&gt;max-size × max-file&lt;/code&gt;。20m × 3 = 60MB，单机跑二三十个容器，最坏情况也就 2GB 以内，心里要有这本账；如果某个服务日志量特别大又想多留历史，把它单独调大，而不是把全局基线放宽。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;轮转不是删除&lt;/strong&gt;：写满一个文件后，旧文件会被改名留作历史（如 &lt;code&gt;-json.log.1&lt;/code&gt;、&lt;code&gt;-json.log.2&lt;/code&gt;），&lt;code&gt;docker logs&lt;/code&gt; 读取时会自动把这几个文件拼起来看，所以轮转不会让近期日志「断片」，只是更早的会被挤掉。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;正在写的容器能改吗&lt;/strong&gt;：不能热改。容器的日志配置在创建那一刻就定死了，任何修改——不管是改 daemon.json 还是改 compose 文件——都必须重建容器才生效，这一点前面已经强调过，这里再重复一遍，因为它是本篇最容易翻车的地方。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;其他日志驱动对比&lt;/h2&gt;
&lt;p&gt;json-file 不是唯一选择。Docker 还内置了几种日志驱动，适用场景各不相同：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;驱动&lt;/th&gt;
&lt;th&gt;日志去向&lt;/th&gt;
&lt;th&gt;docker logs 能看吗&lt;/th&gt;
&lt;th&gt;适用场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;json-file&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;宿主机本地 JSON 文件&lt;/td&gt;
&lt;td&gt;✅ 能&lt;/td&gt;
&lt;td&gt;默认驱动，单机小规模部署，配好轮转就够用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;local&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;宿主机本地文件（Docker 优化格式）&lt;/td&gt;
&lt;td&gt;✅ 能&lt;/td&gt;
&lt;td&gt;json-file 的改良版：自带轮转和压缩，磁盘占用更小，官方推荐的新选择&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;journald&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;宿主机的 systemd journal&lt;/td&gt;
&lt;td&gt;✅ 能（经 journal 读取）&lt;/td&gt;
&lt;td&gt;宿主机用 systemd 且已有 journal 收集习惯，想和系统日志统一管理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;syslog&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;宿主机的 syslog 服务&lt;/td&gt;
&lt;td&gt;❌ 不能&lt;/td&gt;
&lt;td&gt;已有 syslog/远程日志服务器的老牌环境&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;none&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;直接丢弃&lt;/td&gt;
&lt;td&gt;❌ 不能&lt;/td&gt;
&lt;td&gt;输出量巨大且完全不需要日志的容器，或日志已由应用自己处理&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几点说明：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;local&lt;/code&gt; 驱动值得多看一眼：它就是为解决 json-file 的毛病设计的，默认就带轮转（&lt;code&gt;max-size&lt;/code&gt; 默认 20m、&lt;code&gt;max-file&lt;/code&gt; 默认 5），还做了压缩和更高效的读写。新部署的机器可以直接把 daemon.json 的 &lt;code&gt;log-driver&lt;/code&gt; 换成 &lt;code&gt;local&lt;/code&gt;，省去手动配轮转。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;journald&lt;/code&gt; 的好处是能按容器名过滤查看，坏处是日志和系统日志混在一起，且 journal 本身也有自己的轮转策略要管。用了 journald 之后，除了 &lt;code&gt;docker logs&lt;/code&gt;，还可以直接在宿主机上按容器名查：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;journalctl CONTAINER_NAME=nginx -f
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;local&lt;/code&gt; 驱动多提一句：它的日志文件不在前面说的 &lt;code&gt;-json.log&lt;/code&gt; 路径下，格式也是二进制优化过的，不能直接用文本工具去翻文件，老老实实用 &lt;code&gt;docker logs&lt;/code&gt; 看就行。它省下的主要是磁盘 I/O 和空间，对日志量大的机器收益明显。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;syslog&lt;/code&gt; 驱动下 &lt;code&gt;docker logs&lt;/code&gt; 完全失效，日志只在 syslog 里，换机器排障时容易两眼一抹黑。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
&lt;code&gt;none&lt;/code&gt; 驱动是个大坑预警：设成 &lt;code&gt;none&lt;/code&gt; 后容器日志被&lt;strong&gt;直接丢弃&lt;/strong&gt;，&lt;code&gt;docker logs&lt;/code&gt; 执行不报错、但什么都输出不了。哪天你发现某个容器「日志功能坏了」，先用 &lt;code&gt;docker inspect -f &apos;{{.HostConfig.LogConfig.Type}}&apos; 容器名&lt;/code&gt; 查一下它到底用的什么驱动——十有八九是创建时被设成了 &lt;code&gt;none&lt;/code&gt;，或者是从别人那抄的 compose 文件里带着这个设置。
:::&lt;/p&gt;
&lt;h2&gt;磁盘被日志写满：排障全流程&lt;/h2&gt;
&lt;p&gt;这是 Docker 新手最容易吃的一次亏：服务器突然各种服务报错、数据库连不上、SSH 登录都变慢，最后发现是根分区 100% 满了，而凶手往往就是某个容器的日志。按这个流程走，十分钟能定位并止血。&lt;/p&gt;
&lt;h3&gt;第一步：确认磁盘真的满了，满在哪&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 看分区使用率，确认哪个分区满了（一般是 / 或 /var）
df -h

# 看 /var/lib/docker 占了多少
du -sh /var/lib/docker
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第二步：定位大文件&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 按容器列出占用，排序找最大的
du -sh /var/lib/docker/containers/* | sort -rh | head -20

# 或者直接找所有超过 100MB 的日志文件
find /var/lib/docker -name &quot;*-json.log&quot; -size +100M -exec ls -lh {} \;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;一般到这一步凶手就现形了：某个 &lt;code&gt;-json.log&lt;/code&gt; 文件几个 GB 甚至几十 GB。&lt;/p&gt;
&lt;p&gt;想知道它属于哪个容器，用文件路径里的容器 ID 反查：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker ps -a --no-trunc | grep &amp;lt;容器ID前几位&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第三步：应急清空日志（truncate，不能 rm）&lt;/h3&gt;
&lt;p&gt;确认这个日志不需要保留后（或者先 &lt;code&gt;tail&lt;/code&gt; 拷一份样本出来），用 truncate 把文件清零：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;truncate -s 0 /var/lib/docker/containers/&amp;lt;容器ID&amp;gt;/&amp;lt;容器ID&amp;gt;-json.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;或者等价写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cat /dev/null &amp;gt; /var/lib/docker/containers/&amp;lt;容器ID&amp;gt;/&amp;lt;容器ID&amp;gt;-json.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;千万不要直接 &lt;code&gt;rm&lt;/code&gt; 删这个日志文件！&lt;/strong&gt;&amp;lt;/span&amp;gt; 容器进程和 Docker 守护进程还握着这个文件的句柄，&lt;code&gt;rm&lt;/code&gt; 只是删掉了目录项，进程会继续往那个「已经不存在」的文件里写，磁盘空间&lt;strong&gt;一点都不会释放&lt;/strong&gt;（用 &lt;code&gt;lsof | grep deleted&lt;/code&gt; 能看到它还占着），直到容器重启句柄才释放。更糟的是，新日志从此写进黑洞，&lt;code&gt;docker logs&lt;/code&gt; 也再看不到新内容。&lt;code&gt;truncate -s 0&lt;/code&gt; 是把同一个文件清零，句柄不变，空间立刻释放，容器继续正常写日志——这才是正确姿势。
:::&lt;/p&gt;
&lt;p&gt;多说一句怎么判断「凶手是不是日志」：磁盘写满时报错往往很迷惑——数据库可能报连接失败或只读错误，Web 服务返回 502，甚至 Docker 本身拉镜像、建容器都会失败，因为这些操作全都要往磁盘写东西。如果一台机器突然「所有服务一起出问题」，第一反应就应该是去看 &lt;code&gt;df -h&lt;/code&gt;，而不是逐个服务去猜。反过来，单个服务出问题、磁盘还很空，那就老老实实查应用本身，别在磁盘上浪费时间。&lt;/p&gt;
&lt;p&gt;清完后再 &lt;code&gt;df -h&lt;/code&gt; 确认空间回来，服务一般会自己恢复；个别已经崩掉的容器手动重启一下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker restart 容器名
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第四步：事后补上轮转配置&lt;/h3&gt;
&lt;p&gt;止血只是第一步，不补配置，过几天同样的事情还会再发生一遍：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;按前文给 daemon.json 加上 &lt;code&gt;log-opts&lt;/code&gt;（max-size 20m、max-file 3）；&lt;/li&gt;
&lt;li&gt;重启 Docker 让配置生效；&lt;/li&gt;
&lt;li&gt;把出事的那个容器&lt;strong&gt;删除重建&lt;/strong&gt;（记住：只对新建容器生效），确认新容器的 &lt;code&gt;LogConfig&lt;/code&gt; 里已经带上轮转参数；&lt;/li&gt;
&lt;li&gt;顺手检查其他老容器，逐个重建或者在 compose 里补 &lt;code&gt;logging&lt;/code&gt; 段。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;加一道保险：定期巡检大日志&lt;/h3&gt;
&lt;p&gt;轮转配置难免有漏网之鱼（比如别人部署的容器、临时测试起的容器），可以再加一个简单的巡检脚本，定期扫一遍超大日志文件，提前发现苗头：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
# /opt/scripts/check-docker-logs.sh：找出超过 500MB 的容器日志并记录
find /var/lib/docker/containers -name &quot;*-json.log&quot; -size +500M \
  -exec ls -lh {} \; &amp;gt;&amp;gt; /var/log/docker-logs-check.log 2&amp;gt;&amp;amp;1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;挂到 crontab 每周跑一次，或者配合你已有的监控，在文件出现时就告警：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;0 9 * * 1 /opt/scripts/check-docker-logs.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;思路和自动更新一样：&lt;strong&gt;重复性的检查交给定时任务，人才有精力处理真正需要判断的问题&lt;/strong&gt;。等哪天巡检日志里真出现了一行记录，说明又有容器在偷偷攒日志，按前面的流程处理即可。&lt;/p&gt;
&lt;h2&gt;Dozzle：网页端集中看日志&lt;/h2&gt;
&lt;p&gt;容器一多，SSH 上去一个个 &lt;code&gt;docker logs&lt;/code&gt; 就很折腾了。Dozzle 是一个轻量的日志查看 Web 界面：实时流式显示所有容器的日志、支持搜索过滤、多容器一键切换，镜像本身只有十几 MB，是个人服务器上最顺手的日志工具。&lt;/p&gt;
&lt;h3&gt;Compose 部署&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;services:
  dozzle:
    image: amir20/dozzle:latest
    container_name: dozzle
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - &quot;127.0.0.1:8080:8080&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意端口写法是 &lt;code&gt;127.0.0.1:8080:8080&lt;/code&gt;——只绑定本机回环地址，外网直接访问不到，原因在下一节细说。&lt;/p&gt;
&lt;h3&gt;界面能干什么&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;实时日志流&lt;/strong&gt;：打开就是所有容器的列表，点进任意容器，日志像 &lt;code&gt;docker logs -f&lt;/code&gt; 一样实时滚动，不用手动刷新；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;多容器切换&lt;/strong&gt;：左侧列表一键切换，还能同屏对比看几个容器的日志，排查「A 服务调 B 服务失败」这类跨容器问题特别方便；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;搜索与过滤&lt;/strong&gt;：在日志流里直接关键词搜索、高亮命中行，比在终端里翻 &lt;code&gt;grep&lt;/code&gt; 直观得多；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;历史回看&lt;/strong&gt;：往上滚动就能加载更早的日志，带时间戳显示；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;几乎零配置&lt;/strong&gt;：它直接读 Docker 的日志，你现有的容器什么都不用改，装上就能看。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Dozzle 只是「看」日志的工具，它不存储、不转储日志——容器删了，日志在 Dozzle 里也就没了，这一点和 &lt;code&gt;docker logs&lt;/code&gt; 的行为一致。&lt;/p&gt;
&lt;p&gt;再介绍两个实用的可选项。第一，&lt;strong&gt;只展示部分容器&lt;/strong&gt;：机器上容器多了，列表会很长，可以用过滤参数只盯你关心的那些，过滤语法和 &lt;code&gt;docker ps --filter&lt;/code&gt; 一致：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    command: --filter label=com.centurylinklabs.watchtower.enable=true
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;或者按名字过滤：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    command: --filter name=nginx --filter name=app
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第二，&lt;strong&gt;挂在反向代理的子路径下&lt;/strong&gt;：如果想把 Dozzle 放在 &lt;code&gt;https://你的域名/logs/&lt;/code&gt; 这种子路径而不是独立端口/子域名，给它设置基础路径：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    environment:
      - DOZZLE_BASE=/logs
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;反向代理把 &lt;code&gt;/logs/&lt;/code&gt; 转发到 Dozzle 的 8080 端口即可，页面里的静态资源路径会自动带上这个前缀，不会出现页面打开了但样式和脚本 404 的问题。&lt;/p&gt;
&lt;h3&gt;安全加固（重中之重）&lt;/h3&gt;
&lt;p&gt;Dozzle 好用，但它的能力来源是那块 &lt;code&gt;/var/run/docker.sock&lt;/code&gt;，这也是它最大的风险点，必须认真对待。&lt;/p&gt;
&lt;p&gt;先说清楚 docker.sock 是什么：它是 Docker 守护进程的控制接口，谁能访问它，谁就能创建任意容器、挂载宿主机任意目录、以 root 权限在宿主机上执行命令——&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;等于宿主机的 root 权限&lt;/strong&gt;&amp;lt;/span&amp;gt;。Dozzle 挂的是只读（&lt;code&gt;:ro&lt;/code&gt;），这能防止通过 Dozzle 本身修改容器状态，是必须保留的设置；但即便如此，能看&lt;strong&gt;所有容器的全部日志&lt;/strong&gt;本身就很敏感：日志里经常混着数据库密码、API Token、用户隐私数据。&lt;/p&gt;
&lt;p&gt;所以部署时请务必做到这三点：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;不要直接暴露公网。&lt;/strong&gt; 端口只绑 &lt;code&gt;127.0.0.1&lt;/code&gt;（像上面 compose 里那样），然后通过反向代理（Nginx/Caddy）加 HTTPS 访问，或者干脆只在内网/通过 SSH 隧道访问：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;# 在自己电脑上开隧道，然后浏览器访问 http://localhost:8080
ssh -L 8080:127.0.0.1:8080 root@你的服务器
&lt;/code&gt;&lt;/pre&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;开启 Dozzle 自带的登录认证。&lt;/strong&gt; 给容器加两个环境变量即可启用用户名密码登录：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;    environment:
      - TZ=Asia/Shanghai
      - DOZZLE_USERNAME=admin
      - DOZZLE_PASSWORD=换成你的强密码
&lt;/code&gt;&lt;/pre&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;反向代理再加一层。&lt;/strong&gt; 如果确实需要从公网访问，在 Nginx 层再加 Basic Auth 或 IP 白名单，和 Dozzle 自带认证叠加，双保险。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::warning
把 Dozzle 裸奔在公网上（&lt;code&gt;8080:8080&lt;/code&gt; 不绑回环、不设密码）是真实世界里被入侵的常见入口之一：扫描器全天候在扫这个端口，一旦被人打开，你所有容器的日志——包括里面可能出现的密钥和隐私——都一览无余，对方还能从日志里摸清你的全部服务结构。花在加固上的这三分钟，绝对不能省。
:::&lt;/p&gt;
&lt;h2&gt;排障：docker logs 没输出怎么办&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;docker logs&lt;/code&gt; 执行成功、退出码正常，但就是一片空白。按可能性从高到低排查：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;1. 应用把日志写进了文件，没走 stdout/stderr。&lt;/strong&gt;
这是最常见的原因。&lt;code&gt;docker logs&lt;/code&gt; 只能拿到容器主进程的标准输出和标准错误；很多传统应用默认把日志写到 &lt;code&gt;/var/log/xxx.log&lt;/code&gt; 这类文件里，自然看不到。验证方法：进容器里看看有没有日志文件在长大：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec -it 容器名 sh -c &apos;ls -lt /var/log/ | head&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;解决办法是改应用的日志配置让它输出到 stdout；实在改不了，可以在启动命令里把日志文件软链到标准输出，这也是很多官方镜像的做法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;RUN ln -sf /dev/stdout /var/log/app.log \
    &amp;amp;&amp;amp; ln -sf /dev/stderr /var/log/app-error.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;2. 日志驱动被设成了 none。&lt;/strong&gt;
前面提过，&lt;code&gt;none&lt;/code&gt; 驱动直接丢弃日志。检查并重建容器换回 json-file 或 local：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker inspect -f &apos;{{.HostConfig.LogConfig.Type}}&apos; 容器名
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;3. 容器已经删除了。&lt;/strong&gt;
日志文件是跟着容器走的，容器被 &lt;code&gt;docker rm&lt;/code&gt;（或者被自动更新工具重建失败后清掉）之后，日志文件一并删除，事后无从查起。这也是为什么 &lt;a href=&quot;/posts/linux-docker-auto-update/&quot;&gt;《如何在Linux自动更新Docker容器》&lt;/a&gt; 里建议重要服务先开「只监控」观察期、更新前先看日志：真出了事，旧容器的日志还在才有据可查。需要长期留存的日志，应该让应用输出到挂载出来的数据卷文件里，或者接入集中日志系统，而不是只依赖 &lt;code&gt;docker logs&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 用了 --since 却把时间算错了。&lt;/strong&gt;
不加参数明明有日志，一加 &lt;code&gt;--since&lt;/code&gt; 就空白，多半是时间对不上：&lt;code&gt;docker logs&lt;/code&gt; 的绝对时间按 UTC 理解，而你脑子里想的是北京时间，差着 8 小时，窗口自然卡空了。不确定时先用相对时长（&lt;code&gt;--since 30m&lt;/code&gt;）验证，或者用 &lt;code&gt;date -u&lt;/code&gt; 看一眼服务器的 UTC 时间再换算。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. 顺带一提：输出被缓冲了。&lt;/strong&gt;
有些语言（典型如 Python）的 stdout 在非终端环境下是块缓冲，程序在跑、日志却攒着不吐出来，看起来像没输出，过一阵又突然刷出一大片。这不是 Docker 的问题：Python 加 &lt;code&gt;-u&lt;/code&gt; 参数或环境变量 &lt;code&gt;PYTHONUNBUFFERED=1&lt;/code&gt; 即可，其他语言同理查各自的无缓冲设置。&lt;/p&gt;
&lt;h2&gt;再往后：什么时候需要集中日志系统&lt;/h2&gt;
&lt;p&gt;本篇讲的都是单机范围内的日志管理：一台机器、几十个容器，&lt;code&gt;docker logs&lt;/code&gt; 加 Dozzle 完全够用。但如果你的情况变成下面这样，就该考虑把日志集中收集到专门的系统里了：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;机器变多&lt;/strong&gt;：三五台服务器各跑各的容器，出一次问题要挨个 SSH 上去翻日志，效率太低；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;日志要长期留存&lt;/strong&gt;：审计、复盘需要查几个月前的日志，而本机轮转早就把它们挤掉了；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;需要告警&lt;/strong&gt;：想在日志出现特定错误（比如支付失败、异常堆栈）时第一时间收到通知，而不是等用户来报障。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;常见的集中方案有 Loki + Promtail + Grafana（轻量，和监控面板能合一）、ELK（Elasticsearch + Logstash + Kibana，功能强但吃资源）等。它们的共同思路是：在每台机器上跑一个采集小组件，把容器日志实时转发到中心存储。个人规模建议从 Loki 起步，资源占用小、和 Docker 的配合也成熟。不过记住一句话：&lt;strong&gt;集中系统是锦上添花，单机的轮转配置永远是地基&lt;/strong&gt;——采集组件挂掉的时候，本机日志如果没封顶，照样能把磁盘写满，地基的活儿一天都不能省。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;docker logs&lt;/code&gt; 的日常组合是 &lt;code&gt;-f&lt;/code&gt; 跟踪、&lt;code&gt;--tail&lt;/code&gt; 限量、&lt;code&gt;--since/--until&lt;/code&gt; 卡时间窗、&lt;code&gt;-t&lt;/code&gt; 带时间戳，先缩小范围再细看；&lt;/li&gt;
&lt;li&gt;默认 json-file 驱动&lt;strong&gt;不轮转&lt;/strong&gt;，这是磁盘写满事故的头号来源，必须配轮转：daemon.json 全局设 &lt;code&gt;max-size: 20m&lt;/code&gt; + &lt;code&gt;max-file: 3&lt;/code&gt; 定基线，compose 的 &lt;code&gt;logging&lt;/code&gt; 段给个别容器开小灶；&lt;/li&gt;
&lt;li&gt;牢记 daemon.json 改完&lt;strong&gt;只对新建容器生效&lt;/strong&gt;，老容器要重建，并用 &lt;code&gt;docker inspect&lt;/code&gt; 逐个验证；&lt;/li&gt;
&lt;li&gt;磁盘真被写满时，流程是 &lt;code&gt;df&lt;/code&gt;/&lt;code&gt;du&lt;/code&gt;/&lt;code&gt;find&lt;/code&gt; 定位 → &lt;code&gt;truncate -s 0&lt;/code&gt; 清零止血（绝不能直接 &lt;code&gt;rm&lt;/code&gt;）→ 补轮转配置防复发；&lt;/li&gt;
&lt;li&gt;容器多了用 Dozzle 在网页上集中看日志，但 docker.sock 事关宿主机 root 权限：只读挂载、端口绑 127.0.0.1、开登录认证，三件套缺一不可；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;docker logs&lt;/code&gt; 没输出，先怀疑应用没往 stdout 写，其次查日志驱动是不是 &lt;code&gt;none&lt;/code&gt;，最后确认容器是不是已经被删了。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;日志管理的核心就一句话：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;平时给它封顶，出事时靠它查命&lt;/strong&gt;&amp;lt;/span&amp;gt;。轮转配置花十分钟一次配好，往后每次排障都会感谢现在的自己。&lt;/p&gt;
</content:encoded></item><item><title>容器监控体系：cAdvisor 加 Prometheus 加 Grafana</title><link>https://www.anexns.cloudns.org/posts/docker-monitoring-prometheus/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-monitoring-prometheus/</guid><description>从 docker stats 肉眼巡检升级到正经监控：cAdvisor 采集容器指标、Prometheus 存储与查询、Grafana 出图与告警，一套 Compose 全部部署，并讲清它与轻量面板的定位区别。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;容器少的时候，&lt;code&gt;docker stats&lt;/code&gt; 看一眼就够了。但当一台机器上跑了十几个容器、还指望它们 7×24 稳定运行时，靠肉眼巡检迟早出事：凌晨三点某个容器内存缓慢泄漏，一点点吃满宿主机，等你早上发现的时候服务已经挂了几个小时，而你连它是从什么时候开始涨的都不知道。这篇讲怎么给 Docker 搭一套正经的监控体系——cAdvisor 负责采集每个容器的指标，Prometheus 负责存储和查询，Grafana 负责画图和告警，一套 Compose 全部搞定。&lt;/p&gt;
&lt;h2&gt;为什么 docker stats 不够用&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;docker stats&lt;/code&gt; 显示的是&lt;strong&gt;此刻&lt;/strong&gt;的快照，它有三个硬伤：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;缺失能力&lt;/th&gt;
&lt;th&gt;具体问题&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;没有历史&lt;/td&gt;
&lt;td&gt;关掉终端数据就没了，查不了「昨晚 8 点内存为什么飙高」&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;没有曲线&lt;/td&gt;
&lt;td&gt;只有一个数字，看不出趋势：内存是在缓慢泄漏还是瞬间打满，处理方式完全不同&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;没有告警&lt;/td&gt;
&lt;td&gt;异常必须正好被你撞见才算数，没人能 24 小时盯着屏幕&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;在命令速查篇（&lt;a href=&quot;/posts/docker-commands-troubleshooting/&quot;&gt;《Docker 常用命令速查与排障实战》&lt;/a&gt;）里我们说过，&lt;code&gt;docker stats&lt;/code&gt; 是排障的起手式之一，它适合「已经出事了，我来看看现在什么情况」，不适合「在出事之前拦住它」。正经监控要的恰恰是后者：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;指标持续采集、历史可查、异常主动喊人&amp;lt;/span&amp;gt;。这就是这套三件套存在的意义。&lt;/p&gt;
&lt;h2&gt;三件套分工与数据流向&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;组件&lt;/th&gt;
&lt;th&gt;角色&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;cAdvisor&lt;/td&gt;
&lt;td&gt;采集员&lt;/td&gt;
&lt;td&gt;Google 开源的容器监控工具，盯着每个容器的 CPU、内存、网络、磁盘 IO，把指标暴露成一个 HTTP 接口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Prometheus&lt;/td&gt;
&lt;td&gt;仓库 + 大脑&lt;/td&gt;
&lt;td&gt;定时去 cAdvisor 那里把指标「抓」回来存进自己的时序数据库，并提供 PromQL 查询语言和告警规则引擎&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Grafana&lt;/td&gt;
&lt;td&gt;展示 + 喊人&lt;/td&gt;
&lt;td&gt;把 Prometheus 里的数据画成曲线图、仪表盘，超阈值时通过告警通知你&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;数据流向是单向的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;容器 → cAdvisor（采集，:8080/metrics）→ Prometheus（定时抓取存储）→ Grafana（查询出图/告警）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 Prometheus 的工作方式是&lt;strong&gt;拉取（pull）&lt;/strong&gt;：不是 cAdvisor 主动上报，而是 Prometheus 每隔一段时间去访问 cAdvisor 的 &lt;code&gt;/metrics&lt;/code&gt; 接口把数据拿走。这个细节后面排障时会用到——抓不到数据先看 Prometheus 的 Targets 状态。&lt;/p&gt;
&lt;h2&gt;完整 Compose 部署&lt;/h2&gt;
&lt;p&gt;一套 Compose 把三件套全拉起来。先看全貌，后面逐个拆解：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  cadvisor:
    image: gcr.io/cadvisor/cadvisor:latest
    container_name: cadvisor
    restart: unless-stopped
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
    ports:
      - &quot;127.0.0.1:8080:8080&quot;

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    restart: unless-stopped
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - ./rules.yml:/etc/prometheus/rules.yml
      - prometheus_data:/prometheus
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --storage.tsdb.path=/prometheus
      - --storage.tsdb.retention.time=15d
    ports:
      - &quot;127.0.0.1:9090:9090&quot;
    depends_on:
      - cadvisor

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    restart: unless-stopped
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=换成你自己的强密码
    volumes:
      - grafana_data:/var/lib/grafana
    ports:
      - &quot;127.0.0.1:3000:3000&quot;
    depends_on:
      - prometheus

volumes:
  prometheus_data:
  grafana_data:
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;cAdvisor 的四个关键挂载&lt;/h3&gt;
&lt;p&gt;cAdvisor 要统计每个容器的资源占用，就必须能看到宿主机的 cgroup 和 Docker 的数据目录，所以它挂了四个路径，缺一不可：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;挂载&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/:/rootfs:ro&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;把宿主机根目录只读挂进来，让 cAdvisor 能遍历整个文件系统视角下的进程与 cgroup 信息&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/var/run:/var/run:ro&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;里面有 Docker 的 socket 等运行时文件，cAdvisor 靠它和 Docker 守护进程通信、识别容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/sys:/sys:ro&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;cgroup 的数据就挂在 &lt;code&gt;/sys/fs/cgroup&lt;/code&gt; 下，CPU、内存的实际计数器从这里读&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/var/lib/docker/:/var/lib/docker:ro&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Docker 的数据根目录，镜像层、容器元数据都在这，cAdvisor 用它把 cgroup 和具体容器对应起来&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;全部是 &lt;code&gt;:ro&lt;/code&gt; 只读挂载——它只负责读数据统计，不需要写权限，能只读就只读，这是挂载宿主机路径时的基本原则。&lt;/p&gt;
&lt;p&gt;:::warning
在部分系统上 cAdvisor 还需要 &lt;code&gt;privileged: true&lt;/code&gt; 或者额外挂载 &lt;code&gt;/dev/kmsg&lt;/code&gt; 才能拿到完整的机器级指标。如果部署后发现容器指标正常、但宿主机级别的指标缺失，可以在 cadvisor 服务下补一行 &lt;code&gt;privileged: true&lt;/code&gt; 再重建。但&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;特权模式等于放弃容器隔离&amp;lt;/span&amp;gt;，只在确认缺指标时再开，不要无脑加上。
:::&lt;/p&gt;
&lt;h3&gt;Prometheus 的挂载与参数&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;./prometheus.yml&lt;/code&gt; 是主配置文件（下一节逐段讲），&lt;code&gt;./rules.yml&lt;/code&gt; 是告警规则文件；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;prometheus_data&lt;/code&gt; 命名卷挂到 &lt;code&gt;/prometheus&lt;/code&gt;，这是它时序数据库的家，&lt;strong&gt;容器重建数据不能丢，全靠这个卷&lt;/strong&gt;；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--storage.tsdb.retention.time=15d&lt;/code&gt; 是数据保留期，只留最近 15 天，超期自动删——不设的话默认也是 15 天，但写明了心里有数，后面还会细说；&lt;/li&gt;
&lt;li&gt;端口 9090 是 Prometheus 自带的 Web 界面，能直接写 PromQL 查询、看 Targets 状态。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;Grafana 的密码与数据卷&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;管理员账号密码通过 &lt;code&gt;GF_SECURITY_ADMIN_USER&lt;/code&gt; / &lt;code&gt;GF_SECURITY_ADMIN_PASSWORD&lt;/code&gt; 环境变量设置，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝不要用默认的 admin/admin 上线&amp;lt;/span&amp;gt;，首次启动前就把密码换掉；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;grafana_data&lt;/code&gt; 卷存它的仪表盘、数据源配置和用户数据，不挂卷的话容器一重建，你配好的图全没了。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;端口为什么只绑 127.0.0.1&lt;/h3&gt;
&lt;p&gt;三个端口全部写成 &lt;code&gt;127.0.0.1:端口:端口&lt;/code&gt; 的形式，意思是只允许从服务器本机访问。原因很实在：cAdvisor 的界面能看到你所有容器的名字和资源占用，Prometheus 界面能执行任意查询，Grafana 虽然有登录但也不该直接暴露在公网上。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;监控面板裸奔公网等于把服务器的内脏摊开给人看&amp;lt;/span&amp;gt;。日常访问用 SSH 隧道转发，或者用前面 Nginx/Caddy 篇讲的反向代理套一层 HTTPS 再加认证，对外只开反代那一个入口。&lt;/p&gt;
&lt;h2&gt;prometheus.yml 配置逐段讲解&lt;/h2&gt;
&lt;p&gt;部署前先把 &lt;code&gt;prometheus.yml&lt;/code&gt; 写好，它决定 Prometheus 去抓谁、多久抓一次：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;global:
  scrape_interval: 15s
  evaluation_interval: 15s

rule_files:
  - &quot;rules.yml&quot;

scrape_configs:
  - job_name: &quot;prometheus&quot;
    static_configs:
      - targets: [&quot;localhost:9090&quot;]

  - job_name: &quot;cadvisor&quot;
    static_configs:
      - targets: [&quot;cadvisor:8080&quot;]

  - job_name: &quot;node&quot;
    static_configs:
      - targets: [&quot;node-exporter:9100&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐段拆开看：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;global.scrape_interval: 15s&lt;/code&gt;：默认抓取间隔 15 秒。容器监控 15 秒足够细了，调到 5 秒只会让数据库膨胀三倍，收益不大。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;evaluation_interval: 15s&lt;/code&gt;：告警规则的评估间隔，Prometheus 每 15 秒检查一次规则文件里的条件有没有被触发。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;rule_files&lt;/code&gt;：加载告警规则文件，就是 Compose 里挂进去的那个 &lt;code&gt;rules.yml&lt;/code&gt;，路径相对于配置文件所在目录写文件名即可。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;scrape_configs&lt;/code&gt; 是抓取目标清单，每个 &lt;code&gt;job_name&lt;/code&gt; 是一组：
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;prometheus&lt;/code&gt; 抓自己，用来监控监控系统本身的健康；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;cadvisor&lt;/code&gt; 是主角，目标 &lt;code&gt;cadvisor:8080&lt;/code&gt;——注意这里用的是 &lt;strong&gt;Compose 服务名&lt;/strong&gt;，因为 Prometheus 和 cAdvisor 在同一个 Compose 网络里，靠服务名就能互相找到，这正是自定义网络内置 DNS 的用法；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;node&lt;/code&gt; 是可选项：如果你还想监控&lt;strong&gt;宿主机本身&lt;/strong&gt;的 CPU、内存、磁盘、网络（而不只是容器），再额外跑一个 &lt;code&gt;prom/node-exporter&lt;/code&gt; 容器（端口 9100），把这段加上；只关心容器的话可以整段删掉，不影响主线。&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;cAdvisor 自带界面与核心指标速览&lt;/h2&gt;
&lt;p&gt;cAdvisor 本身带一个 Web 界面（本机访问 &lt;code&gt;http://127.0.0.1:8080&lt;/code&gt;），能按容器点进去看实时曲线，临时瞄一眼够用；但它的数据只留在内存里，重启就没，所以正经的历史和告警还是靠 Prometheus。&lt;/p&gt;
&lt;p&gt;写 PromQL 之前，先认识几个最核心的指标名。cAdvisor 的指标都以 &lt;code&gt;container_&lt;/code&gt; 开头，用标签区分容器，最常用的是 &lt;code&gt;name&lt;/code&gt;（容器名）和 &lt;code&gt;image&lt;/code&gt;（镜像名）：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;指标名&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;container_cpu_usage_seconds_total&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器累计消耗的 CPU 时间（秒），是个只增不减的计数器，要配合 &lt;code&gt;rate()&lt;/code&gt; 算使用率&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;container_memory_usage_bytes&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器当前内存占用（字节），包含缓存，是最直观的那个数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;container_memory_working_set_bytes&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器的工作集内存（不含可回收缓存），判断「真的吃紧了」看这个更准，告警一般用它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;container_spec_memory_limit_bytes&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器的内存上限（没设限制时等于宿主机总内存），算内存百分比时当分母&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;container_network_receive_bytes_total&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器累计收到的网络流量（字节），计数器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;container_network_transmit_bytes_total&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器累计发出的网络流量（字节），计数器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;container_start_time_seconds&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器启动时间点的时间戳，它一变就说明容器重启过&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;记住一条规律：名字带 &lt;code&gt;_total&lt;/code&gt; 的基本都是&lt;strong&gt;累计计数器&lt;/strong&gt;，直接看数值没意义，必须用 &lt;code&gt;rate()&lt;/code&gt; 或 &lt;code&gt;increase()&lt;/code&gt; 换算成速率/增量；不带 &lt;code&gt;_total&lt;/code&gt; 的是&lt;strong&gt;瞬时值&lt;/strong&gt;，可以直接看、可以直接告警。&lt;/p&gt;
&lt;h2&gt;PromQL 入门五例&lt;/h2&gt;
&lt;p&gt;PromQL 是 Prometheus 的查询语言，Grafana 出图、告警规则背后全是它。下面五条是容器监控里最高频的，逐条拆解。&lt;/p&gt;
&lt;h3&gt;例 1：某容器的 CPU 使用率&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;rate(container_cpu_usage_seconds_total{name=&quot;nginx&quot;}[5m]) * 100
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拆解：&lt;code&gt;container_cpu_usage_seconds_total&lt;/code&gt; 是累计 CPU 秒数；&lt;code&gt;{name=&quot;nginx&quot;}&lt;/code&gt; 用标签只选名为 nginx 的容器；&lt;code&gt;rate(...[5m])&lt;/code&gt; 取最近 5 分钟窗口，算出平均每秒增长多少——也就是平均用了几个核；乘 100 换成百分比口径（100% = 用满 1 个核，400% = 用满 4 个核）。&lt;/p&gt;
&lt;h3&gt;例 2：内存占用排行&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;topk(5, container_memory_usage_bytes{name!=&quot;&quot;})
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拆解：&lt;code&gt;{name!=&quot;&quot;}&lt;/code&gt; 过滤掉没有容器名的序列（cAdvisor 会给宿主机本身和 cgroup 层级也生成指标，名字为空，不滤掉排行榜会被它们污染）；&lt;code&gt;topk(5, ...)&lt;/code&gt; 取数值最大的 5 条。想看哪个容器最吃内存，这条直接出答案。单位是字节，在 Grafana 里把单位设成 bytes 会自动换算成 MiB/GiB 显示。&lt;/p&gt;
&lt;h3&gt;例 3：某容器的网络接收速率&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;rate(container_network_receive_bytes_total{name=&quot;nginx&quot;}[5m])
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拆解：和例 1 同理，对累计接收字节数求 5 分钟平均速率，得到的是字节/秒。发送方向把指标换成 &lt;code&gt;container_network_transmit_bytes_total&lt;/code&gt; 即可。注意有些容器有多个网卡（eth0、veth 等），会按 &lt;code&gt;interface&lt;/code&gt; 标签分开出多条序列，需要汇总时外面再套一层 &lt;code&gt;sum by (name) (...)&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;例 4：最近一小时某容器流出了多少流量&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;increase(container_network_transmit_bytes_total{name=&quot;nginx&quot;}[1h])
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拆解：&lt;code&gt;increase()&lt;/code&gt; 和 &lt;code&gt;rate()&lt;/code&gt; 是亲兄弟，区别是它不除以时间、直接给窗口内的&lt;strong&gt;总增量&lt;/strong&gt;。算速率用 &lt;code&gt;rate()&lt;/code&gt;，算「这一小时一共跑了多少流量」用 &lt;code&gt;increase()&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;例 5：某容器最近 24 小时重启了几次&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;changes(container_start_time_seconds{name=&quot;nginx&quot;}[24h])
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拆解：&lt;code&gt;container_start_time_seconds&lt;/code&gt; 记录容器启动时刻，容器每次重启这个值就会跳一次；&lt;code&gt;changes()&lt;/code&gt; 统计窗口内这个值变化了几次，正好就是重启次数。某个容器半夜反复重启，用这条一查便知，比翻日志快得多。&lt;/p&gt;
&lt;h3&gt;附：标签过滤的四种匹配符&lt;/h3&gt;
&lt;p&gt;上面五例反复用到 &lt;code&gt;{name=&quot;nginx&quot;}&lt;/code&gt; 这种大括号写法，它叫标签匹配，是 PromQL 的基本功，一共四种：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;匹配符&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;典型用法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;完全相等&lt;/td&gt;
&lt;td&gt;&lt;code&gt;{name=&quot;nginx&quot;}&lt;/code&gt; 只看这一个容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;!=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不相等&lt;/td&gt;
&lt;td&gt;&lt;code&gt;{name!=&quot;&quot;}&lt;/code&gt; 排除无名序列，五例里反复出现&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;=~&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;正则匹配&lt;/td&gt;
&lt;td&gt;&lt;code&gt;{name=~&quot;api|web&quot;}&lt;/code&gt; 一次看两个容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;!~&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;正则排除&lt;/td&gt;
&lt;td&gt;&lt;code&gt;{name!~&quot;test.*&quot;}&lt;/code&gt; 把测试容器全部排除&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;多个条件写在同一对大括号里用逗号隔开，是「并且」的关系，比如 &lt;code&gt;{name=&quot;nginx&quot;, interface=&quot;eth0&quot;}&lt;/code&gt; 表示只要 nginx 的 eth0 网卡那一条。刚上手时最容易写错的是把 &lt;code&gt;=~&lt;/code&gt; 的正则忘了加引号、或者在 &lt;code&gt;|&lt;/code&gt; 两侧加空格，记住整段正则要完整包在引号里就行。另外提醒一句：查询返回的序列太多时 Grafana 画图会糊成一团，先用标签把范围收窄到你要看的那几个容器，再套函数计算，这个顺序别反了。&lt;/p&gt;
&lt;p&gt;:::warning
所有 &lt;code&gt;rate()&lt;/code&gt; / &lt;code&gt;increase()&lt;/code&gt; 的时间窗口建议至少是抓取间隔的 4 倍。咱们抓取间隔 15 秒，窗口就别小于 1 分钟，例子里统一用 &lt;code&gt;[5m]&lt;/code&gt; 是稳妥的默认值；窗口太小算出来的曲线会锯齿乱跳，甚至直接没数据。
:::&lt;/p&gt;
&lt;h2&gt;Grafana 接入：数据源与现成仪表盘&lt;/h2&gt;
&lt;p&gt;三件套跑起来后，打开 Grafana（本机 &lt;code&gt;http://127.0.0.1:3000&lt;/code&gt;），用 Compose 里设的管理员账号登录，然后做两件事。&lt;/p&gt;
&lt;h3&gt;第一步：添加 Prometheus 数据源&lt;/h3&gt;
&lt;p&gt;左侧菜单进 &lt;strong&gt;Connections → Data sources → Add data source&lt;/strong&gt;，选 Prometheus，URL 填：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;http://prometheus:9090
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;同样是走 Compose 服务名互访——Grafana 容器和 Prometheus 容器在同一网络里。填完点 &lt;strong&gt;Save &amp;amp; test&lt;/strong&gt;，看到绿色的成功提示就说明通了。&lt;/p&gt;
&lt;h3&gt;第二步：导入现成仪表盘&lt;/h3&gt;
&lt;p&gt;容器监控的仪表盘没必要自己从零画，Grafana 官方仪表盘库里有大量现成的 cAdvisor 仪表盘，导入步骤：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;打开 Grafana 官网的仪表盘库页面（grafana.com 的 Dashboards 区），搜索关键词 &lt;code&gt;cadvisor&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;挑一个下载量高、近期有维护的，点进去把它的 JSON 文件下载下来（页面上也有一个仪表盘编号 ID 可复制，二选一即可）；&lt;/li&gt;
&lt;li&gt;回到自己的 Grafana，左侧进 &lt;strong&gt;Dashboards → New → Import&lt;/strong&gt;，上传 JSON 文件（或粘贴 ID 让它在线拉取）；&lt;/li&gt;
&lt;li&gt;导入时数据源选第一步建好的 Prometheus，确认导入。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;导入后你会得到一套按容器筛选的 CPU、内存、网络、磁盘曲线面板，顶部一般有容器下拉框，切换容器名就能看单个容器的全貌。先用现成的跑起来，哪些图没用删掉、缺什么再自己加面板，这是最省时间的路线。&lt;/p&gt;
&lt;p&gt;:::warning
导入在线拉取 ID 的方式要求 Grafana 所在服务器能访问外网；如果拉取失败，就改走「下载 JSON 再上传」这条路，效果完全一样。网上教程里写的仪表盘 ID 很多已经过时或被作者删除，照抄别人的 ID 导入失败是常事，以官网库当前能搜到的为准。
:::&lt;/p&gt;
&lt;h2&gt;告警：容器内存超 90% 持续 5 分钟&lt;/h2&gt;
&lt;p&gt;监控的终点是告警。这里给一条完整可抄的规则：&lt;strong&gt;任意容器的工作集内存超过其上限的 90%，且持续 5 分钟，就触发告警&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;把下面内容写进 Compose 里挂载的 &lt;code&gt;rules.yml&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;groups:
  - name: container-alerts
    rules:
      - alert: ContainerHighMemory
        expr: |
          container_memory_working_set_bytes{name!=&quot;&quot;}
            / container_spec_memory_limit_bytes{name!=&quot;&quot;} &amp;gt; 0.9
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: &quot;容器 {{ $labels.name }} 内存使用率过高&quot;
          description: &quot;容器 {{ $labels.name }} 的工作集内存已超过上限的 90%，当前值 {{ $value | humanizePercentage }}，请及时处理。&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐段说明：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;expr&lt;/code&gt; 是触发条件：工作集内存除以上限大于 0.9。分子分母都带 &lt;code&gt;{name!=&quot;&quot;}&lt;/code&gt; 把无名序列滤掉；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;for: 5m&lt;/code&gt; 是关键——条件必须&lt;strong&gt;连续成立满 5 分钟&lt;/strong&gt;才真正触发，短暂的毛刺不会半夜把你吵醒；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;{{ $labels.name }}&lt;/code&gt; 会被替换成具体的容器名，告警消息里一眼能看出是谁出事；&lt;/li&gt;
&lt;li&gt;规则文件改完后重启 Prometheus 容器生效（&lt;code&gt;docker compose restart prometheus&lt;/code&gt;），在 Prometheus 界面的 &lt;strong&gt;Status → Rules&lt;/strong&gt; 里能看到这条规则是否加载成功。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;触发之后通知发到哪，有两条路线，二选一即可，别重复配：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;路线&lt;/th&gt;
&lt;th&gt;做法&lt;/th&gt;
&lt;th&gt;适合&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Prometheus + Alertmanager&lt;/td&gt;
&lt;td&gt;再部署一个 Alertmanager 容器，在 &lt;code&gt;prometheus.yml&lt;/code&gt; 里加 &lt;code&gt;alerting&lt;/code&gt; 段指向它，由它负责把告警发到邮件/Webhook 等渠道&lt;/td&gt;
&lt;td&gt;告警条数多、想要分组去重静默等专业能力&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Grafana 告警&lt;/td&gt;
&lt;td&gt;直接在 Grafana 的 Alerting 里基于同一条 PromQL 建告警规则并绑通知渠道&lt;/td&gt;
&lt;td&gt;就几台机器、规则不多，想少养一个组件&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;小规模场景我更推荐 Grafana 告警这一条，少一个容器少一份维护；等规则多到需要分组、静默、值班轮换时，再上 Alertmanager 也不迟。&lt;/p&gt;
&lt;h2&gt;资源占用与数据留存：小机器先算账&lt;/h2&gt;
&lt;p&gt;这套监控本身也是要吃资源的，先把账算清楚再决定上不上：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;组件&lt;/th&gt;
&lt;th&gt;大致资源占用&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;cAdvisor&lt;/td&gt;
&lt;td&gt;约 50–150MB 内存&lt;/td&gt;
&lt;td&gt;和容器数量正相关，容器越多它越忙&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Prometheus&lt;/td&gt;
&lt;td&gt;约 200MB–1GB 内存&lt;/td&gt;
&lt;td&gt;主要花在数据留存上：15 秒抓一次、几十个容器、留 15 天，磁盘占用通常在几个 GB 量级&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Grafana&lt;/td&gt;
&lt;td&gt;约 100–200MB 内存&lt;/td&gt;
&lt;td&gt;很省，主要是画图时有点 CPU&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;留存策略的核心就是部署时那个参数：&lt;code&gt;--storage.tsdb.retention.time=15d&lt;/code&gt;。想省磁盘就改成 &lt;code&gt;7d&lt;/code&gt;，想留一个月排查慢性问题就改成 &lt;code&gt;30d&lt;/code&gt;，按磁盘大小和排查习惯权衡。改完重启 Prometheus 生效。另外可以顺手用 &lt;code&gt;docker stats&lt;/code&gt; 观察几天这三个容器自己的占用，心里有个数——监控把宿主机挤垮就本末倒置了。&lt;/p&gt;
&lt;p&gt;:::warning
1 核 1GB 级别的小机器&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要硬上这套三件套&amp;lt;/span&amp;gt;，光 Prometheus 和 Grafana 就能吃掉小半内存。这种机器用下面说的轻量探针就够了，需要看曲线时临时在本地电脑上连过去查也行。
:::&lt;/p&gt;
&lt;h2&gt;定位区别：和 Uptime Kuma、Komari 怎么分工&lt;/h2&gt;
&lt;p&gt;这套三件套不是万能的，它和常见的两个轻量工具是&lt;strong&gt;分工&lt;/strong&gt;关系，不是替代关系：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;工具&lt;/th&gt;
&lt;th&gt;回答的问题&lt;/th&gt;
&lt;th&gt;粒度&lt;/th&gt;
&lt;th&gt;资源成本&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Uptime Kuma&lt;/td&gt;
&lt;td&gt;服务&lt;strong&gt;活没活&lt;/strong&gt;（HTTP/端口通不通）&lt;/td&gt;
&lt;td&gt;分钟级探活&lt;/td&gt;
&lt;td&gt;极低&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Komari 等探针面板&lt;/td&gt;
&lt;td&gt;机器&lt;strong&gt;大概怎么样&lt;/strong&gt;（在线状态、负载、流量概览）&lt;/td&gt;
&lt;td&gt;秒级概览&lt;/td&gt;
&lt;td&gt;低&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;cAdvisor + Prometheus + Grafana&lt;/td&gt;
&lt;td&gt;容器&lt;strong&gt;为什么出问题&lt;/strong&gt;（哪项资源、从何时起、涨得多快）&lt;/td&gt;
&lt;td&gt;秒级指标 + 历史曲线 + 规则告警&lt;/td&gt;
&lt;td&gt;中高&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一句话概括：Kuma 管「死没死」，探针管「多台机器一眼扫过去谁不对劲」，这套三件套管「定位到具体容器、具体资源、具体时间点」。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;轻量工具负责发现异常，三件套负责查清原因&amp;lt;/span&amp;gt;，已经在用 Kuma 或探针的完全不用拆，把这套补在需要深挖的主力机上即可，别每台机器都重复建设。&lt;/p&gt;
&lt;h2&gt;实战：用这套监控定位一次内存缓慢上涨&lt;/h2&gt;
&lt;p&gt;把工具用起来才算数，这里走一遍最典型的场景：某台机器隔几天就要手动重启一次容器，重启完好几天，然后又慢慢变卡，始终不知道是谁干的。&lt;/p&gt;
&lt;p&gt;第一步，先在 Grafana 的内存面板把时间范围拉到最近 7 天。&lt;code&gt;docker stats&lt;/code&gt; 永远看不到的画面出现了：十几个容器里，大部分是平的，只有一条线在以非常均匀的斜率一路向上爬，中间每次陡降都是你手动重启它的时刻——这就是典型的内存泄漏曲线，缓慢、持续、不回头。&lt;/p&gt;
&lt;p&gt;第二步，确认涨势和速率。把那个容器的名字代入内存排行和速率查询，看它每天大概涨多少。PromQL 里没有直接的「内存变化速率」常用指标，但可以借 &lt;code&gt;deriv()&lt;/code&gt; 或者干脆用一段时间窗口的首尾差来估算，比如用 &lt;code&gt;container_memory_working_set_bytes{name=&quot;xxx&quot;} - (container_memory_working_set_bytes{name=&quot;xxx&quot;} offset 24h)&lt;/code&gt; 算出它 24 小时涨了多少字节。能算出每天涨 200MB、机器总共 4GB 内存，什么时候会被吃满就一目了然了。&lt;/p&gt;
&lt;p&gt;第三步，找规律。把时间轴缩到 1 小时粒度，看上涨是匀速的还是台阶式的：如果每次某个定时任务跑完就跳一截，问题多半出在那批任务处理的代码路径上；如果是匀速上涨，则更像连接、缓存、会话这类只进不出的结构在堆积。再把 CPU 和网络曲线叠在一起看时间点是否对得上，证据链就完整了。&lt;/p&gt;
&lt;p&gt;第四步，处理和验证。定位到容器只是开始：该升级镜像的升级、该给容器加内存上限的加上限（限制写法的细节见安全与资源限制篇），处理完之后继续盯着同一条曲线看两三天，斜率消失了才算真修好。这正是历史曲线最大的价值——它不只帮你找到问题，还能帮你确认问题真的没了，而不是自我安慰。&lt;/p&gt;
&lt;p&gt;顺带说一个使用习惯：Grafana 里建议固定留三个视图——全机总览（一屏看所有容器的 CPU 和内存，扫一眼就知道谁不对劲）、单容器详情（出事时点进去深挖）、宿主机视图（配了 node-exporter 才有，看磁盘和整机负载）。视图不在多，顺手最重要，平时打开总览扫十秒，没事就关掉，有异常再往深里点。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;h3&gt;Prometheus 的 Targets 显示 DOWN&lt;/h3&gt;
&lt;p&gt;打开 Prometheus 界面（&lt;code&gt;http://127.0.0.1:9090/targets&lt;/code&gt;），每个抓取目标都有状态。cAdvisor 显示 DOWN 时按顺序查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;看 DOWN 旁边写的错误信息，&lt;code&gt;connection refused&lt;/code&gt; 是对方没起来或端口不对，&lt;code&gt;context deadline exceeded&lt;/code&gt; 是超时、对方卡了；&lt;/li&gt;
&lt;li&gt;确认 cAdvisor 容器本身在跑：&lt;code&gt;docker compose ps&lt;/code&gt; 看状态，挂了就 &lt;code&gt;docker logs cadvisor&lt;/code&gt; 看它为什么退出（最常见是四个卷挂载路径在宿主机上不存在或权限不对）；&lt;/li&gt;
&lt;li&gt;确认两个容器在同一 Compose 网络、目标写的是服务名 &lt;code&gt;cadvisor&lt;/code&gt; 而不是 &lt;code&gt;localhost&lt;/code&gt;——在 Prometheus 容器里，&lt;code&gt;localhost&lt;/code&gt; 指的是它自己，这是新手最常踩的坑。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;Grafana 里查不到数据&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;先回 Prometheus 界面自己写一条最简单的查询，比如 &lt;code&gt;container_memory_usage_bytes&lt;/code&gt;，能查到说明数据没问题，锅在 Grafana 侧；&lt;/li&gt;
&lt;li&gt;查不到则说明抓取环节断了，回到上一条看 Targets；&lt;/li&gt;
&lt;li&gt;Prometheus 有数据、Grafana 没数据，重点查数据源 URL 是否写对（应该是 &lt;code&gt;http://prometheus:9090&lt;/code&gt;）、Save &amp;amp; test 是否通过；&lt;/li&gt;
&lt;li&gt;数据源没问题但面板空白，多半是导入的仪表盘用的指标名或标签和你这版 cAdvisor 对不上，在面板的查询编辑器里把 PromQL 复制到 Prometheus 界面验证一遍，改成能查出结果的写法。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;cAdvisor 指标为空或缺失&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;进 cAdvisor 自带界面点任意容器，如果界面里也没数据，是采集本身没工作，优先查四个卷是否都正确挂载（&lt;code&gt;docker inspect cadvisor&lt;/code&gt; 看 Mounts），尤其是 &lt;code&gt;/sys&lt;/code&gt; 和 &lt;code&gt;/var/lib/docker/&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;只有宿主机级指标缺、容器指标正常，按前文说明补 &lt;code&gt;privileged: true&lt;/code&gt; 后重建再看；&lt;/li&gt;
&lt;li&gt;指标有但 Prometheus 里搜不到，检查抓取间隔内 cAdvisor 是否重启过（计数器归零会让 &lt;code&gt;rate()&lt;/code&gt; 短暂异常），等两个抓取周期再看；&lt;/li&gt;
&lt;li&gt;内存指标看着比 &lt;code&gt;docker stats&lt;/code&gt; 大一截，通常不是错——&lt;code&gt;container_memory_usage_bytes&lt;/code&gt; 含文件缓存，看「真实压力」改用 &lt;code&gt;container_memory_working_set_bytes&lt;/code&gt;，两个指标的口径区别在前面的速览表里写了。&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;docker stats&lt;/code&gt; 只能看当下，历史、曲线、告警这三样必须靠正经监控补齐；&lt;/li&gt;
&lt;li&gt;分工记牢：cAdvisor 采集、Prometheus 存储与查询、Grafana 出图与告警，数据是被 Prometheus 定时拉走的；&lt;/li&gt;
&lt;li&gt;部署的命门就三处：cAdvisor 的四个只读挂载、Prometheus 和 Grafana 的数据卷、三个端口只绑 &lt;code&gt;127.0.0.1&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;PromQL 先掌握 &lt;code&gt;rate()&lt;/code&gt;、&lt;code&gt;increase()&lt;/code&gt;、&lt;code&gt;changes()&lt;/code&gt; 和五个示例，出事时能自己查才是这套东西的真正价值；&lt;/li&gt;
&lt;li&gt;告警规则记得加 &lt;code&gt;for: 5m&lt;/code&gt; 这类持续时间，过滤毛刺；通知渠道 Prometheus 路线和 Grafana 路线二选一；&lt;/li&gt;
&lt;li&gt;上之前先算资源账，小机器用轻量探针，主力机再上三件套，和 Uptime Kuma、Komari 分工配合，不重复建设。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>一台服务器多项目生产实战</title><link>https://www.anexns.cloudns.org/posts/docker-multi-project-prod/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-multi-project-prod/</guid><description>系列收官整合篇：一台服务器上同时跑十个项目也不乱——目录与命名规范、每项目独立网络与资源配额、统一反向代理入口、日志备份监控的整体方案，外加一份上线巡检清单。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;写到这一篇，前面所有单点知识都要收口了。部署、网络、日志、安全、备份、监控、反向代理，每一篇单看都成立，但真把它们一起搬上同一台服务器跑生产，问题立刻换了一副面孔：不再是「某个功能不会用」，而是「十个项目互相干扰、一起出事」。这篇就是整合篇，给出一套能长期维护的单机多项目整体方案：一项目一目录一 Compose、网络与资源双隔离、一个反代统一出口、日志备份监控全部走全局基线，最后附一张上线巡检清单。&lt;/p&gt;
&lt;h2&gt;先看乱象：单机多项目跑久了会出什么事&lt;/h2&gt;
&lt;p&gt;如果你已经在一台服务器上堆了几个月容器，下面这些场景大概率眼熟。先把乱象列清楚，后文每一节都是在逐条拆解它们：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;乱象&lt;/th&gt;
&lt;th&gt;典型事故&lt;/th&gt;
&lt;th&gt;根因&lt;/th&gt;
&lt;th&gt;本篇解法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;端口大杂烩&lt;/td&gt;
&lt;td&gt;新项目 &lt;code&gt;docker compose up&lt;/code&gt; 直接报 &lt;code&gt;port is already allocated&lt;/code&gt;，或者更糟——抢注成功，老项目被顶掉&lt;/td&gt;
&lt;td&gt;所有项目都往宿主机乱绑端口，没有登记、没有规划&lt;/td&gt;
&lt;td&gt;端口只绑 &lt;code&gt;127.0.0.1&lt;/code&gt; 且仅在确有必要时绑，对外统一走反代（第五节）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;资源无上限&lt;/td&gt;
&lt;td&gt;一个项目内存泄漏，OOM Killer 先杀掉的却是隔壁的数据库，整台机器一起陪葬&lt;/td&gt;
&lt;td&gt;容器默认可以吃满整机 CPU 和内存&lt;/td&gt;
&lt;td&gt;每项目资源配额模板，提前圈好上限（第四节）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;日志爆盘&lt;/td&gt;
&lt;td&gt;某天凌晨磁盘 100%，所有容器写不进去集体异常，排查半天发现是一个跑了三个月的容器日志写了 40 GB&lt;/td&gt;
&lt;td&gt;没给日志做轮转基线，&lt;code&gt;docker system df&lt;/code&gt; 从没看过&lt;/td&gt;
&lt;td&gt;&lt;code&gt;daemon.json&lt;/code&gt; 全局日志基线 + 单项目覆盖（第六节）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;改一处崩一片&lt;/td&gt;
&lt;td&gt;给 A 项目加个环境变量，顺手 &lt;code&gt;docker compose down&lt;/code&gt; 了共用的那份大杂烩 Compose 文件，B、C 项目跟着下线&lt;/td&gt;
&lt;td&gt;多个项目挤在同一份 Compose、同一个默认网络里，命运被绑在一起&lt;/td&gt;
&lt;td&gt;一项目一目录一 Compose，网络各自独立（第二、四节）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;网络全互通&lt;/td&gt;
&lt;td&gt;所有容器都在默认 &lt;code&gt;bridge&lt;/code&gt; 或同一张网里，任何一个服务被攻破，攻击者能直接横向访问所有项目的数据库&lt;/td&gt;
&lt;td&gt;没有做网络隔离，数据库端口在容器网络里对所有人敞开&lt;/td&gt;
&lt;td&gt;每项目独立网络，只有反代进公共网络（第四节）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;备份靠想起来&lt;/td&gt;
&lt;td&gt;磁盘坏了才发现：数据卷从没备份过，Compose 文件改过十几版，一版都没存档&lt;/td&gt;
&lt;td&gt;没有固定的备份节奏，配置没有版本管理&lt;/td&gt;
&lt;td&gt;卷定时备份 + 配置进 Git（第六节）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;更新一锅烩&lt;/td&gt;
&lt;td&gt;Watchtower 半夜把十个项目全更新了，其中一个新版不兼容，早上起来全线飘红还没法快速定位&lt;/td&gt;
&lt;td&gt;更新没有分批，没有分组，没有回滚预案&lt;/td&gt;
&lt;td&gt;按项目分批更新、关键服务手动更新（第七节）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;看完这张表，结论其实很朴素：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;单机多项目能不能长期稳定，不取决于单点技术多熟练，而取决于有没有一套所有项目共同遵守的规范&amp;lt;/span&amp;gt;。规范立住了，十个项目和两个项目的管理成本差不多；规范立不住，三个项目就能乱成一团。&lt;/p&gt;
&lt;h2&gt;目录规范：一项目一目录，一目录一 Compose&lt;/h2&gt;
&lt;p&gt;所有项目统一放在 &lt;code&gt;/opt&lt;/code&gt; 下，一个项目一个目录，目录名就是项目名。每个目录里自成一套：Compose 文件、环境变量、配置、数据，互不借用、互不引用。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/opt/
├── edge/                      # 统一入口：反向代理（独立项目，见第五节）
│   ├── compose.yaml
│   └── Caddyfile
├── blog/
│   ├── compose.yaml
│   ├── .env                   # 本项目的密钥与变量，不进 Git
│   ├── .env.example           # 变量清单模板，进 Git
│   ├── config/                # 挂载给容器的配置文件
│   └── data/                  # 绑定挂载的数据目录（或改用命名卷）
├── cloud/
│   ├── compose.yaml
│   ├── .env
│   └── data/
├── monitor/
│   ├── compose.yaml
│   └── .env
└── backup/                    # 备份脚本与备份落点（也可直接同步到异地）
    ├── backup-all.sh
    └── logs/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这套结构有三条硬规矩：&lt;/p&gt;
&lt;p&gt;第一，&lt;strong&gt;一项目一 Compose 文件&lt;/strong&gt;，永远不要把多个不相关的项目写进同一份 &lt;code&gt;compose.yaml&lt;/code&gt;。项目之间唯一的耦合点是第五节那张公共网络，除此之外谁下线都不影响别人。Compose 的基本写法和 &lt;code&gt;project&lt;/code&gt; 概念在&lt;a href=&quot;/posts/linux-docker-compose/&quot;&gt;部署篇&lt;/a&gt;里讲透了，这里只强调组织方式。&lt;/p&gt;
&lt;p&gt;第二，&lt;strong&gt;&lt;code&gt;.env&lt;/code&gt; 单独管，且不进 Git&lt;/strong&gt;。密钥、密码、Token 只存在于各项目自己的 &lt;code&gt;.env&lt;/code&gt; 里；仓库里只提交 &lt;code&gt;.env.example&lt;/code&gt;，列出变量名和示例值。这样配置可以放心版本化，密钥又不外泄。反面教材是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把真实密码写进 compose.yaml 再推到公开仓库&amp;lt;/span&amp;gt;，机器人几分钟内就能扫到并拿去挖矿或勒索，这类事故每个月都在发生。&lt;/p&gt;
&lt;p&gt;第三，&lt;strong&gt;数据与配置分离&lt;/strong&gt;。&lt;code&gt;config/&lt;/code&gt; 是人写的、可以进 Git 的；&lt;code&gt;data/&lt;/code&gt;（或命名卷）是程序生成的、走备份流程的。恢复一个项目时逻辑很清晰：配置从 Git 拉，数据从备份回，两条线不混。&lt;/p&gt;
&lt;p&gt;数据库这类有状态服务，优先用命名卷而不是随手绑定挂载到某个临时路径，卷的命名、备份与恢复方法见&lt;a href=&quot;/posts/docker-volumes-backup/&quot;&gt;数据卷与备份篇&lt;/a&gt;。无状态的 Web 服务则怎么方便怎么来。&lt;/p&gt;
&lt;h2&gt;命名规范：前缀统一，见名知意&lt;/h2&gt;
&lt;p&gt;项目多了之后，&lt;code&gt;docker ps&lt;/code&gt; 满屏都是 &lt;code&gt;app&lt;/code&gt;、&lt;code&gt;web&lt;/code&gt;、&lt;code&gt;db&lt;/code&gt;、&lt;code&gt;redis&lt;/code&gt; 这种名字，根本分不清属于谁。解决办法是所有资源统一加项目名前缀：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;资源&lt;/th&gt;
&lt;th&gt;命名规则&lt;/th&gt;
&lt;th&gt;示例（项目 blog）&lt;/th&gt;
&lt;th&gt;示例（项目 cloud）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;项目目录&lt;/td&gt;
&lt;td&gt;项目名本身&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/opt/blog&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/opt/cloud&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Compose 项目名&lt;/td&gt;
&lt;td&gt;与目录名一致（&lt;code&gt;name:&lt;/code&gt; 显式写明）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;blog&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;cloud&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;容器名&lt;/td&gt;
&lt;td&gt;项目名-角色&lt;/td&gt;
&lt;td&gt;&lt;code&gt;blog-web&lt;/code&gt;、&lt;code&gt;blog-db&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;cloud-app&lt;/code&gt;、&lt;code&gt;cloud-db&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;自定义网络&lt;/td&gt;
&lt;td&gt;项目名-net&lt;/td&gt;
&lt;td&gt;&lt;code&gt;blog-net&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;cloud-net&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;命名卷&lt;/td&gt;
&lt;td&gt;项目名-数据名&lt;/td&gt;
&lt;td&gt;&lt;code&gt;blog-dbdata&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;cloud-uploads&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;镜像（自建）&lt;/td&gt;
&lt;td&gt;项目名/服务名:版本&lt;/td&gt;
&lt;td&gt;&lt;code&gt;blog/web:1.4.0&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;cloud/api:2.1.3&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;Compose 文件开头把项目名写死，不要依赖目录名自动推导，搬目录时才不会串味：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;name: blog

services:
  web:
    image: blog/web:1.4.0
    container_name: blog-web
    # ...
  db:
    image: postgres:16-alpine
    container_name: blog-db
    # ...
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;container_name&lt;/code&gt; 写死之后，这个服务就不能再扩容多副本了（名字会冲突）。单机多项目场景绝大多数服务都是单副本，写死名字换来的是运维时一眼可辨；真需要多副本的服务，去掉这一行、靠 Compose 自动命名即可。另外，自建镜像一律打明确版本号，生产环境不要用 latest 当唯一标签，出事时你连回滚到哪一版都说不清。&lt;/p&gt;
&lt;h2&gt;隔离三件套：网络、资源、端口&lt;/h2&gt;
&lt;p&gt;隔离是这篇的核心。三个维度一起上，任何一个项目出问题，都被关在自己的笼子里。&lt;/p&gt;
&lt;h3&gt;网络隔离：每项目一张自己的网&lt;/h3&gt;
&lt;p&gt;每个项目在自己的 Compose 里声明一张自定义网络，本项目的所有服务都进这张网；项目内部用服务名互相访问（比如 Web 连 &lt;code&gt;db:5432&lt;/code&gt;），项目之间则完全不通。网络模型、自定义网络与容器间通信的原理见&lt;a href=&quot;/posts/docker-network/&quot;&gt;网络篇&lt;/a&gt;，这里给多项目落地的固定写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;name: blog

services:
  web:
    image: blog/web:1.4.0
    container_name: blog-web
    networks:
      - blog-net        # 项目内通信
      - edge            # 只把需要被反代访问的服务额外挂到公共网络
  db:
    image: postgres:16-alpine
    container_name: blog-db
    networks:
      - blog-net        # 数据库只进项目内网，坚决不挂 edge

networks:
  blog-net:
    name: blog-net
  edge:
    external: true      # 由 edge 项目统一创建，见第五节
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;关键在数据库：它只出现在 &lt;code&gt;blog-net&lt;/code&gt; 里，&lt;code&gt;cloud&lt;/code&gt; 项目的任何容器都解析不到 &lt;code&gt;blog-db&lt;/code&gt; 这个名字，更连不上。这样即便某个项目的 Web 层被攻破，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;攻击者也摸不到其他项目的数据库&amp;lt;/span&amp;gt;，横向移动在容器网络这一层就被切断。&lt;/p&gt;
&lt;h3&gt;资源隔离：每项目一份配额模板&lt;/h3&gt;
&lt;p&gt;容器默认能吃满整机资源，必须用配额圈住。下面这段是本系列的通用模板，直接抄进每个项目的每个服务，按项目体量改数字。配额参数的含义、CPU 与内存限制的区别在&lt;a href=&quot;/posts/docker-security-resources/&quot;&gt;安全与资源篇&lt;/a&gt;里有详解，这里给生产可用的组合：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  web:
    image: blog/web:1.4.0
    deploy:
      resources:
        limits:
          cpus: &quot;1.0&quot;          # 最多用 1 核
          memory: 512M         # 硬上限，超了触发 OOM Kill（只杀自己）
        reservations:
          cpus: &quot;0.25&quot;         # 保底份额，整机繁忙时优先保障
          memory: 128M
    mem_swappiness: 0          # 可选：减少被换出到 swap 的倾向
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;deploy.resources&lt;/code&gt; 在 Docker Compose V2 里执行 &lt;code&gt;docker compose up&lt;/code&gt; 时是生效的（这是新版 Compose 规范的行为，和 Swarm 无关），不要被老资料里「deploy 只对 Swarm 有效」的说法误导。验证方法很简单：容器起来后 &lt;code&gt;docker inspect&lt;/code&gt; 看 &lt;code&gt;HostConfig&lt;/code&gt; 里的 &lt;code&gt;Memory&lt;/code&gt; 与 &lt;code&gt;NanoCpus&lt;/code&gt;，或者 &lt;code&gt;docker stats&lt;/code&gt; 观察上限是否吻合。
:::&lt;/p&gt;
&lt;p&gt;配额数字怎么定：先用 &lt;code&gt;docker stats&lt;/code&gt; 观察一周拿到各服务的日常水位，limits 给到水位的 1.5～2 倍，数据库这类关键服务再多给一点。宁可一开始给宽些再收紧，也不要拍脑袋给个小数字——内存上限给太小，容器会被反复 OOM Kill，表面看是「服务老重启」，实际是自己把自己掐死。&lt;/p&gt;
&lt;h3&gt;端口隔离：只绑 127.0.0.1，对外只留一个出口&lt;/h3&gt;
&lt;p&gt;除反代之外，任何项目的端口都不直接暴露到公网。确有调试或本机访问需要的，绑到回环地址：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ports:
  - &quot;127.0.0.1:8080:80&quot;    # 只有本机能访问，外网扫不到
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;绝大多数服务连这一行都不需要写：反代和它在同一张 &lt;code&gt;edge&lt;/code&gt; 网络里，直接用容器名加内部端口访问即可，根本不用经过宿主机端口。宿主机上真正对公网开放的，理想状态下只有 SSH 和反代的 80/443。端口越少，攻击面越小，这也是&lt;a href=&quot;/posts/docker-security-resources/&quot;&gt;安全与资源篇&lt;/a&gt;反复强调的最小暴露原则。&lt;/p&gt;
&lt;h2&gt;统一入口：一张公共网络加一个反代&lt;/h2&gt;
&lt;p&gt;所有项目的对外流量收拢到一个反代上：域名、HTTPS 证书、访问日志都在这一个点解决，新项目接入不用再碰宿主机防火墙。&lt;/p&gt;
&lt;p&gt;做法是先建一张全局公共网络，由 &lt;code&gt;edge&lt;/code&gt; 项目（即反代自己）创建，其他项目以 &lt;code&gt;external: true&lt;/code&gt; 的方式挂载——第四节的 Compose 片段里已经出现了它：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker network create edge
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;反代二选一：配置灵活、生态成熟选 Nginx，写法见&lt;a href=&quot;/posts/docker-nginx-https/&quot;&gt;用 Docker 部署 Nginx 反向代理与自动 HTTPS&lt;/a&gt;；想省心、证书全自动选 Caddy，写法见&lt;a href=&quot;/posts/docker-caddy-https/&quot;&gt;用 Docker 部署 Caddy：自动 HTTPS 反向代理&lt;/a&gt;。以 Caddy 为例，&lt;code&gt;edge&lt;/code&gt; 项目的 Caddyfile 里每个项目一段，按容器名反代：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;blog.example.com {
    reverse_proxy blog-web:80
}

cloud.example.com {
    reverse_proxy cloud-app:8080
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;新项目接入固定三步，照着走不会乱：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;项目自己的 Compose 里，把需要对外的服务额外挂上 &lt;code&gt;edge&lt;/code&gt; 网络（数据库等内部服务不挂）。&lt;/li&gt;
&lt;li&gt;在 Caddyfile（或 Nginx 配置）里加一段：新域名指向新容器名与内部端口，重载反代。&lt;/li&gt;
&lt;li&gt;把新域名解析到本机，证书由反代自动签发，完事。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;整个过程不重启任何已有项目，反代重载也是平滑的。哪天某个项目要下线，同样反着来：删反代配置段、停项目、删解析，其他项目毫无感知。&lt;/p&gt;
&lt;h2&gt;全局基线：日志、备份与配置版本化&lt;/h2&gt;
&lt;p&gt;单项目的细节前面各篇都讲过，这里定的是「所有项目统一执行」的基线数值，新项目上线即套用，不再逐个商量。&lt;/p&gt;
&lt;h3&gt;日志基线&lt;/h3&gt;
&lt;p&gt;在 &lt;code&gt;/etc/docker/daemon.json&lt;/code&gt; 里给所有容器兜底（单项目也可在 Compose 里用 &lt;code&gt;logging&lt;/code&gt; 段单独覆盖），日志驱动与轮转参数见&lt;a href=&quot;/posts/docker-logging/&quot;&gt;日志管理篇&lt;/a&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;log-driver&quot;: &quot;json-file&quot;,
  &quot;log-opts&quot;: {
    &quot;max-size&quot;: &quot;20m&quot;,
    &quot;max-file&quot;: &quot;3&quot;
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;单文件 20 MB、保留 3 个，一容器日志最多占 60 MB。十个项目、几十个容器，最坏情况也就几个 GB，再也不会出现日志把磁盘写爆的事故。改完 &lt;code&gt;daemon.json&lt;/code&gt; 需要重启 Docker 守护进程（会短暂影响全部容器），挑低峰期做，且&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;重启前务必确认所有项目都设置了 unless-stopped 或 always 重启策略&amp;lt;/span&amp;gt;，否则重启完一地手动拉起的活。&lt;/p&gt;
&lt;h3&gt;备份与配置基线&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对象&lt;/th&gt;
&lt;th&gt;策略&lt;/th&gt;
&lt;th&gt;频率&lt;/th&gt;
&lt;th&gt;保留&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;命名卷 / 数据目录&lt;/td&gt;
&lt;td&gt;停写或快照后打包，脚本统一执行&lt;/td&gt;
&lt;td&gt;每天凌晨一次&lt;/td&gt;
&lt;td&gt;本地 7 天，异地 30 天&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据库&lt;/td&gt;
&lt;td&gt;用自带导出工具做逻辑备份（&lt;code&gt;pg_dump&lt;/code&gt;、&lt;code&gt;mysqldump&lt;/code&gt; 等），不要只拷数据文件&lt;/td&gt;
&lt;td&gt;每天一次，重要库可加中午一次&lt;/td&gt;
&lt;td&gt;同上&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;各项目 Compose 与配置&lt;/td&gt;
&lt;td&gt;全部进 Git 仓库（&lt;code&gt;.env&lt;/code&gt; 除外）&lt;/td&gt;
&lt;td&gt;每次改动即提交&lt;/td&gt;
&lt;td&gt;Git 历史即版本线&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.env&lt;/code&gt; 密钥&lt;/td&gt;
&lt;td&gt;单独加密备份一份到密码管理器或离线介质&lt;/td&gt;
&lt;td&gt;每次变更时&lt;/td&gt;
&lt;td&gt;长期&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;备份本身&lt;/td&gt;
&lt;td&gt;定期做恢复演练，抽一个卷实际还原验证&lt;/td&gt;
&lt;td&gt;每季度一次&lt;/td&gt;
&lt;td&gt;——&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;备份的具体命令与卷打包方法见&lt;a href=&quot;/posts/docker-volumes-backup/&quot;&gt;数据卷与备份篇&lt;/a&gt;。这里只强调一条铁律：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;没做过恢复验证的备份，等于没有备份&amp;lt;/span&amp;gt;。备份脚本跑成功只证明「写出去了」，恢复演练才证明「拿得回来」。&lt;/p&gt;
&lt;h2&gt;更新与监控：分批、分组、留后路&lt;/h2&gt;
&lt;h3&gt;更新策略：按项目分批，不要一锅烩&lt;/h3&gt;
&lt;p&gt;自动更新工具 Watchtower 的用法见&lt;a href=&quot;/posts/linux-docker-auto-update/&quot;&gt;自动更新篇&lt;/a&gt;，多项目场景要给它加约束：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;项目类型&lt;/th&gt;
&lt;th&gt;更新策略&lt;/th&gt;
&lt;th&gt;理由&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;无状态小服务（博客、静态站、工具类）&lt;/td&gt;
&lt;td&gt;Watchtower 自动更新，错峰到凌晨低峰&lt;/td&gt;
&lt;td&gt;挂了影响小，新版收益（安全修复）大于风险&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;有状态服务（数据库、网盘、带数据的应用）&lt;/td&gt;
&lt;td&gt;关闭自动更新，手动看更新日志后升级&lt;/td&gt;
&lt;td&gt;数据格式变更、迁移脚本出问题都是大事，必须人在场&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;反代、监控等基础设施&lt;/td&gt;
&lt;td&gt;手动更新，且单独安排时间&lt;/td&gt;
&lt;td&gt;它们一挂，全站一起挂，不能和业务项目同批&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;给 Watchtower 分组靠的是标签（label）：只给允许自动更新的容器打上启用标签，其余一律不碰；或者干脆跑两个 Watchtower 实例，分别管不同批次。再加一条：任何自动更新都要接通知（更新了谁、从哪版到哪版），第二天扫一眼通知，出问题能立刻对上时间线。&lt;/p&gt;
&lt;h3&gt;监控分工：三个层次各管一段&lt;/h3&gt;
&lt;p&gt;监控不要指望一个工具包打天下，按层次分工（指标体系的搭建见&lt;a href=&quot;/posts/docker-monitoring-prometheus/&quot;&gt;容器监控篇：cAdvisor + Prometheus + Grafana&lt;/a&gt;）：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;层次&lt;/th&gt;
&lt;th&gt;回答的问题&lt;/th&gt;
&lt;th&gt;工具思路&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;存活监控&lt;/td&gt;
&lt;td&gt;服务还活着吗、域名还能打开吗&lt;/td&gt;
&lt;td&gt;HTTP/端口探测，挂了立刻推送告警&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;资源指标&lt;/td&gt;
&lt;td&gt;CPU、内存、网络、磁盘水位涨到哪了&lt;/td&gt;
&lt;td&gt;cAdvisor + Prometheus + Grafana 看趋势&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;业务探针&lt;/td&gt;
&lt;td&gt;关键接口返回是否正确、证书还有几天到期&lt;/td&gt;
&lt;td&gt;定时脚本请求接口并校验内容，证书到期单独提醒&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;其中磁盘水位是最容易被忽视又最致命的一项，给一条明确阈值：&lt;strong&gt;根分区使用率到 80% 预警、90% 告警&lt;/strong&gt;，并把 &lt;code&gt;docker system df&lt;/code&gt; 的结果纳入日常巡检——悬空镜像、无主卷、构建缓存攒几个月，同样能悄悄吃掉几十 GB。清理时只清明确无用的部分，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要图省事直接 docker system prune -a 一把梭&amp;lt;/span&amp;gt;，它会把停着但还要用的镜像和卷一起带走，生产机上这一条命令的破坏力堪比删库。&lt;/p&gt;
&lt;h2&gt;上线巡检清单：新项目上线前逐项打勾&lt;/h2&gt;
&lt;p&gt;每个新项目接入这台服务器之前，按这张表走一遍，全部打勾才算上线完成。老项目每季度也拿它复查一次：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;#&lt;/th&gt;
&lt;th&gt;检查项&lt;/th&gt;
&lt;th&gt;通过标准&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;目录与命名&lt;/td&gt;
&lt;td&gt;在 &lt;code&gt;/opt/&amp;lt;项目名&amp;gt;/&lt;/code&gt; 下，Compose 写明 &lt;code&gt;name:&lt;/code&gt;，容器/网络/卷都带项目前缀&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;端口暴露&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker ps&lt;/code&gt; 检查：除反代外无 &lt;code&gt;0.0.0.0&lt;/code&gt; 绑定，调试端口只绑 &lt;code&gt;127.0.0.1&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;资源配额&lt;/td&gt;
&lt;td&gt;每个服务都有 CPU 与内存 limits，&lt;code&gt;docker stats&lt;/code&gt; 核对生效&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;网络隔离&lt;/td&gt;
&lt;td&gt;数据库等内部服务只在项目内网，未挂 &lt;code&gt;edge&lt;/code&gt;；跨项目容器名互不解析&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;日志轮转&lt;/td&gt;
&lt;td&gt;命中全局 &lt;code&gt;daemon.json&lt;/code&gt; 基线或项目自有 &lt;code&gt;logging&lt;/code&gt; 配置，无无限增长的日志&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;密钥管理&lt;/td&gt;
&lt;td&gt;真实密钥只在 &lt;code&gt;.env&lt;/code&gt;，仓库里只有 &lt;code&gt;.env.example&lt;/code&gt;，无明文密码进 Git&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;备份接入&lt;/td&gt;
&lt;td&gt;数据卷已加入统一备份脚本并实际跑通一次，恢复路径明确&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;8&lt;/td&gt;
&lt;td&gt;更新策略&lt;/td&gt;
&lt;td&gt;已明确归入自动/手动批次，Watchtower 标签与本项目策略一致&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;9&lt;/td&gt;
&lt;td&gt;监控接入&lt;/td&gt;
&lt;td&gt;存活探测已添加，域名与关键接口在监控列表内&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;10&lt;/td&gt;
&lt;td&gt;域名与证书&lt;/td&gt;
&lt;td&gt;反代配置段就位，HTTPS 可正常访问，证书自动续期链路完整&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;11&lt;/td&gt;
&lt;td&gt;重启自恢复&lt;/td&gt;
&lt;td&gt;服务设了 &lt;code&gt;unless-stopped&lt;/code&gt; 或 &lt;code&gt;always&lt;/code&gt;，手动重启宿主机（或模拟）后能自动回来&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;12&lt;/td&gt;
&lt;td&gt;回滚预案&lt;/td&gt;
&lt;td&gt;镜像保留上一个版本号，知道出事时改哪个标签、执行哪条命令回退&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这张表打印出来贴在文档首页都不过分。它不高级，但生产事故里的大多数，恰恰死在这些基础项没人逐条确认过。&lt;/p&gt;
&lt;h2&gt;排障：多项目环境的高频问题&lt;/h2&gt;
&lt;p&gt;:::warning
多项目排障的第一原则是先定位影响面：先确认是单项目问题还是整机问题。用 &lt;code&gt;docker stats&lt;/code&gt; 看整机水位、用 &lt;code&gt;docker ps&lt;/code&gt; 看异常容器状态，能省掉一半瞎猜的时间。
:::&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;症状一：某项目突然打不开，其他项目正常。&lt;/strong&gt; 先查反代：&lt;code&gt;docker logs edge&lt;/code&gt; 看是否有上游连接错误；再查该项目容器是否在反复重启（&lt;code&gt;docker ps&lt;/code&gt; 里 STATUS 显示 Restarting 多半是配额太小被 OOM Kill，或新配置写错）；最后查它有没有被手滑移出 &lt;code&gt;edge&lt;/code&gt; 网络（&lt;code&gt;docker network inspect edge&lt;/code&gt; 看成员列表）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;症状二：所有项目同时变慢或打不开。&lt;/strong&gt; 这是整机问题，按顺序查：&lt;code&gt;df -h&lt;/code&gt; 看磁盘是不是满了（日志、镜像、备份包是三大嫌疑）；&lt;code&gt;docker stats&lt;/code&gt; 看是不是某个容器在狂吃 CPU/内存——如果它没设配额，就是隔离没做全，回到第四节补上；&lt;code&gt;free -h&lt;/code&gt; 与 &lt;code&gt;dmesg | grep -i oom&lt;/code&gt; 看有没有进程被系统杀掉。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;症状三：新项目起不来，报网络或名字冲突。&lt;/strong&gt; 多半是命名没遵守规范：容器名、网络名或卷名和已有项目撞了。&lt;code&gt;docker ps -a&lt;/code&gt;、&lt;code&gt;docker network ls&lt;/code&gt; 对照排查，根治办法是回第二节把前缀补齐。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;症状四：证书突然过期，全站 HTTPS 报警。&lt;/strong&gt; 自动续期失败通常是 80 端口被别的进程占了、域名解析被改过，或反代容器本身异常。先单独访问反代的日志定位续期报错，再逐项核对解析与端口，别急着手动签证书绕过——绕过一次，下个周期还会再炸。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;症状五：磁盘莫名少了几十 GB。&lt;/strong&gt; &lt;code&gt;docker system df -v&lt;/code&gt; 逐项看：镜像、容器可写层、卷、构建缓存谁在膨胀。构建缓存和悬空镜像可以清，卷必须逐个确认归属再动。&lt;/p&gt;
&lt;h2&gt;什么时候该拆出去&lt;/h2&gt;
&lt;p&gt;这套方案能舒服地撑起一台中配服务器上的十来个中小项目，但它有明确的天花板：单机没有高可用，宿主机一挂全挂；资源总量就这么多，项目只增不减迟早见底。判断是否该扩容，看三个信号：整机内存或 CPU 长期水位超过 70%；某个项目开始需要多副本或独立带宽；维护窗口越来越难找（重启一次影响太多项目）。&lt;/p&gt;
&lt;p&gt;处理顺序是先纵向加配置，再把最吃资源或最关键的项目拆到第二台机器（目录规范统一，迁移就是搬目录加改解析），真到了多机协同、需要服务编排与滚动发布的阶段，再考虑上 Swarm 这类集群方案，入门路径见 &lt;a href=&quot;/posts/docker-swarm/&quot;&gt;Docker Swarm 篇&lt;/a&gt;。不要提前上重型架构——单机规范做扎实，比过早上集群重要得多。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;多项目乱象的根源不是技术不行，而是没有共同规范；先立规矩，再谈技巧。&lt;/li&gt;
&lt;li&gt;目录、命名、网络、资源、端口五条规范是地基：一项目一目录一 Compose、资源命名全带前缀、数据库只进内网、每服务必设配额、对外只留反代一个出口。&lt;/li&gt;
&lt;li&gt;日志、备份、更新、监控全部走全局基线，新项目套模板接入，不逐个发明方案。&lt;/li&gt;
&lt;li&gt;上线前过一遍十二项巡检清单，每季度复查一次；备份必须做过恢复验证才作数。&lt;/li&gt;
&lt;li&gt;单机方案有边界，水位、副本、维护窗口三个信号出现时，按加配置、拆项目、上集群的顺序走。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;至此，从单容器入门到多项目生产，整个系列算是闭环了。把这一篇的规范当成默认设置带进每一个新项目，服务器会越用越省心，而不是越用越心慌。&lt;/p&gt;
</content:encoded></item><item><title>Docker 网络详解：从 bridge 到 IPv6</title><link>https://www.anexns.cloudns.org/posts/docker-network/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-network/</guid><description>一篇讲透 Docker 网络：bridge/host/none/macvlan 的区别与选型、端口映射与只绑本机的安全做法、自定义网络的容器互访、IPv6 完整开启方法与网络排障命令。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;上一篇 &lt;a href=&quot;/posts/linux-docker-compose/&quot;&gt;《如何在Linux部署Docker&amp;amp;Compose》&lt;/a&gt; 里，我们用 &lt;code&gt;docker compose up -d&lt;/code&gt; 就把 Nginx 和 Redis 跑起来了，还顺手映射了端口。但很多人对 Docker 网络的理解也就停留在「加一行 ports 就能访问」这一步，一旦遇到容器之间互访不通、端口映射了外网却连不上、想开 IPv6 不知道从哪下手，就会卡住。这篇就把 Docker 网络一次讲透：五种网络模式的原理与选型、端口映射的正确姿势、自定义网络的容器互访、host 模式的实战与坑、IPv6 的完整开启方法，最后给一套排障工具箱。看完这篇，Docker 网络相关的问题你基本都能自己定位。&lt;/p&gt;
&lt;h2&gt;网络模式总览：先建立整体概念&lt;/h2&gt;
&lt;p&gt;容器启动时必须选一种网络模式（&lt;code&gt;--network&lt;/code&gt;），它决定了容器和外界、容器和容器之间怎么通信。Docker 内置了下面几种驱动，先看总览表，后面逐个展开：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;模式&lt;/th&gt;
&lt;th&gt;原理&lt;/th&gt;
&lt;th&gt;优点&lt;/th&gt;
&lt;th&gt;缺点&lt;/th&gt;
&lt;th&gt;适用场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;bridge（默认）&lt;/td&gt;
&lt;td&gt;容器接入虚拟网桥 docker0，各自有独立网段内的 IP，靠 NAT 出网、靠端口映射入网&lt;/td&gt;
&lt;td&gt;隔离性好、最通用&lt;/td&gt;
&lt;td&gt;多一层 NAT，性能略损；默认网络不支持容器名解析&lt;/td&gt;
&lt;td&gt;绝大多数单机应用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;bridge（自定义）&lt;/td&gt;
&lt;td&gt;原理同上，但网段、网关可控，且自带容器名 DNS 解析&lt;/td&gt;
&lt;td&gt;容器可用名字互访、网络可隔离分组&lt;/td&gt;
&lt;td&gt;需要自己规划网段&lt;/td&gt;
&lt;td&gt;多容器项目（Compose 默认就这么做）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;host&lt;/td&gt;
&lt;td&gt;容器直接共用宿主机网络命名空间，没有自己的网卡和 IP&lt;/td&gt;
&lt;td&gt;性能最好、无端口映射概念&lt;/td&gt;
&lt;td&gt;端口直接占用宿主机、隔离性差；仅 Linux 可用&lt;/td&gt;
&lt;td&gt;对网络性能极敏感、或需要监听大量端口的服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;none&lt;/td&gt;
&lt;td&gt;只有回环网卡 lo，完全断网&lt;/td&gt;
&lt;td&gt;绝对隔离&lt;/td&gt;
&lt;td&gt;不能联网&lt;/td&gt;
&lt;td&gt;只做本地计算、批处理类容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;container&lt;/td&gt;
&lt;td&gt;与另一个已有容器共用网络命名空间&lt;/td&gt;
&lt;td&gt;两个容器像同一台机器，用 localhost 互访&lt;/td&gt;
&lt;td&gt;命运绑定，被共享的容器重启会受影响&lt;/td&gt;
&lt;td&gt;伴生容器，如 VPN 容器 + 借道走它的应用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;macvlan&lt;/td&gt;
&lt;td&gt;给容器分配局域网真实 IP 和独立 MAC，像一台独立设备接入物理网络&lt;/td&gt;
&lt;td&gt;容器在局域网里就是一台「真机」&lt;/td&gt;
&lt;td&gt;配置复杂；默认与宿主机不通（需额外处理）&lt;/td&gt;
&lt;td&gt;需要容器直接出现在局域网、接管特定 IP 的场景&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选型口诀：&lt;strong&gt;单机多容器用自定义 bridge（Compose 默认），追求性能或特殊需求再考虑 host，局域网独立 IP 才上 macvlan，none 和 container 是小众特殊场景。&lt;/strong&gt; 下面按重要程度展开。&lt;/p&gt;
&lt;h2&gt;bridge 模式与端口映射&lt;/h2&gt;
&lt;h3&gt;默认 bridge 是什么样&lt;/h3&gt;
&lt;p&gt;不加任何网络参数时，容器都接入默认的 &lt;code&gt;docker0&lt;/code&gt; 网桥，网段通常是 &lt;code&gt;172.17.0.0/16&lt;/code&gt;，容器 IP 从 &lt;code&gt;172.17.0.2&lt;/code&gt; 开始顺序分配。容器访问外网靠宿主机的 NAT 转发，没有任何问题；但外界想访问容器里的服务，就必须做&lt;strong&gt;端口映射&lt;/strong&gt;，把宿主机端口和容器端口绑定。&lt;/p&gt;
&lt;p&gt;先看一下你机器上的网络现状：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker network ls
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;NETWORK ID     NAME      DRIVER    SCOPE
a1b2c3d4e5f6   bridge    bridge    local
b2c3d4e5f6a7   host      host      local
c3d4e5f6a7b8   none      null      local
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;bridge、host、none 三个是 Docker 自带的，不能删除。&lt;/p&gt;
&lt;h3&gt;端口映射的写法&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;docker run&lt;/code&gt; 用 &lt;code&gt;-p&lt;/code&gt;，完整格式是：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-p [宿主机IP:]宿主机端口:容器端口[/协议]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;常见写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 宿主机 8080 → 容器 80，所有网卡可访问（等价于 0.0.0.0:8080）
docker run -d -p 8080:80 nginx

# 只绑本机回环：只有宿主机自己能访问，外网连不进来
docker run -d -p 127.0.0.1:8080:80 nginx

# UDP 端口要显式带 /udp（比如 DNS、游戏服务器、HY2 类服务）
docker run -d -p 53:53/udp mydns

# 一次映射多个
docker run -d -p 8080:80 -p 8443:443 nginx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Compose 里对应的是 &lt;code&gt;ports&lt;/code&gt;，写法一致，&lt;strong&gt;记得加引号&lt;/strong&gt;，避免 YAML 把 &lt;code&gt;8080:80&lt;/code&gt; 这类值误解析：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  nginx:
    image: nginx:latest
    ports:
      - &quot;8080:80&quot;
      - &quot;127.0.0.1:8443:443&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;查看某个容器实际映射了哪些端口：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker port &amp;lt;容器名&amp;gt;
docker ps   # PORTS 列也能直接看到
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;只绑 127.0.0.1：最容易被忽视的安全习惯&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;-p 8080:80&lt;/code&gt; 默认绑的是 &lt;code&gt;0.0.0.0&lt;/code&gt;，也就是&lt;strong&gt;全网可达&lt;/strong&gt;：只要云厂商安全组或防火墙放行，任何人都能连上这个端口。很多数据库、面板类容器出事，就是因为图省事直接把端口暴露到了公网。&lt;/p&gt;
&lt;p&gt;如果这个服务只需要给本机其他程序用，或者前面还有 Nginx 反向代理在转发，就应该只绑回环地址：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d -p 127.0.0.1:3306:3306 mysql
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这样即使防火墙全开，外网也连不进来，本机通过 &lt;code&gt;127.0.0.1:3306&lt;/code&gt; 正常访问。判断原则很简单：&lt;strong&gt;这个端口需要被外网直接访问吗？不需要，就绑 127.0.0.1。&lt;/strong&gt; 数据库、Redis、管理面板，统统属于「不需要」。&lt;/p&gt;
&lt;p&gt;:::warning
Docker 的端口映射是直接写 iptables/nftables 规则的，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;会绕过 ufw 的默认拦截策略&lt;/strong&gt;&amp;lt;/span&amp;gt;。也就是说你在 ufw 里没放行，不代表 Docker 映射的端口外网连不上——这正是「只绑 127.0.0.1」如此重要的原因。不要以为装了 ufw 就万事大吉。
:::&lt;/p&gt;
&lt;h3&gt;userland-proxy=false 是什么意思&lt;/h3&gt;
&lt;p&gt;Docker 做端口映射有两种实现：一种是内核层的 NAT 规则转发；另一种是每个映射端口再起一个用户态代理进程 &lt;code&gt;docker-proxy&lt;/code&gt; 做转发。&lt;code&gt;/etc/docker/daemon.json&lt;/code&gt; 里加上：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;userland-proxy&quot;: false
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;就是关掉那个用户态代理，全部走内核 NAT。好处是少一层转发、性能略好、进程列表更干净，这也是很多长期使用 Docker 的人的固定偏好。代价要知道两个：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;关掉后，&lt;strong&gt;从容器内通过「宿主机 IP + 映射端口」回访自己映射出去的端口可能不通&lt;/strong&gt;（hairpin 场景），容器间通信请走后面讲的自定义网络，不要绕宿主机端口；&lt;/li&gt;
&lt;li&gt;某些依赖代理进程保留源 IP 细节的边缘场景行为会变化，普通使用无感。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;改完 daemon.json 必须重启 Docker 才生效：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl restart docker
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;自定义 bridge 网络：容器互访的正解&lt;/h2&gt;
&lt;h3&gt;默认 bridge 的两个硬伤&lt;/h3&gt;
&lt;p&gt;默认 bridge 能用，但有两个先天不足：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;不支持容器名解析&lt;/strong&gt;。在默认网络里，容器 A 想访问容器 B，只能用 B 的内网 IP（如 172.17.0.3），而 IP 是重启后重新分配的，写死了迟早出事。老旧的 &lt;code&gt;--link&lt;/code&gt; 方案早已被官方废弃，不要再用。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;所有容器挤在一个网络里&lt;/strong&gt;，互相之间毫无隔离，A 项目的容器能直接访问 B 项目的数据库。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;自定义 bridge 网络把这两个问题都解决了：它内置了一个 DNS 服务器（地址 &lt;code&gt;127.0.0.11&lt;/code&gt;），&lt;strong&gt;同一网络内的容器可以直接&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;用容器名/服务名互相访问&amp;lt;/span&amp;gt;&lt;/strong&gt;，IP 变了也不怕；不同项目用不同网络，天然隔离。&lt;/p&gt;
&lt;h3&gt;手动创建与使用&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 创建一个自定义网络，可指定网段和网关
docker network create \
  --driver bridge \
  --subnet 172.20.0.0/16 \
  --gateway 172.20.0.1 \
  mynet

# 两个容器接入同一网络
docker run -d --name web --network mynet nginx
docker run -d --name app --network mynet myapp

# 在 app 容器里直接用名字访问 web
docker exec app curl http://web
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;规划网段时避开你局域网和常用 VPN 的网段（比如家里路由器是 192.168.1.0/24 就别用它），Docker 默认分配的 172.16.0.0/12 私有段一般不冲突。&lt;/p&gt;
&lt;h3&gt;动态接入与固定 IP&lt;/h3&gt;
&lt;p&gt;容器跑起来之后也能变更网络归属，不用重建：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker network connect mynet &amp;lt;已存在的容器&amp;gt;     # 把运行中的容器接入某网络
docker network disconnect mynet &amp;lt;容器&amp;gt;          # 从某网络断开
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;一个容器可以同时接入多个网络（比如前面的 app 同时在 frontend 和 backend 里），&lt;code&gt;connect&lt;/code&gt; 就是实现手段。Compose 里增删 networks 后 &lt;code&gt;up -d&lt;/code&gt; 会自动完成同样的事，手动命令主要用在临时调试。&lt;/p&gt;
&lt;p&gt;有些场景需要给容器固定内网 IP（比如防火墙规则按 IP 放行、或老应用写死了对端地址），自定义网络支持指定：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d --network mynet --ip 172.20.0.10 nginx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Compose 写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  db:
    image: postgres:16
    networks:
      backend:
        ipv4_address: 172.21.0.10

networks:
  backend:
    ipam:
      config:
        - subnet: 172.21.0.0/16
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意固定 IP 只能用在自己规划了子网的自定义网络上，默认 bridge 不支持。没特殊需求时不要滥用固定 IP——名字解析已经解决了寻址问题，固定 IP 反而增加维护负担和冲突风险。&lt;/p&gt;
&lt;h3&gt;Compose 里怎么配&lt;/h3&gt;
&lt;p&gt;用 Compose 时其实你已经在用自定义网络了：&lt;strong&gt;Compose 会为每个项目自动创建一个名为 &lt;code&gt;&amp;lt;项目名&amp;gt;_default&lt;/code&gt; 的网络&lt;/strong&gt;，同一 compose 文件里的服务默认全部接入，彼此用&lt;strong&gt;服务名&lt;/strong&gt;互访。比如上一篇的例子里，Nginx 容器想连 Redis，直接写 &lt;code&gt;redis:6379&lt;/code&gt; 就行，不需要任何额外配置。&lt;/p&gt;
&lt;p&gt;需要显式规划时这样写：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  web:
    image: nginx:latest
    networks:
      - frontend
  app:
    image: myapp:latest
    networks:
      - frontend
      - backend
  db:
    image: postgres:16
    networks:
      - backend

networks:
  frontend:
  backend:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这个例子里 web 和 db 不在同一网络，&lt;strong&gt;web 无法直连数据库&lt;/strong&gt;，必须经过 app 中转——这就是用网络做访问隔离的标准手法，比在应用层堵要可靠得多。&lt;/p&gt;
&lt;p&gt;:::warning
容器互访用的是&lt;strong&gt;容器端口&lt;/strong&gt;，不是映射到宿主机的端口。上例中 app 访问 db 写的是 &lt;code&gt;db:5432&lt;/code&gt;（PostgreSQL 的容器端口），与 db 有没有在 &lt;code&gt;ports&lt;/code&gt; 里映射、映射成多少，都没有关系。把这两个概念搞混是新手最常见的互访故障来源。
:::&lt;/p&gt;
&lt;h2&gt;host 模式实战与注意事项&lt;/h2&gt;
&lt;p&gt;host 模式下容器没有自己的网络空间，直接用宿主机的网卡、IP 和端口。启动方式：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run -d --network host nginx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;此时 Nginx 监听的 80 端口就是宿主机的 80 端口，访问 &lt;code&gt;http://宿主机IP&lt;/code&gt; 直达，没有映射这一步。Compose 写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  nginx:
    image: nginx:latest
    network_mode: host
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意事项必须一条条说清：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;ports 配置会失效&lt;/strong&gt;。host 模式下写 &lt;code&gt;ports&lt;/code&gt; 不仅没用，Compose 还会警告并忽略它。端口冲突直接发生在宿主机层面：宿主机 80 已被占用，容器就起不来。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;仅 Linux 可用&lt;/strong&gt;。Docker Desktop（Mac/Windows）里的 host 模式行为完全不同，不要在那上面验证生产配置。&lt;/li&gt;
&lt;li&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;隔离性基本归零&lt;/strong&gt;&amp;lt;/span&amp;gt;。容器进程能看到宿主机全部网络接口，还能抓到本机流量，只对完全可信的镜像使用。&lt;/li&gt;
&lt;li&gt;适合它的场景：需要监听成百上千个端口、做软路由/网关类应用、对 NAT 那一点性能损耗都敏感的高吞吐服务。普通 Web 应用用 bridge 完全够了，不要跟风上 host。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;macvlan 补充：与宿主机不通是设计如此&lt;/h2&gt;
&lt;p&gt;前面表格里说 macvlan 容器像局域网里的一台独立设备，这里补一个最常踩的点：&lt;strong&gt;macvlan 容器默认和宿主机互相 ping 不通&lt;/strong&gt;。这是内核出于安全隔离的设计（同一个物理网卡上的 macvlan 端点与宿主机端点被隔开），不是配置错误。如果业务上需要宿主机访问 macvlan 容器，要在宿主机上再建一个 macvlan 子接口并配上同网段地址、加一条主机路由，操作偏繁琐。所以选型时要想清楚：只是想要「容器有个固定内网地址」，自定义 bridge + 固定 IP 就够了；只有当路由器、局域网其他设备必须把容器当独立机器发现和访问时，才值得上 macvlan。&lt;/p&gt;
&lt;p&gt;创建 macvlan 网络时要把局域网的网段、网关和物理网卡名都写对：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker network create -d macvlan \
  --subnet 192.168.1.0/24 \
  --gateway 192.168.1.1 \
  -o parent=eth0 \
  lan-net
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;其中 &lt;code&gt;parent&lt;/code&gt; 是宿主机真实网卡名（用 &lt;code&gt;ip link&lt;/code&gt; 查看），写错整个网络不可用；分配给容器的 IP 也要避开路由器 DHCP 的地址池范围，防止和局域网其他设备撞 IP。&lt;/p&gt;
&lt;h2&gt;IPv6 完整开启方法&lt;/h2&gt;
&lt;p&gt;Docker 默认只开 IPv4。宿主机本身有 IPv6 的话，把容器网络的 IPv6 打开只要三步。&lt;/p&gt;
&lt;h3&gt;第一步：改 daemon.json&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;ipv6&quot;: true,
  &quot;fixed-cidr-v6&quot;: &quot;fdb::/64&quot;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;说明两点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;ipv6: true&lt;/code&gt; 是总开关，同时 Docker 会启用 ip6tables 规则管理；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;fixed-cidr-v6&lt;/code&gt; 是给默认 bridge 分配的 IPv6 网段。这里用 &lt;code&gt;fdb::/64&lt;/code&gt; 属于 ULA 私有地址段（fd00::/8），只在内部使用、不参与公网路由，不会和任何公网地址冲突，是固定写法的稳妥选择。&lt;strong&gt;不要&lt;/strong&gt;把宿主机的公网 IPv6 网段直接填进来硬套，不懂路由规划时容易把网络搞乱。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;第二步：重启 Docker 生效&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;systemctl restart docker
docker network inspect bridge | grep -i ipv6
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;重启 Docker 会重启所有容器&amp;lt;/span&amp;gt;（配了 &lt;code&gt;live-restore&lt;/code&gt; 的除外，见第一篇）。生产机器上请挑低峰期操作，并提前确认各容器都配了 &lt;code&gt;restart: unless-stopped&lt;/code&gt; 之类的自启策略。
:::&lt;/p&gt;
&lt;h3&gt;第三步：Compose 项目里开启&lt;/h3&gt;
&lt;p&gt;全局开了 IPv6 后，Compose 的自定义网络还要单独声明才有 IPv6：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  web:
    image: nginx:latest
    ports:
      - &quot;8080:80&quot;

networks:
  default:
    enable_ipv6: true
    ipam:
      config:
        - subnet: &quot;fdb:1::/64&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;每个项目给一个不同的 ULA 子网（如 fdb:1::/64、fdb:2::/64），避免网段重叠。&lt;/p&gt;
&lt;h3&gt;验证方法&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 1. 看网络里是否已启用 IPv6 并分到了网段
docker network inspect &amp;lt;网络名&amp;gt;

# 2. 进容器看网卡，应该能看到 inet6 地址
docker exec web ip addr

# 3. 容器内测 IPv6 连通性（容器需装 iputils，debian 系 apt install iputils-ping）
docker exec web ping6 -c 3 fdb::1

# 4. 从宿主机按 IPv6 访问映射端口（如映射时绑了 v6）
curl -g -6 &quot;http://[::1]:8080&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果第 2 步容器里根本没有 inet6 地址，先回头检查 daemon.json 语法（JSON 不能有注释和多余逗号）和 Docker 是否真的重启成功：&lt;code&gt;systemctl status docker&lt;/code&gt; 看启动时间。&lt;/p&gt;
&lt;p&gt;:::warning
容器有 IPv6 地址 ≠ 能用 IPv6 上公网。ULA 地址只保证内网互通；要让容器借宿主机的公网 IPv6 出网，还需要宿主机开启转发并做 NDP 代理或前缀委派，属于进阶路由话题，不要指望改个 daemon.json 就自动通公网。
:::&lt;/p&gt;
&lt;h2&gt;排障工具箱&lt;/h2&gt;
&lt;p&gt;网络问题按「先确认事实，再缩小范围」的顺序查，下面这套命令能覆盖九成场景。&lt;/p&gt;
&lt;h3&gt;常用命令速查&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker network ls                          # 有哪些网络
docker network inspect &amp;lt;网络名&amp;gt;            # 看网段、网关、接入了哪些容器及其 IP
docker inspect &amp;lt;容器名&amp;gt;                    # 看某个容器在各网络中的 IP、别名
docker exec &amp;lt;容器名&amp;gt; ip addr               # 容器自己的网卡视角
docker exec &amp;lt;容器名&amp;gt; cat /etc/resolv.conf  # 容器用的 DNS（自定义网络应为 127.0.0.11）
ss -tlnp                                   # 宿主机上到底谁在监听哪些端口
docker port &amp;lt;容器名&amp;gt;                       # 映射关系一览
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;场景一：端口映射了，但外网访问不了&lt;/h3&gt;
&lt;p&gt;按这个顺序逐项排除：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;宿主机本地先测：&lt;code&gt;curl http://127.0.0.1:8080&lt;/code&gt;，通不通决定了问题在 Docker 还是在网络层；&lt;/li&gt;
&lt;li&gt;本地通、外网不通 → 九成是&lt;strong&gt;云厂商安全组没放行&lt;/strong&gt;或机房防火墙拦截，去控制台放行对应端口；&lt;/li&gt;
&lt;li&gt;看映射是不是只绑了 127.0.0.1（&lt;code&gt;docker port&lt;/code&gt; 输出带 &lt;code&gt;127.0.0.1&lt;/code&gt; 前缀），是的话外网本来就进不来，属预期行为；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;ss -tlnp | grep 8080&lt;/code&gt; 确认端口确实在监听、且监听进程是 docker。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;场景二：两个容器互访不通&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;先确认在不在&lt;strong&gt;同一个网络&lt;/strong&gt;：&lt;code&gt;docker network inspect &amp;lt;网络名&amp;gt;&lt;/code&gt; 看 Containers 列表里有没有双方；&lt;/li&gt;
&lt;li&gt;不在一个网络，要么把它们接进同一网络，要么明确接受不通（隔离设计）；&lt;/li&gt;
&lt;li&gt;在同一网络还不通，检查你用的是容器名+&lt;strong&gt;容器端口&lt;/strong&gt;，而不是宿主机映射端口；&lt;/li&gt;
&lt;li&gt;在默认 bridge 网络里用容器名互访必然失败——默认网络没有名字解析，改用自定义网络，这是设计如此，不是故障。&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;# 容器内连通性三连测
docker exec app ping -c 3 db        # 名字能否解析、网络通不通
docker exec app curl -v http://db:5432   # 端口层面的确认（换成目标服务端口）
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;场景三：启动报错端口被占用&lt;/h3&gt;
&lt;p&gt;报错形如 &lt;code&gt;Bind for 0.0.0.0:8080 failed: port is already allocated&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ss -tlnp | grep 8080   # 先看占用者是谁：可能是另一个容器，也可能是宿主机原生进程
docker ps              # 若是另一个容器占的，改它或改自己的宿主机端口
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;处理原则：改&lt;strong&gt;宿主机侧&lt;/strong&gt;端口即可（如 8080→8081），容器端口不要动，应用配置也不用改。&lt;/p&gt;
&lt;h3&gt;场景四：容器里上不了网&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker exec app ping -c 3 223.5.5.5   # 先测纯 IP，排除 DNS 因素
docker exec app ping -c 3 baidu.com   # 再测域名
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;IP 通、域名不通是 DNS 问题（检查容器 resolv.conf 与 daemon.json 的 dns 配置）；IP 也不通，多半是宿主机转发没开或防火墙 FORWARD 链被其他软件改过，先查 &lt;code&gt;sysctl net.ipv4.ip_forward&lt;/code&gt; 应为 1，再回忆最近是否装过其他网络类工具动过 iptables。&lt;/p&gt;
&lt;h3&gt;场景五：同网络内名字解析失败&lt;/h3&gt;
&lt;p&gt;在自定义网络里用容器名 ping 不通、报 &lt;code&gt;Name or service not known&lt;/code&gt;，按下面查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;确认两个容器真的在同一个网络，且用的是&lt;strong&gt;容器名或 Compose 服务名&lt;/strong&gt;，不是镜像名；&lt;/li&gt;
&lt;li&gt;进容器看 &lt;code&gt;/etc/resolv.conf&lt;/code&gt;，自定义网络的 nameserver 应该是 &lt;code&gt;127.0.0.11&lt;/code&gt;（Docker 内置 DNS），若被镜像改成了别的，先解决镜像的 DNS 配置；&lt;/li&gt;
&lt;li&gt;Compose 里给服务改过 &lt;code&gt;container_name&lt;/code&gt; 的，服务名和容器名都能解析；若还用了网络别名（&lt;code&gt;aliases&lt;/code&gt;），别名同样有效，可在 &lt;code&gt;docker network inspect&lt;/code&gt; 输出里核对每个容器的 Aliases 字段；&lt;/li&gt;
&lt;li&gt;宿主机或公司内网有 mDNS、systemd-resolved 劫持时偶尔会干扰解析结果，用 &lt;code&gt;docker exec app getent hosts db&lt;/code&gt; 看容器内部的真实解析结果，别在宿主机上测了下结论。&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;网络模式选型：默认用自定义 bridge，host 只给性能敏感且可信的服务，macvlan 只在需要局域网真实 IP 时用；&lt;/li&gt;
&lt;li&gt;端口映射默认全网可达，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;不需要外网直连的端口一律只绑 127.0.0.1&lt;/strong&gt;&amp;lt;/span&amp;gt;，且记住 Docker 映射会绕过 ufw；&lt;/li&gt;
&lt;li&gt;容器互访的正解是同一自定义网络 + 服务名 + 容器端口，默认 bridge 没有名字解析，别再用 IP 硬编码和 &lt;code&gt;--link&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;IPv6 开启就三步&amp;lt;/span&amp;gt;：daemon.json 写 &lt;code&gt;ipv6: true&lt;/code&gt; 与 &lt;code&gt;fixed-cidr-v6: &quot;fdb::/64&quot;&lt;/code&gt;、重启 Docker、Compose 网络里再声明 &lt;code&gt;enable_ipv6&lt;/code&gt;，验证用 inspect + 容器内 ip addr/ping6；&lt;/li&gt;
&lt;li&gt;排障先分清层次：映射问题查 &lt;code&gt;docker port&lt;/code&gt; 和 &lt;code&gt;ss&lt;/code&gt;，互访问题查是否同网络，通不通外网先分清本地与云安全组。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;网络这块吃透了，后面讲反向代理、监控这些实战部署时就不会再被「连不上」卡住。&lt;/p&gt;
</content:encoded></item><item><title>用 Docker 部署 Nginx 反向代理与自动 HTTPS</title><link>https://www.anexns.cloudns.org/posts/docker-nginx-https/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-nginx-https/</guid><description>两条路线给容器服务套上域名和 HTTPS：原生 Nginx + Certbot 手动路线讲透反代配置与证书自动续期，Nginx Proxy Manager 图形化路线十分钟上线，附 WebSocket 支持与 502 排障全流程。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;前几篇里我们已经把 Docker 装好、把容器跑起来了（没装的先看 &lt;a href=&quot;/posts/linux-docker-compose/&quot;&gt;《如何在Linux部署Docker&amp;amp;Compose》&lt;/a&gt;）。但跑起来只是第一步：服务监听在 &lt;code&gt;8080&lt;/code&gt;、&lt;code&gt;3001&lt;/code&gt;、&lt;code&gt;4000&lt;/code&gt; 这些端口上，要访问就得记一串 IP 加端口，既难记又不安全——密码、数据全在明文 HTTP 里跑，浏览器还动不动弹「不安全」警告。这篇就解决这个问题：用反向代理给所有服务&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;统一套上域名和 HTTPS&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;全文给两条路线：&lt;strong&gt;路线 A&lt;/strong&gt; 是原生 Nginx + Certbot，配置全在自己手里，适合想搞懂原理、服务不多的场景；&lt;strong&gt;路线 B&lt;/strong&gt; 是 Nginx Proxy Manager（下文简称 NPM），图形化点点鼠标就能上线，适合服务多、怕折腾配置的场景。两条路线最后有对比表，先通读再选一条动手即可。&lt;/p&gt;
&lt;h2&gt;为什么需要反向代理&lt;/h2&gt;
&lt;p&gt;先说清楚反向代理到底解决了什么问题。假设你的服务器上跑了三个容器服务：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;服务&lt;/th&gt;
&lt;th&gt;容器端口&lt;/th&gt;
&lt;th&gt;直接访问的方式&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;博客&lt;/td&gt;
&lt;td&gt;8080&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http://服务器IP:8080&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;监控面板&lt;/td&gt;
&lt;td&gt;3001&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http://服务器IP:3001&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;网盘&lt;/td&gt;
&lt;td&gt;5212&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http://服务器IP:5212&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;反向代理是站在这些服务前面的一层「门卫」：外部请求统一打到服务器的 80/443 端口，门卫根据请求的域名把流量转发给后面对应的服务。它带来四个实实在在的好处：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;一个入口分发多个服务。&lt;/strong&gt; 80 和 443 是仅有的两个需要对外开放的端口，门卫按域名分流：&lt;code&gt;blog.example.com&lt;/code&gt; 去博客、&lt;code&gt;vps.example.com&lt;/code&gt; 去监控面板，一个 IP 承载任意多个站点。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;统一 HTTPS。&lt;/strong&gt; 证书只在门卫这一层申请和续期，后面的服务继续跑普通 HTTP 就行，不用每个服务单独折腾证书。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;隐藏内部端口。&lt;/strong&gt; 后端服务可以只监听本机回环地址或 Docker 内网，外面根本扫不到 8080、3001 这些端口，攻击面小很多。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;集中做通用处理。&lt;/strong&gt; 上传大小限制、超时、WebSocket 转发、访问日志，全在门卫一处配置，所有服务共享。&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;前置准备&lt;/h2&gt;
&lt;p&gt;动手之前把三件事备齐，后面能少踩一半的坑。&lt;/p&gt;
&lt;h3&gt;域名解析到服务器&lt;/h3&gt;
&lt;p&gt;在你的域名 DNS 管理里，给要用的域名加 A 记录指向服务器公网 IP，比如：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;主机记录&lt;/th&gt;
&lt;th&gt;记录类型&lt;/th&gt;
&lt;th&gt;记录值&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;blog&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A&lt;/td&gt;
&lt;td&gt;你的服务器公网 IP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;vps&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A&lt;/td&gt;
&lt;td&gt;你的服务器公网 IP&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;解析生效需要几分钟到几十分钟。验证是否生效，在本地执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ping blog.example.com
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回的 IP 是你服务器的 IP 就说明解析到位了。&lt;strong&gt;这一步没到位之前不要去申请证书&lt;/strong&gt;，Let&apos;s Encrypt 会因为验证不到域名归属直接拒绝，失败次数多了还会触发限额（后面排障部分会细说）。&lt;/p&gt;
&lt;h3&gt;放行 80 和 443 端口&lt;/h3&gt;
&lt;p&gt;两个地方都要放行，缺一个都不行：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;云厂商安全组&lt;/strong&gt;（如果你的服务器在云上）：入方向放行 TCP 80、443。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;本机防火墙&lt;/strong&gt;（如果开了 ufw / firewalld）：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;# ufw
ufw allow 80/tcp
ufw allow 443/tcp

# firewalld
firewall-cmd --permanent --add-service=http
firewall-cmd --permanent --add-service=https
firewall-cmd --reload
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;80 端口不只是给 HTTP 访问用的，Let&apos;s Encrypt 的 HTTP-01 验证也要走 80 端口，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;80 不通 = 证书申请必失败&lt;/strong&gt;&amp;lt;/span&amp;gt;，这是新手最常见的翻车点。&lt;/p&gt;
&lt;h3&gt;被反代的服务先「藏好」&lt;/h3&gt;
&lt;p&gt;反代上线之后，后端服务就不应该再直接暴露公网了。两种做法：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;服务跑在宿主机或端口映射时只绑回环地址&lt;/strong&gt;：Compose 里把端口映射写成 &lt;code&gt;127.0.0.1:8080:80&lt;/code&gt;，这样只有本机能连，外网连不上，流量只能从反代进来。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;服务和反代在同一个 Docker 网络里&lt;/strong&gt;：端口干脆不映射（不写 &lt;code&gt;ports&lt;/code&gt;），只通过容器名在内网互通。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;先有个概念就行，路线 A 用第一种衔接方式（同网络容器名互通也会讲到），路线 B 会专门讲它惯用的网关地址写法。&lt;/p&gt;
&lt;h2&gt;路线 A：原生 Nginx + Certbot&lt;/h2&gt;
&lt;p&gt;这条路线的思路是：Nginx 容器负责反代，Certbot 容器负责申请和续期 Let&apos;s Encrypt 证书，两者通过共享目录交换证书文件和验证文件。&lt;/p&gt;
&lt;h3&gt;目录结构&lt;/h3&gt;
&lt;p&gt;先建好目录，后面所有路径都以此为准：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p /opt/nginx-proxy/{conf.d,certbot/www,certbot/conf}
cd /opt/nginx-proxy
&lt;/code&gt;&lt;/pre&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;目录&lt;/th&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;conf.d/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Nginx 的站点配置文件，挂进容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;certbot/www/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;ACME 验证文件目录，Nginx 和 Certbot 共享&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;certbot/conf/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;证书存放目录，Certbot 写、Nginx 读&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;docker-compose.yml&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;services:
  nginx:
    image: nginx:alpine
    container_name: nginx-proxy
    restart: unless-stopped
    ports:
      - &quot;80:80&quot;
      - &quot;443:443&quot;
    volumes:
      - ./conf.d:/etc/nginx/conf.d:ro
      - ./certbot/www:/var/www/certbot:ro
      - ./certbot/conf:/etc/letsencrypt:ro

  certbot:
    image: certbot/certbot:latest
    container_name: certbot
    volumes:
      - ./certbot/www:/var/www/certbot
      - ./certbot/conf:/etc/letsencrypt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个细节注意：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Nginx 侧的三个挂载都加了 &lt;code&gt;:ro&lt;/code&gt;（只读），Nginx 只需要读配置和证书，不给写权限更安全；Certbot 侧不能加 &lt;code&gt;:ro&lt;/code&gt;，它要往里面写证书和验证文件。&lt;/li&gt;
&lt;li&gt;certbot 服务没有 &lt;code&gt;command&lt;/code&gt;，它是一次性工具容器，需要用的时候用 &lt;code&gt;docker compose run --rm certbot ...&lt;/code&gt; 临时拉起来执行命令，执行完自动删除，这正是下面申请证书的用法。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;第一步：先写 HTTP 版站点配置&lt;/h3&gt;
&lt;p&gt;关键顺序问题：&lt;strong&gt;证书还没申请下来之前，Nginx 不能加载引用证书文件的 HTTPS 配置&lt;/strong&gt;，否则启动直接报错。所以流程是先用纯 HTTP 配置把 Nginx 跑起来 → 用 Certbot 申请证书 → 再换成 HTTPS 配置并重载。&lt;/p&gt;
&lt;p&gt;在 &lt;code&gt;conf.d/&lt;/code&gt; 里新建 &lt;code&gt;blog.conf&lt;/code&gt;，先写 HTTP 版本（以把本机 8080 端口的博客服务反代到 &lt;code&gt;blog.example.com&lt;/code&gt; 为例）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;server {
    listen 80;
    server_name blog.example.com;

    # ACME 验证路径：Let&apos;s Encrypt 会来这里取验证文件，必须放在 location / 之前并单独声明
    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    location / {
        proxy_pass http://172.17.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这份配置逐行讲清楚，这是全篇最核心的部分：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;listen 80;&lt;/code&gt;：监听 HTTP 端口。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;server_name blog.example.com;&lt;/code&gt;：这个站点块只处理域名为 &lt;code&gt;blog.example.com&lt;/code&gt; 的请求，这就是「按域名分流」的实现方式——多个服务就写多个 server 块，各自认领一个域名。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;location /.well-known/acme-challenge/&lt;/code&gt;：Let&apos;s Encrypt 的 HTTP-01 验证路径。验证时它会访问 &lt;code&gt;http://blog.example.com/.well-known/acme-challenge/某个随机文件名&lt;/code&gt;，Certbot 会把验证文件写到共享目录里，Nginx 从这里读到并返回，验证就通过了。这个 location 缺失或被其他规则拦截，是证书申请失败的第二大原因。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;proxy_pass http://172.17.0.1:8080;&lt;/code&gt;：把请求转发到后端服务。这里的 &lt;code&gt;172.17.0.1&lt;/code&gt; 是 Docker 默认网桥在宿主机一侧的网关地址，也就是说后端服务是「监听在宿主机 8080 端口」的情况（比如另一个 Compose 项目映射了 &lt;code&gt;127.0.0.1:8080&lt;/code&gt;）。如果后端服务和 Nginx 在同一个 Compose、同一个网络里，这里可以直接写容器名加容器端口，如 &lt;code&gt;proxy_pass http://blog:80;&lt;/code&gt;，靠 Docker 内置 DNS 解析。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;proxy_set_header 四件套&lt;/strong&gt;，每一项都不能省：
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;Host $host&lt;/code&gt;：把用户实际访问的域名原样告诉后端。不传的话后端收到的 Host 是 &lt;code&gt;172.17.0.1:8080&lt;/code&gt;，很多应用会据此生成跳转链接、校验来源，轻则链接全错，重则直接拒绝请求。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;X-Real-IP $remote_addr&lt;/code&gt;：把访客的真实 IP 传给后端。经过反代之后，后端看到的连接来源全是 Nginx 的地址，没有这一行，后端日志里所有访客 IP 都会变成同一个网关地址，限流、封禁、审计全没法做。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;X-Forwarded-For $proxy_add_x_forwarded_for&lt;/code&gt;：和上一行的分工不同，这个头记录的是完整的代理链（访客 IP 经过每一层代理依次追加），后端框架普遍优先读这个头来还原真实 IP。&lt;code&gt;$proxy_add_x_forwarded_for&lt;/code&gt; 的含义是「在已有的 X-Forwarded-For 后面追加上一层的地址」，而不是覆盖，多层代理时不会丢链。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;X-Forwarded-Proto $scheme&lt;/code&gt;：告诉后端「用户到 Nginx 这一段用的是 http 还是 https」。等启用 HTTPS 后这一行尤其关键：后端如果不知道前面是 HTTPS，会生成 http 的跳转地址，用户就会被甩回明文或陷入重定向死循环（登录后反复跳回登录页是典型症状）。&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;写好后启动 Nginx：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d nginx
docker compose logs nginx   # 确认没有配置报错
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第二步：用 Certbot 申请证书&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker compose run --rm certbot certonly --webroot \
  -w /var/www/certbot \
  -d blog.example.com \
  --email your@email.com \
  --agree-tos \
  --no-eff-email
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;参数说明：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;certonly&lt;/code&gt;：只申请证书，不自动改任何配置（配置我们自己写，可控）。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--webroot -w /var/www/certbot&lt;/code&gt;：用 webroot 验证方式，把验证文件写到共享目录，正好对应上一步 Nginx 配置里的 ACME 路径。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;-d blog.example.com&lt;/code&gt;：要申请证书的域名，多个域名可以继续加 &lt;code&gt;-d&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--email&lt;/code&gt;：证书快到期时 Let&apos;s Encrypt 会发提醒邮件到这个邮箱。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;成功后证书会出现在 &lt;code&gt;certbot/conf/live/blog.example.com/&lt;/code&gt; 下，关键的两个文件是 &lt;code&gt;fullchain.pem&lt;/code&gt;（证书链）和 &lt;code&gt;privkey.pem&lt;/code&gt;（私钥）。&lt;/p&gt;
&lt;p&gt;:::warning
第一次申请前务必确认两件事：域名已经解析到这台服务器、80 端口从外网能通。验证失败会计入 Let&apos;s Encrypt 的限额：同一域名组合 &lt;strong&gt;一周内失败验证和重复签发都有次数上限&lt;/strong&gt;（重复证书每周 5 张、失败验证每小时 5 次），触发限额只能等窗口过期，急也没用。所以&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;别拿生产域名反复试错&amp;lt;/span&amp;gt;，先把前置准备做扎实。
:::&lt;/p&gt;
&lt;h3&gt;第三步：换上 HTTPS 配置并加 HTTP 跳转&lt;/h3&gt;
&lt;p&gt;把 &lt;code&gt;conf.d/blog.conf&lt;/code&gt; 替换成完整版本：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;server {
    listen 80;
    server_name blog.example.com;

    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    # 其余 HTTP 请求一律 301 跳转到 HTTPS
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    server_name blog.example.com;

    ssl_certificate /etc/letsencrypt/live/blog.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/blog.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    location / {
        proxy_pass http://172.17.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;新增的部分：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;第一个 server 块只干两件事：保留 ACME 验证路径（续期还要用它，删了续期就失败），其余请求 &lt;code&gt;return 301 https://$host$request_uri;&lt;/code&gt; 永久跳转到 HTTPS，&lt;code&gt;$request_uri&lt;/code&gt; 保证跳转后路径和参数原样保留。&lt;/li&gt;
&lt;li&gt;第二个 server 块监听 &lt;code&gt;443 ssl&lt;/code&gt;，用 &lt;code&gt;ssl_certificate&lt;/code&gt; / &lt;code&gt;ssl_certificate_key&lt;/code&gt; 指向刚申请下来的证书，&lt;code&gt;ssl_protocols&lt;/code&gt; 只允许 TLS 1.2 和 1.3，老旧协议全部关掉。&lt;/li&gt;
&lt;li&gt;反代的四件套和 HTTP 版一字不差，注意此时 &lt;code&gt;$scheme&lt;/code&gt; 的值变成了 &lt;code&gt;https&lt;/code&gt;，后端靠它就知道外层是加密连接。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;改好后先验配置再重载，不要直接重启：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose exec nginx nginx -t      # 语法检查，必须看到 successful
docker compose exec nginx nginx -s reload
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;浏览器访问 &lt;code&gt;https://blog.example.com&lt;/code&gt;，地址栏有锁、证书信息里签发者是 Let&apos;s Encrypt，就算上线了。再访问 &lt;code&gt;http://blog.example.com&lt;/code&gt; 应该会被自动跳到 HTTPS。&lt;/p&gt;
&lt;h3&gt;第四步：证书自动续期&lt;/h3&gt;
&lt;p&gt;Let&apos;s Encrypt 证书有效期只有 90 天，自动续期是这条路线的必修课。原理是定期跑 &lt;code&gt;certbot renew&lt;/code&gt;（它只会续期离到期不足 30 天的证书，没到期跑了也无副作用），续期成功后重载 Nginx 让新证书生效。用宿主机的 cron 实现最稳妥：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;crontab -e
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;加入一行（每周一凌晨 3 点执行，路径换成你的实际目录）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;0 3 * * 1 cd /opt/nginx-proxy &amp;amp;&amp;amp; docker compose run --rm certbot renew --quiet &amp;amp;&amp;amp; docker compose exec nginx nginx -s reload &amp;gt;&amp;gt; /var/log/certbot-renew.log 2&amp;gt;&amp;amp;1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;用 systemd 的机器也可以写 timer，效果一样，二选一即可。续期机制上线后建议手动演练一次，确认整条链是通的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/nginx-proxy
docker compose run --rm certbot renew --dry-run
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--dry-run&lt;/code&gt; 是向 Let&apos;s Encrypt 的测试环境走一遍完整续期流程，不消耗正式限额，输出里看到 &lt;code&gt;Congratulations, all simulated renewals succeeded&lt;/code&gt; 就说明解析、80 端口、验证路径都没问题。&lt;/p&gt;
&lt;p&gt;:::warning
续期失败最常见的两个原因：一是有人「优化」配置时把 &lt;code&gt;/.well-known/acme-challenge/&lt;/code&gt; 那个 location 删了或被跳转规则吞了；二是 80 端口被关了。所以 HTTP server 块里的 ACME 路径和 301 跳转要并存——验证路径优先匹配自己的 location，其余才走跳转，上面配置的写法已经处理好了，不要把 &lt;code&gt;return 301&lt;/code&gt; 写到 server 块顶层去，那样验证路径也会被跳走。
:::&lt;/p&gt;
&lt;h2&gt;路线 B：Nginx Proxy Manager&lt;/h2&gt;
&lt;p&gt;不想碰配置文件的走这条：NPM 把 Nginx 包装成了带 Web 后台的成品，反代、证书、跳转全部在网页上点选完成。&lt;/p&gt;
&lt;h3&gt;docker-compose.yml&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;services:
  npm:
    image: jc21/nginx-proxy-manager:latest
    container_name: nginx-proxy-manager
    restart: unless-stopped
    ports:
      - &quot;80:80&quot;     # HTTP 入口
      - &quot;443:443&quot;   # HTTPS 入口
      - &quot;81:81&quot;     # 管理后台
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;data&lt;/code&gt; 卷存 NPM 的全部配置和数据库，&lt;code&gt;letsencrypt&lt;/code&gt; 卷存它申请的证书，两个都要持久化，重建容器不会丢配置。&lt;/p&gt;
&lt;h3&gt;首次登录：先改密码&lt;/h3&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;http://服务器IP:81&lt;/code&gt;，用官方默认账号登录：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;默认值&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;邮箱&lt;/td&gt;
&lt;td&gt;&lt;code&gt;admin@example.com&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;密码&lt;/td&gt;
&lt;td&gt;&lt;code&gt;changeme&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
&lt;code&gt;admin@example.com&lt;/code&gt; / &lt;code&gt;changeme&lt;/code&gt; 是 NPM 官方公开的默认账号密码，任何人都知道。登录后系统会强制要求你先完善资料并修改密码，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;不要跳过、不要拖延&lt;/strong&gt;&amp;lt;/span&amp;gt;：81 端口等于把全站流量的总闸开在了公网，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;默认密码不改就是裸奔&amp;lt;/span&amp;gt;。改完密码后，进一步建议把 81 端口也收一下：只绑 &lt;code&gt;127.0.0.1:81:81&lt;/code&gt; 再通过内网或隧道访问，或者在防火墙里只放行你自己的 IP。
:::&lt;/p&gt;
&lt;h3&gt;添加一个反代站点（Proxy Host）&lt;/h3&gt;
&lt;p&gt;登录后点顶部的 &lt;strong&gt;Hosts → Proxy Hosts → Add Proxy Host&lt;/strong&gt;，在 Details 页填：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;填法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Domain Names&lt;/td&gt;
&lt;td&gt;&lt;code&gt;blog.example.com&lt;/code&gt;（一个站点可以填多个域名）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Scheme&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http&lt;/code&gt;（指 NPM 到后端这一段的协议，后端跑的是 HTTP 就选 http）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Forward Hostname / IP&lt;/td&gt;
&lt;td&gt;&lt;code&gt;172.17.0.1&lt;/code&gt;（理由见下一小节）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Forward Port&lt;/td&gt;
&lt;td&gt;后端服务在宿主机上的端口，如 &lt;code&gt;8080&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Block Common Exploits&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;勾选&lt;/strong&gt;（拦截常见攻击特征，没副作用）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Websockets Support&lt;/td&gt;
&lt;td&gt;需要 WebSocket 的服务&lt;strong&gt;勾选&lt;/strong&gt;（原理见 WebSocket 小节）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;保存后先用 &lt;code&gt;http://blog.example.com&lt;/code&gt; 访问验证反代本身通不通，通了再去开证书，不要两个变量一起改，出问题不好定位。&lt;/p&gt;
&lt;h3&gt;一键申请证书并强制 HTTPS&lt;/h3&gt;
&lt;p&gt;编辑刚建的 Proxy Host，切到 &lt;strong&gt;SSL&lt;/strong&gt; 页：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;SSL Certificate 下拉选 &lt;strong&gt;Request a new SSL Certificate&lt;/strong&gt;；&lt;/li&gt;
&lt;li&gt;打开 &lt;strong&gt;Force SSL&lt;/strong&gt;（等于路线 A 里手写的 301 跳转）；&lt;/li&gt;
&lt;li&gt;打开 &lt;strong&gt;HTTP/2 Support&lt;/strong&gt;；&lt;/li&gt;
&lt;li&gt;填你的邮箱，勾选同意 Let&apos;s Encrypt 条款，保存。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;NPM 会自动走完验证、签发、配置、重载的全过程，十几秒后 &lt;code&gt;https://blog.example.com&lt;/code&gt; 就能访问了。证书续期也由 NPM 内部自动处理，不用再单独配 cron——这是图形化路线最省心的地方。&lt;/p&gt;
&lt;h3&gt;上游地址为什么填 172.17.0.1&lt;/h3&gt;
&lt;p&gt;这是 NPM（以及一切独立部署的反代）最值得讲清楚的一个细节。添加 Proxy Host 时，后端地址有两种填法：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;填容器名&lt;/strong&gt;：要求 NPM 和后端服务处在同一个 Docker 网络里，NPM 才能靠内置 DNS 解析到容器名。后果是每接一个新服务，就要把 NPM 拉进那个服务的网络，服务多了 NPM 身上挂着一堆网络，配置互相耦合，删服务、改网络时还容易误伤总闸。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;填 &lt;code&gt;172.17.0.1:&amp;lt;端口&amp;gt;&lt;/code&gt;&lt;/strong&gt;（本篇推荐）：&lt;code&gt;172.17.0.1&lt;/code&gt; 是 Docker 默认网桥 &lt;code&gt;docker0&lt;/code&gt; 在宿主机一侧的网关地址，从任何容器里访问它，就等于访问宿主机本身。所以后端服务只要把端口映射到宿主机（配合前面说的绑 &lt;code&gt;127.0.0.1&lt;/code&gt; 更安全），NPM 用「网关地址 + 宿主机端口」就能找到它，&lt;strong&gt;完全不用把 NPM 拉进各业务网络&lt;/strong&gt;。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;反代和业务彻底解耦&amp;lt;/span&amp;gt;：业务随便增删改，反代这边只改一行转发地址。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;代价只有一个：后端服务必须在宿主机上有端口映射（哪怕只绑 127.0.0.1 也行，网关地址同样能连通回环绑定的端口）。对绝大多数个人部署来说，这个代价可以忽略，换来的是干净的网络结构。&lt;/p&gt;
&lt;h2&gt;WebSocket 支持&lt;/h2&gt;
&lt;p&gt;很多现代应用（在线终端、实时面板、聊天类服务、各类 Dashboard 的实时数据）都用 WebSocket 长连接。WebSocket 是靠 HTTP 的 Upgrade 机制升级出来的协议，反代默认不转发升级头的话，表现就是「页面能开，但实时功能连不上、一直转圈重连」。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;路线 A（原生 Nginx）&lt;/strong&gt; 需要在对应站点的 &lt;code&gt;location /&lt;/code&gt; 里加三行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location / {
    proxy_pass http://172.17.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection &quot;upgrade&quot;;
    # 原来的四件套继续保留
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;proxy_http_version 1.1;&lt;/code&gt;：Upgrade 机制要求 HTTP/1.1，而 Nginx 反代默认用 HTTP/1.0，这行不加后面两行等于白写。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;Upgrade $http_upgrade&lt;/code&gt;：把客户端发来的 Upgrade 头原样传给后端。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;Connection &quot;upgrade&quot;&lt;/code&gt;：告诉后端这条连接要升级成 WebSocket。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;路线 B（NPM）&lt;/strong&gt; 就是添加/编辑 Proxy Host 时勾选那个 &lt;strong&gt;Websockets Support&lt;/strong&gt; 开关，它在底层生成的正是上面这组配置。一行代码和一个勾的区别，这就是两条路线风格差异的缩影。&lt;/p&gt;
&lt;h2&gt;其他常用配置项&lt;/h2&gt;
&lt;p&gt;这几项在路线 A 里是往 &lt;code&gt;location /&lt;/code&gt; 或 server 块里加行，路线 B 里 NPM 的 Proxy Host 有个 &lt;strong&gt;Advanced&lt;/strong&gt; 页，填的就是原生 Nginx 配置片段，语法完全一样，抄过去即可。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;放开上传大小。&lt;/strong&gt; Nginx 默认请求体上限只有 1MB，网盘类服务传个稍大的文件就报 &lt;code&gt;413 Request Entity Too Large&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;client_max_body_size 1024m;   # 按需改，0 表示不限制（不建议）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;放长读超时。&lt;/strong&gt; 备份导出、AI 对话、大文件处理这类接口经常跑几分钟，默认 60 秒读超时会让请求被反代掐断、前端报 504：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;proxy_read_timeout 600s;
proxy_send_timeout 600s;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;静态资源缓存头。&lt;/strong&gt; 让浏览器缓存图片、CSS、JS，减轻后端压力、打开更快：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
    proxy_pass http://172.17.0.1:8080;
    expires 7d;
    add_header Cache-Control &quot;public&quot;;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意这类带正则的 location 要和 &lt;code&gt;location /&lt;/code&gt; 并列写，Nginx 会优先匹配正则规则。动态内容千万别套缓存头，会把 A 用户的页面缓存给 B 用户看。&lt;/p&gt;
&lt;h2&gt;排障全流程&lt;/h2&gt;
&lt;h3&gt;502 Bad Gateway&lt;/h3&gt;
&lt;p&gt;502 的含义非常明确：&lt;strong&gt;反代本身活着，但它连不上或读不懂后端&lt;/strong&gt;。按这个顺序查，基本五分钟内定位：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;后端服务活没活。&lt;/strong&gt; &lt;code&gt;docker ps&lt;/code&gt; 看容器在不在跑；直接在服务器上 &lt;code&gt;curl -v http://127.0.0.1:8080&lt;/code&gt;（换成你的后端地址端口），本机都访问不通就先修后端，反代不用看了。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;转发地址和端口对不对。&lt;/strong&gt; 对照 Proxy Host / 配置文件里的地址端口和后端实际监听的是否一致，尤其注意「容器内端口」和「映射到宿主机的端口」是两回事：走 &lt;code&gt;172.17.0.1&lt;/code&gt; 时填的是&lt;strong&gt;宿主机映射端口&lt;/strong&gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;看反代的错误日志。&lt;/strong&gt; 路线 A：&lt;code&gt;docker compose logs nginx&lt;/code&gt; 或容器内 &lt;code&gt;/var/log/nginx/error.log&lt;/code&gt;；路线 B：&lt;code&gt;docker logs nginx-proxy-manager&lt;/code&gt;。日志会直说原因，常见三类：
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;connect() failed (111: Connection refused)&lt;/code&gt;：后端没监听这个端口，回到第 1、2 步。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;no live upstreams&lt;/code&gt;：同上，本质还是连不上。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;upstream sent too big header&lt;/code&gt;：后端返回头过大，给 location 加 &lt;code&gt;proxy_buffer_size 128k;&lt;/code&gt; 和 &lt;code&gt;proxy_buffers 4 256k;&lt;/code&gt; 再重载。&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;还有一个隐蔽情况：后端绑了 &lt;code&gt;127.0.0.1&lt;/code&gt;、本机 curl 也通，但走网关地址就是不通——检查后端端口映射绑的是不是 &lt;code&gt;127.0.0.1&lt;/code&gt;，绝大多数发行版上回环绑定对 &lt;code&gt;172.17.0.1&lt;/code&gt; 过来的连接同样有效；个别环境不行的话，改绑 &lt;code&gt;0.0.0.0&lt;/code&gt; 并用防火墙封掉外网访问该端口即可。&lt;/p&gt;
&lt;h3&gt;证书申请失败&lt;/h3&gt;
&lt;p&gt;按可能性从高到低排查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;域名没解析过来。&lt;/strong&gt; &lt;code&gt;ping 域名&lt;/code&gt; 看 IP 对不对；刚改的解析没生效就等等，别反复重试耗限额。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;80 端口不通。&lt;/strong&gt; 云安全组和本机防火墙两处都查；可以在别的网络用手机流量打开 &lt;code&gt;http://域名&lt;/code&gt; 验证（能打开反代的默认页或后端都行，关键是通）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;ACME 路径被拦截。&lt;/strong&gt; 路线 A 检查 &lt;code&gt;/.well-known/acme-challenge/&lt;/code&gt; 的 location 还在不在、有没有被 301 跳转吞掉；路线 B 一般不会，但如果 Advanced 里写过自定义配置要重点怀疑。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;触发 Let&apos;s Encrypt 限额。&lt;/strong&gt; 错误信息里出现 &lt;code&gt;rate limit&lt;/code&gt; 就是它，只能等（重复证书限额按周滚动，失败验证按小时）。等待期间想先上线，可以临时用自签证书顶着，或者换一个子域名继续。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;证书过期与有效期检查&lt;/h3&gt;
&lt;p&gt;怀疑证书过期或想确认续期是否生效，用这两条命令在任何机器上都能查：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 看证书的生效与到期时间
echo | openssl s_client -connect blog.example.com:443 -servername blog.example.com 2&amp;gt;/dev/null | openssl x509 -noout -dates

# 或者从 curl 的握手信息里看
curl -vI https://blog.example.com 2&amp;gt;&amp;amp;1 | grep -E &quot;expire|SSL certificate verify&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;notAfter&lt;/code&gt; 是到期时间。两条路线分别这样查：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;路线&lt;/th&gt;
&lt;th&gt;查法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;路线 A&lt;/td&gt;
&lt;td&gt;续期后到期时间没变，说明续期或重载环节断了：先看 cron 有没有执行（&lt;code&gt;grep certbot /var/log/syslog&lt;/code&gt; 或你重定向的日志文件），再手动跑一遍 &lt;code&gt;renew --dry-run&lt;/code&gt; 看报错&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;路线 B&lt;/td&gt;
&lt;td&gt;去后台的 SSL Certificates 页面看每个证书的到期状态，红色就是已过期或续期失败，点进去能看到错误原因&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;两条路线对比与选型&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;路线 A：原生 Nginx + Certbot&lt;/th&gt;
&lt;th&gt;路线 B：Nginx Proxy Manager&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;上手方式&lt;/td&gt;
&lt;td&gt;写配置文件&lt;/td&gt;
&lt;td&gt;Web 后台点选&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;上线速度&lt;/td&gt;
&lt;td&gt;30 分钟左右（第一次）&lt;/td&gt;
&lt;td&gt;10 分钟左右&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;证书申请&lt;/td&gt;
&lt;td&gt;命令行手动走 webroot 流程&lt;/td&gt;
&lt;td&gt;后台一键申请&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;证书续期&lt;/td&gt;
&lt;td&gt;自己配 cron / timer&lt;/td&gt;
&lt;td&gt;内置自动续期&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;WebSocket&lt;/td&gt;
&lt;td&gt;手写三行 Upgrade 配置&lt;/td&gt;
&lt;td&gt;勾选开关&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;可控程度&lt;/td&gt;
&lt;td&gt;最高，Nginx 的任何能力都能用&lt;/td&gt;
&lt;td&gt;常用功能够全，高级玩法靠 Advanced 补配置&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;排障方式&lt;/td&gt;
&lt;td&gt;看配置文件和 error.log，最直接&lt;/td&gt;
&lt;td&gt;先看后台状态，再看容器日志&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;额外攻击面&lt;/td&gt;
&lt;td&gt;无（只有 Nginx 本身）&lt;/td&gt;
&lt;td&gt;多一个管理后台，必须改默认密码、收好 81 端口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合人群&lt;/td&gt;
&lt;td&gt;服务少、想学原理、喜欢一切在代码里&lt;/td&gt;
&lt;td&gt;服务多、经常增删站点、想省事&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选型建议很简单：&lt;strong&gt;只有一两个服务、且愿意花半小时把原理搞透，选路线 A&lt;/strong&gt;，这套配置知识在任何公司、任何环境都通用；&lt;strong&gt;服务三五个以上、以后还会不断加新服务，选路线 B&lt;/strong&gt;，把时间花在服务本身而不是反代配置上。两条路线并不互斥——不少人就是用 NPM 起步，等某个站点需要精细调优时，再把那一个站点迁到原生 Nginx 上单独伺候。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;反向代理的价值是「一个入口、统一 HTTPS、隐藏后端」，域名分流靠 server_name（路线 A）或 Proxy Host（路线 B）实现。&lt;/li&gt;
&lt;li&gt;动手前先把解析、80/443 放行、后端绑回环这三件前置做完，证书申请的坑能避掉大半。&lt;/li&gt;
&lt;li&gt;路线 A 的正确顺序是：HTTP 配置先行 → webroot 申请证书 → 换 HTTPS 配置 → cron 自动续期，顺序错了 Nginx 起不来。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;proxy_set_header&lt;/code&gt; 四件套缺一不可，真实 IP 和协议头丢了，后端的日志、限流和跳转都会出问题。&lt;/li&gt;
&lt;li&gt;NPM 的上游填 &lt;code&gt;172.17.0.1:&amp;lt;端口&amp;gt;&lt;/code&gt; 是解耦的关键：后端只管映射端口，反代永远不用钻进业务网络。&lt;/li&gt;
&lt;li&gt;出问题先分清层：502 查后端连通性，证书失败查解析和 80 端口，命令和日志都在排障小节里备好了。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>私有镜像仓库：Registry 与 Harbor 部署实战</title><link>https://www.anexns.cloudns.org/posts/docker-private-registry/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-private-registry/</guid><description>自己的镜像自己存：用官方 Registry 十分钟搭起私有仓库并配好认证与 HTTPS，完整走通登录、推送、拉取与垃圾回收，再讲清什么时候该升级到 Harbor 以及两者的选型边界。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;上一篇 &lt;a href=&quot;/posts/dockerfile-guide/&quot;&gt;《Dockerfile 入门》&lt;/a&gt; 讲了怎么把自己的应用打包成镜像，打包完紧接着一个问题：镜像放哪？推 Docker Hub 要公开（私有仓库数量还有限），传文件用 &lt;code&gt;docker save&lt;/code&gt; 又笨重。这篇就解决这个问题：&lt;strong&gt;在自己的服务器上搭一个私有镜像仓库&lt;/strong&gt;。主线是官方 Registry——十分钟部署、配好认证和 HTTPS、走通推送拉取全流程；再讲什么时候该升级到企业级的 Harbor。&lt;/p&gt;
&lt;h2&gt;为什么需要私有仓库&lt;/h2&gt;
&lt;p&gt;先把动机说清楚，私有仓库解决的是这四件事：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;内网拉取快&lt;/strong&gt;。服务器都在自己手里，镜像从局域网/同机房的仓库拉，比每次去 Docker Hub 绕一圈快得多，批量部署时差距尤其明显。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;镜像不用公开&lt;/strong&gt;。自己写的业务镜像里可能带着代码和配置，推到公共仓库等于把家底亮出去；私有仓库只对自己人开放。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;躲开 Docker Hub 的限流&lt;/strong&gt;。匿名用户从 Docker Hub 拉镜像有速率限制（按 IP 计数），CI 里频繁拉取很容易撞上 &lt;code&gt;toomanyrequests&lt;/code&gt;；公共基础镜像可以先同步到自己的仓库当缓存。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;可用性自己说了算&lt;/strong&gt;。公共仓库抽风、网络不通的时候，自己的仓库不受影响；离线环境（内网机房）更是只能靠私有仓库供镜像。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;一句话：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;镜像是资产，资产要存在自己手里&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h2&gt;选型：Registry 还是 Harbor&lt;/h2&gt;
&lt;p&gt;Docker 生态里搭私有仓库主流就两个选择，先看清区别再动手：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;官方 Registry（registry:2）&lt;/th&gt;
&lt;th&gt;Harbor&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;本质&lt;/td&gt;
&lt;td&gt;单容器，就是仓库本体&lt;/td&gt;
&lt;td&gt;一整套平台：Registry ＋ 门户 ＋ 数据库 ＋ 扫描器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;资源占用&lt;/td&gt;
&lt;td&gt;内存几十 MB，单机随便跑&lt;/td&gt;
&lt;td&gt;起步建议 2 核 4G、40G 磁盘&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;用户与权限&lt;/td&gt;
&lt;td&gt;只有 htpasswd 账号密码，无分级权限&lt;/td&gt;
&lt;td&gt;多用户、项目级权限、机器人账号、LDAP/OIDC 对接&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Web 界面&lt;/td&gt;
&lt;td&gt;无（需另配第三方 UI）&lt;/td&gt;
&lt;td&gt;自带完整管理界面&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;镜像扫描&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;内置 Trivy，可拦截有高危漏洞的镜像被拉走&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;仓库复制&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;支持跨仓库定时/手动同步&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;垃圾回收&lt;/td&gt;
&lt;td&gt;命令行手动执行&lt;/td&gt;
&lt;td&gt;界面里可配定时 GC&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;部署维护&lt;/td&gt;
&lt;td&gt;一个 Compose 服务&lt;/td&gt;
&lt;td&gt;离线安装包一键装，但组件多、升级要走流程&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;选型线很简单&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;个人或小团队、就一两台服务器、只要「能推能拉」——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;先用 Registry 起步，绝大多数人到这一步就够了&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;li&gt;出现这些信号再考虑 Harbor：多人协作需要分权限、合规要求镜像必须过漏洞扫描、多个机房/多套环境要互相复制镜像、需要审计谁拉了什么。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;本文主线是 Registry，Harbor 在文末单独讲升级路径。&lt;/p&gt;
&lt;h2&gt;第一步：部署 Registry&lt;/h2&gt;
&lt;p&gt;目录规划（沿用本系列的习惯，一个服务一个目录）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p /opt/registry/{data,auth,certs}
cd /opt/registry
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;docker-compose.yml&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  registry:
    image: registry:2
    container_name: registry
    restart: unless-stopped
    ports:
      - &quot;127.0.0.1:5000:5000&quot;
    volumes:
      - ./data:/var/lib/registry
    environment:
      - TZ=Asia/Shanghai
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个说明：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;镜像数据存在 &lt;code&gt;/var/lib/registry&lt;/code&gt;，挂到宿主机的 &lt;code&gt;./data&lt;/code&gt;，备份和迁移时直接打包这个目录（备份方法见 &lt;a href=&quot;/posts/docker-volumes-backup/&quot;&gt;《数据卷与备份恢复》&lt;/a&gt;）。&lt;/li&gt;
&lt;li&gt;端口先只绑 &lt;code&gt;127.0.0.1&lt;/code&gt;——这一步只是把仓库跑起来验证，认证和 HTTPS 都还没配，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;没认证的仓库绝不能直接暴露公网&amp;lt;/span&amp;gt;，原因下一节细说。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;启动并验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
curl http://127.0.0.1:5000/v2/
# 返回 {} 说明仓库 API 活着
curl http://127.0.0.1:5000/v2/_catalog
# 返回 {&quot;repositories&quot;:[]}，现在还是空仓库
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;/v2/&lt;/code&gt; 是仓库的健康检查口，返回空 JSON 就是通了。&lt;/p&gt;
&lt;p&gt;补一句配置方式的说明，方便后面看懂：Registry 的全部配置既可以写成一个 &lt;code&gt;config.yml&lt;/code&gt; 挂到容器里的 &lt;code&gt;/etc/docker/registry/config.yml&lt;/code&gt;，也可以像本文这样用环境变量表达——环境变量的命名规则是把配置路径大写、层级之间用下划线连接，比如配置里的 &lt;code&gt;auth.htpasswd.path&lt;/code&gt; 对应 &lt;code&gt;REGISTRY_AUTH_HTPASSWD_PATH&lt;/code&gt;。个人部署用环境变量写在 Compose 里最直观，配置项多了再换成 &lt;code&gt;config.yml&lt;/code&gt; 文件，两者不要混着写同一项，会互相覆盖搞不清以谁为准。&lt;/p&gt;
&lt;h2&gt;第二步：加认证（htpasswd）&lt;/h2&gt;
&lt;p&gt;没有认证的仓库意味着：任何知道地址的人都能往里推镜像、把你的镜像全拉走，甚至用同名镜像覆盖你的版本投毒。所以认证是私有仓库的底线配置，不是可选项。&lt;/p&gt;
&lt;p&gt;Registry 支持的认证方式里最简单的是 htpasswd 文件。用官方文档推荐的方式生成（借 httpd 镜像里的 &lt;code&gt;htpasswd&lt;/code&gt; 工具，&lt;code&gt;-B&lt;/code&gt; 表示用 bcrypt 加密，这点很重要，老式的 MD5/SHA1 都不要用）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/registry
docker run --rm --entrypoint htpasswd httpd:2 \
  -Bbn admin &apos;换成你的强密码&apos; &amp;gt; auth/htpasswd
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;参数拆解：&lt;code&gt;-B&lt;/code&gt; bcrypt 加密、&lt;code&gt;-b&lt;/code&gt; 从命令行读密码、&lt;code&gt;-n&lt;/code&gt; 输出到标准输出而不是写文件。生成的 &lt;code&gt;auth/htpasswd&lt;/code&gt; 内容形如 &lt;code&gt;admin:$2y$05$...&lt;/code&gt; 一行。再加第二个用户就去掉 &lt;code&gt;-n&lt;/code&gt; 换成追加写入，或者重新生成时把多个用户写进同一个文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 追加一个只用于拉取的账号（第一次生成文件时不要带 -c 以外的覆盖选项，这里用 &amp;gt;&amp;gt; 追加）
docker run --rm --entrypoint htpasswd httpd:2 \
  -Bbn puller &apos;另一个密码&apos; &amp;gt;&amp;gt; auth/htpasswd
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后给 Compose 加上认证配置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  registry:
    image: registry:2
    container_name: registry
    restart: unless-stopped
    ports:
      - &quot;127.0.0.1:5000:5000&quot;
    volumes:
      - ./data:/var/lib/registry
      - ./auth:/auth:ro
    environment:
      - TZ=Asia/Shanghai
      - REGISTRY_AUTH=htpasswd
      - REGISTRY_AUTH_HTPASSWD_REALM=Private Registry
      - REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;REGISTRY_AUTH_HTPASSWD_PATH&lt;/code&gt; 写的是&lt;strong&gt;容器内路径&lt;/strong&gt; &lt;code&gt;/auth/htpasswd&lt;/code&gt;，和挂载点对应。重建后验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
curl http://127.0.0.1:5000/v2/
# 现在应返回 401 Unauthorized，说明认证生效
curl -u admin:你的密码 http://127.0.0.1:5000/v2/
# 带账号密码返回 {} 才算配对
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
htpasswd 认证只有「有账号/没账号」两档，没有只读/可写之分——任何一个有效账号都能推能删。如果你的场景需要「CI 只能推、生产机只能拉」的分级权限，htpasswd 已经不够用，这正是升级 Harbor 的典型信号（Harbor 有项目成员角色和只读机器人账号）。
:::&lt;/p&gt;
&lt;h2&gt;第三步：加 HTTPS&lt;/h2&gt;
&lt;p&gt;Docker 客户端默认只信任 HTTPS 仓库。给仓库上 HTTPS 有两条路，按你的条件二选一。&lt;/p&gt;
&lt;h3&gt;路线 A：有域名，挂正式证书（推荐）&lt;/h3&gt;
&lt;p&gt;假设域名 &lt;code&gt;registry.example.com&lt;/code&gt; 已解析到这台机，证书文件（比如从 Let&apos;s Encrypt 申请的）放在 &lt;code&gt;./certs&lt;/code&gt; 下，Compose 里加三行环境变量并把证书目录挂进去：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    ports:
      - &quot;5000:5000&quot;
    volumes:
      - ./data:/var/lib/registry
      - ./auth:/auth:ro
      - ./certs:/certs:ro
    environment:
      - REGISTRY_HTTP_TLS_CERTIFICATE=/certs/fullchain.pem
      - REGISTRY_HTTP_TLS_KEY=/certs/privkey.pem
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;证书怎么申请、Nginx/Caddy 怎么配合，&lt;a href=&quot;/posts/docker-nginx-https/&quot;&gt;《Nginx 反向代理与自动 HTTPS》&lt;/a&gt; 已经写过。除了让 Registry 自己终止 TLS，另一个常见做法是 Registry 仍跑 HTTP 只听本机，前面套一层 Nginx/Caddy 反代来上 HTTPS——两种都行，反代路线的好处是证书续期和网站共用一套，仓库本身不用动。&lt;/p&gt;
&lt;h3&gt;路线 B：纯内网自签，客户端配 insecure-registries&lt;/h3&gt;
&lt;p&gt;没有域名、仓库只在内网用，可以自签证书甚至直接 HTTP，但必须在&lt;strong&gt;每一台要访问仓库的 Docker 客户端&lt;/strong&gt;上把仓库地址声明为不安全仓库。编辑客户端的 &lt;code&gt;/etc/docker/daemon.json&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;insecure-registries&quot;: [&quot;192.168.1.10:5000&quot;]
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改完重启 Docker（&lt;code&gt;systemctl restart docker&lt;/code&gt;）才生效。代价要心里有数：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;这个地址从此走明文 HTTP（或不验证书），同网段有人抓包就能看到镜像内容和登录凭据的 Base64（等于明文）。&lt;/li&gt;
&lt;li&gt;每台新机器都要记得加这一行，漏了就报证书/协议错误（排障一节会讲到这个经典报错）。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;所以 insecure-registries 只适合可信内网临时用，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;只要仓库地址会出内网，就必须上正规 HTTPS&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h2&gt;第四步：全流程实战（推一个镜像上去）&lt;/h2&gt;
&lt;p&gt;仓库地址下面统一用 &lt;code&gt;registry.example.com:5000&lt;/code&gt; 举例（走的路线 A，HTTPS 已配好；内网场景换成你的 IP:5000）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;1. 登录&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker login registry.example.com:5000
# 输入刚才 htpasswd 里建的账号密码
# Login Succeeded 才算成功
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;登录凭据会存进 &lt;code&gt;~/.docker/config.json&lt;/code&gt;（Base64 编码，不是加密，保护好这个文件）。两个卫生习惯：服务器上多人共用账号时，用完执行 &lt;code&gt;docker logout registry.example.com:5000&lt;/code&gt; 把凭据清掉；在 CI 里则用只给这次任务的临时账号密码通过环境变量注入，不要把 &lt;code&gt;config.json&lt;/code&gt; 打进任何镜像或提交进任何仓库——它进镜像等于把仓库钥匙送给所有能拉到镜像的人。凭据一旦怀疑泄露，处理方式是回 htpasswd 重新生成该用户的密码，旧密码立即失效，这也是 htpasswd 方案运维上为数不多的便利之处。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 给镜像打仓库标签&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;镜像要推到哪个仓库，是由它的名字决定的——名字前缀必须是仓库地址。拿 &lt;a href=&quot;/posts/dockerfile-guide/&quot;&gt;Dockerfile 篇&lt;/a&gt; 打出来的 &lt;code&gt;myapp:1.0&lt;/code&gt; 举例：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker tag myapp:1.0 registry.example.com:5000/myapp:1.0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;想分项目管理可以再加一层目录，如 &lt;code&gt;registry.example.com:5000/team/myapp:1.0&lt;/code&gt;，Registry 对这种多级路径原生支持。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 推送&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker push registry.example.com:5000/myapp:1.0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出里每一层后面的 &lt;code&gt;Pushed&lt;/code&gt; / &lt;code&gt;Layer already exists&lt;/code&gt; 说明分层上传在工作：已存在的层不会重复传，这是镜像分层设计带来的天然增量。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 删掉本地，重新拉回来验证&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker rmi registry.example.com:5000/myapp:1.0
docker pull registry.example.com:5000/myapp:1.0
docker images | grep myapp
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;能重新拉回来并正常 &lt;code&gt;docker run&lt;/code&gt;，整条链路才算真的通了。再补两个日常会用到的点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;同一个镜像推多个版本&lt;/strong&gt;就是重复打不同标签再 push，如 &lt;code&gt;myapp:1.0&lt;/code&gt;、&lt;code&gt;myapp:1.1&lt;/code&gt;、&lt;code&gt;myapp:latest&lt;/code&gt; 可以同时指向构建产物；&lt;code&gt;latest&lt;/code&gt; 只是个普通标签，不会自动指向最新版，养成习惯是版本号标签必推、&lt;code&gt;latest&lt;/code&gt; 顺手带上，拉取时尽量写明版本号，别养成只写 &lt;code&gt;latest&lt;/code&gt; 的习惯，出了问题都不知道自己跑的是哪一版。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;给别的机器用&lt;/strong&gt;：其他服务器上先 &lt;code&gt;docker login&lt;/code&gt; 一次，之后在 Compose 里把 &lt;code&gt;image:&lt;/code&gt; 写成带仓库前缀的完整名字，&lt;code&gt;docker compose pull&lt;/code&gt; 就会自动从私有仓库拉——私有仓库和 Compose 的配合不需要任何额外配置，地址写对就行。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;也可以用 API 查仓库内容：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -u admin:你的密码 https://registry.example.com:5000/v2/_catalog
curl -u admin:你的密码 https://registry.example.com:5000/v2/myapp/tags/list
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;进阶：把 Registry 当 Docker Hub 的本地缓存&lt;/h2&gt;
&lt;p&gt;私有仓库还有一个很实用的模式：&lt;strong&gt;pull-through cache（拉取透传缓存）&lt;/strong&gt;。再起一个 Registry 实例，专门当 Docker Hub 的本地镜像站——客户端把镜像源指向它，它本地没有就去 Docker Hub 拉一份、存下来，下次直接本地供。前面说的「躲开 Docker Hub 限流、内网加速」靠的就是它。配置只需要三行环境变量：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;  hub-cache:
    image: registry:2
    container_name: hub-cache
    restart: unless-stopped
    ports:
      - &quot;127.0.0.1:5001:5000&quot;
    volumes:
      - ./cache-data:/var/lib/registry
    environment:
      - REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;客户端在 &lt;code&gt;daemon.json&lt;/code&gt; 里把这个地址设为镜像加速地址（注意：这是给 Docker 守护进程用的 &lt;code&gt;registry-mirrors&lt;/code&gt;，和前面客户端信任自签仓库的 &lt;code&gt;insecure-registries&lt;/code&gt; 是两个不同字段，别混）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;registry-mirrors&quot;: [&quot;http://192.168.1.10:5001&quot;]
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重启 Docker 后，&lt;code&gt;docker pull nginx&lt;/code&gt; 时守护进程会先问本地缓存要。这个缓存仓库是&lt;strong&gt;只读拉取&lt;/strong&gt;的（推不进去，push 会被拒），所以它和前面存自己镜像的主仓库是两个实例、两个目录，职责分开：主仓库存自己的资产，缓存仓库当公网的本地副本。缓存同样会越攒越大，治理方法还是第六节那套删除加 GC，只是缓存删错了代价小——大不了重新去 Hub 拉一次。&lt;/p&gt;
&lt;h2&gt;顺带看懂：仓库的存储结构&lt;/h2&gt;
&lt;p&gt;理解后面删除、GC、备份为什么是那个样子，先花一分钟看懂 &lt;code&gt;./data&lt;/code&gt; 里的布局（路径都在 &lt;code&gt;docker/registry/v2/&lt;/code&gt; 之下）：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;repositories/&amp;lt;镜像名&amp;gt;/&lt;/code&gt;：按镜像名组织的目录，里面 &lt;code&gt;_manifests/tags/&amp;lt;标签&amp;gt;/&lt;/code&gt; 记录每个标签当前指向哪个 manifest，&lt;code&gt;_layers/&lt;/code&gt; 只是链接索引。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;blobs/sha256/&amp;lt;前两位&amp;gt;/&amp;lt;完整digest&amp;gt;/data&lt;/code&gt;：&lt;strong&gt;所有镜像的层和配置都混存在这里&lt;/strong&gt;，按内容哈希寻址。两个镜像共用同一个基础层时，磁盘上只有一份——这就是为什么仓库总占用远小于各镜像大小之和，也是为什么「删一个标签」释放不了多少空间：层可能还被别的标签引用着。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;记住这个模型：标签和清单是「目录」，blob 才是「实体」。删除操作动的是目录，GC 干的是清掉没有目录指向的实体。后面两节就都顺理成章了。&lt;/p&gt;
&lt;h2&gt;第五步：配个 Web 界面（docker-registry-ui）&lt;/h2&gt;
&lt;p&gt;纯 API 查仓库很不直观，社区有个轻量 UI：&lt;code&gt;joxit/docker-registry-ui&lt;/code&gt;，能浏览仓库/标签、看每个标签的大小和层信息。在同一个 Compose 里加一个服务即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;  registry-ui:
    image: joxit/docker-registry-ui:latest
    container_name: registry-ui
    restart: unless-stopped
    ports:
      - &quot;127.0.0.1:8080:80&quot;
    environment:
      - REGISTRY_TITLE=私有镜像仓库
      - REGISTRY_URL=http://registry:5000
      - DELETE_IMAGES=true
    depends_on:
      - registry
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;REGISTRY_URL&lt;/code&gt; 填容器网络里能直达的地址，这里用服务名 &lt;code&gt;registry:5000&lt;/code&gt; 走内网，不绕公网。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;DELETE_IMAGES=true&lt;/code&gt; 打开界面上的删除按钮。删除能真正生效还需要 Registry 侧允许删除 API，下一步在 Registry 的环境变量里加一行 &lt;code&gt;REGISTRY_STORAGE_DELETE_ENABLED=true&lt;/code&gt; 并重建。&lt;/li&gt;
&lt;li&gt;UI 本身没有独立的账号体系，它会把你的浏览器输入的账号密码转发给 Registry 做 Basic Auth——所以前提是 Registry 已开 htpasswd 认证；UI 的端口同样只绑本机或走反代加 HTTPS，别裸奔。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
界面上点「删除」删掉的只是这个标签的 manifest（清单），镜像的层数据（blob）还躺在磁盘上占着空间，不会立刻释放。这不是 UI 的 bug，而是 Registry 的存储模型——真正回收空间要靠下一节的垃圾回收。很多人删了半天发现磁盘没变小，就是卡在这里。
:::&lt;/p&gt;
&lt;h2&gt;第六步：空间治理与垃圾回收&lt;/h2&gt;
&lt;p&gt;私有仓库最常见的运维问题就是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;磁盘被旧镜像悄悄吃满&amp;lt;/span&amp;gt;：CI 每天推几个版本、没人删，几个月后 &lt;code&gt;./data&lt;/code&gt; 涨到几十上百 GB。治理分两步，缺一不可：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步：删掉不要的标签。&lt;/strong&gt; 用 UI 删除，或者调 API：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 先查这个标签对应的 digest
curl -u admin:你的密码 -I \
  -H &quot;Accept: application/vnd.docker.distribution.manifest.v2+json&quot; \
  https://registry.example.com:5000/v2/myapp/manifests/0.9
# 从返回头 Docker-Content-Digest 取值，再按 digest 删除
curl -u admin:你的密码 -X DELETE \
  https://registry.example.com:5000/v2/myapp/manifests/sha256:&amp;lt;digest值&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;前提是 Registry 开了 &lt;code&gt;REGISTRY_STORAGE_DELETE_ENABLED=true&lt;/code&gt;，没开会返回 405。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二步：执行垃圾回收（garbage-collect）&lt;/strong&gt;，把没有 manifest 引用的 blob 真正从磁盘清掉。正确的执行姿势：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/registry
# 1. 先停仓库，避免回收期间有人推拉造成数据不一致
docker compose stop registry
# 2. 用一次性容器跑 GC（--delete-untagged 连没有标签的清单一并清掉）
docker compose run --rm registry \
  bin/registry garbage-collect --delete-untagged /etc/docker/registry/config.yml
# 3. 再启动
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
GC 期间仓库必须停写。官方支持不停机跑（把存储切到只读模式），但对个人部署来说，挑个低峰期停几分钟执行是最稳妥的做法，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;边推边回收有可能把正在上传的层误判成垃圾删掉&amp;lt;/span&amp;gt;。另外 GC 前建议先把 &lt;code&gt;data&lt;/code&gt; 目录整体备份一份，回收错了还有退路。
:::&lt;/p&gt;
&lt;p&gt;回收效果用 &lt;code&gt;du -sh data&lt;/code&gt; 前后对比即可确认。养成习惯：给 CI 的镜像标签带构建号的同时，定期清理老版本，只保留最近若干个。&lt;/p&gt;
&lt;h2&gt;第七步：仓库数据的备份&lt;/h2&gt;
&lt;p&gt;仓库的全部家当就是 &lt;code&gt;./data&lt;/code&gt; 目录（镜像层和清单都在里面），外加 &lt;code&gt;auth/htpasswd&lt;/code&gt; 和证书。备份策略和普通数据卷一致：停服或低峰期打包目录、异地再存一份，具体方法直接套用 &lt;a href=&quot;/posts/docker-volumes-backup/&quot;&gt;《数据卷与备份恢复》&lt;/a&gt; 里的卷备份流程，这里只强调一点：&lt;strong&gt;仓库备份要定期做恢复演练&lt;/strong&gt;——拉一个备份出来起一个临时 Registry，能 &lt;code&gt;_catalog&lt;/code&gt; 列出镜像才算备份有效。&lt;/p&gt;
&lt;h2&gt;第八步：什么时候升级 Harbor&lt;/h2&gt;
&lt;p&gt;如果你的使用已经越过前面说的选型线，Harbor 的离线部署梗概如下，心里有个谱：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;组件构成&lt;/strong&gt;：Harbor 不是一个容器，而是一组：门户（Portal）、核心服务（Core）、自带的 Registry、Job Service（复制/GC 等异步任务）、数据库（PostgreSQL）、缓存（Redis）、日志收集，再加可选的 Trivy 扫描器。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;安装方式&lt;/strong&gt;：从 GitHub 发布页下载离线安装包（&lt;code&gt;harbor-offline-installer-v&amp;lt;版本&amp;gt;.tgz&lt;/code&gt;，自带全部镜像，不依赖外网拉取），解压后改 &lt;code&gt;harbor.yml&lt;/code&gt;（填主机名/域名、HTTPS 证书路径、管理员初始密码、数据目录），然后执行 &lt;code&gt;./install.sh&lt;/code&gt;（需要带 Trivy 就加 &lt;code&gt;--with-trivy&lt;/code&gt;），它会生成 Compose 文件并一键拉起整套服务。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;值得上的规模&lt;/strong&gt;：团队 3 人以上共用、需要按项目分权限、有安全合规或等保要求要做漏洞扫描拦截、多环境/多机房要做镜像复制。反之，一个人一两台机器，Harbor 的运维成本（升级、备份它自己的数据库）会超过收益，老老实实 Registry。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;升级到 Harbor 后，日常真正会高频用到的其实是三个东西，先有个概念：**项目（Project）**是权限和配额的边界，镜像按项目组织，成员角色分管理员/开发者/访客（只读）；**机器人账号（Robot Account）**是给 CI 和服务器拉取专用的、权限可限定到单个项目、可设过期的凭据，替代真人账号到处飞；**保留策略（Retention）**按规则自动清理老标签（比如只保留最近 10 个版本），配合定时 GC，把本文第六节那套手动治理变成平台自动执行。这三样恰好对应 htpasswd 方案最疼的三个点——分不了权、凭据管不住、清理靠手动，这也是判断「该不该升级」最实在的对照表。&lt;/p&gt;
&lt;p&gt;Harbor 的数据模型和 Registry 是两套东西，迁移时不是改个地址就行，而是把旧仓库镜像逐个 &lt;code&gt;pull → tag → push&lt;/code&gt; 搬过去，或者用 Harbor 的仓库复制功能从旧 Registry 同步——规划升级时把这块工作量算进去。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;push 报 &lt;code&gt;http: server gave HTTP response to HTTPS client&lt;/code&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;最经典的一个。客户端默认用 HTTPS 访问仓库，但仓库实际在说 HTTP（没配 TLS），协议对不上。两个解法：给仓库配上正式证书（路线 A），或者在&lt;strong&gt;客户端&lt;/strong&gt;的 &lt;code&gt;daemon.json&lt;/code&gt; 里把该地址加进 &lt;code&gt;insecure-registries&lt;/code&gt; 并重启 Docker。后者只适合内网，别拿它当长期方案。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;login 或 push 报 &lt;code&gt;unauthorized&lt;/code&gt; / &lt;code&gt;denied: requested access to the resource is denied&lt;/code&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;按顺序查：①账号密码对不对（拿同一组账号 &lt;code&gt;curl -u&lt;/code&gt; 请求 &lt;code&gt;/v2/&lt;/code&gt; 验证）；②htpasswd 文件路径和挂载对不对，进容器 &lt;code&gt;docker exec registry cat /auth/htpasswd&lt;/code&gt; 看内容在不在；③密码文件是不是用了非 bcrypt 的老加密方式，新版 Registry 不认，重新用 &lt;code&gt;-Bbn&lt;/code&gt; 生成；④&lt;code&gt;docker login&lt;/code&gt; 的地址和 push 目标地址前缀是否完全一致（带不带端口都算不同地址）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;报 &lt;code&gt;x509: certificate signed by unknown authority&lt;/code&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;证书是自签的或企业 CA 签的，客户端系统不认识这个签发者。要么把 CA 根证书放进客户端的 &lt;code&gt;/etc/docker/certs.d/&amp;lt;仓库地址&amp;gt;/ca.crt&lt;/code&gt;（这是 Docker 官方的按仓库信任方式，比全局 insecure 更克制），要么换 Let&apos;s Encrypt 这类公共证书。自签＋insecure 也能绕过，但等于放弃验证，不推荐。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;经反代 push 大镜像报 413 或中途断开&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;走路线 A 的反代方案时常见：小镜像能推、几百 MB 的大层推到一半失败或直接 413。原因是反代默认的请求体大小和超时在拦：Nginx 需要在对应的 server/location 里放开 &lt;code&gt;client_max_body_size 0;&lt;/code&gt;（0 表示不限）并调大 &lt;code&gt;proxy_read_timeout&lt;/code&gt; / &lt;code&gt;proxy_send_timeout&lt;/code&gt;，同时确认没有开会把上传攒在内存里的请求缓冲（大文件上传建议 &lt;code&gt;proxy_request_buffering off;&lt;/code&gt;）。改完 reload 反代再重试，这类问题基本都在反代层，不在 Registry 本身——直连 5000 端口能推成功，就是铁证。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;pull 时报 &lt;code&gt;manifest unknown&lt;/code&gt; 或 blob 404&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;先确认标签名没写错（&lt;code&gt;tags/list&lt;/code&gt; 查一遍）。如果标签在、拉取中途 404，多半是存储层数据不一致：比如手动删过 &lt;code&gt;data&lt;/code&gt; 目录里的文件、GC 时机不当删掉了还在引用的层，或者磁盘满导致某层没写完。这种情况没有太好的修复手段，删掉这个标签重新 push 一份完整的；这也是为什么前文反复强调 GC 要停写、目录别手动乱删。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;UI 上没有删除按钮，或删除时报 405&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;先确认 UI 的环境变量 &lt;code&gt;DELETE_IMAGES=true&lt;/code&gt; 已设置且重建过容器；再确认 Registry 侧开了 &lt;code&gt;REGISTRY_STORAGE_DELETE_ENABLED=true&lt;/code&gt;——删除 API 默认是关闭的，没开时任何客户端删除都会收到 405 Method Not Allowed，UI 只是把这个错误透传出来而已。两个开关都对了还不行，就绕过 UI 直接用上一节的 API 删除命令验证，先把问题定位在 UI 还是 Registry 本身。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;磁盘满导致 push 失败&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;push 到一半卡住或报 &lt;code&gt;no space left on device&lt;/code&gt;，先 &lt;code&gt;df -h&lt;/code&gt; 和 &lt;code&gt;du -sh /opt/registry/data&lt;/code&gt; 对一下，再走第六节的删除＋GC 流程。临时救急可以先清掉确认无用的老标签再 GC，不要直接去 &lt;code&gt;data&lt;/code&gt; 目录里删文件——删错 blob 就会出现上面那种 404。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;私有仓库的核心价值是：拉取快、镜像不公开、躲开公共仓库限流、可用性自主。&lt;/li&gt;
&lt;li&gt;个人和小团队用官方 Registry 就够：Compose 一个服务起步，&lt;strong&gt;htpasswd 认证和 HTTPS 是底线配置&lt;/strong&gt;，不是可选装饰。&lt;/li&gt;
&lt;li&gt;删除标签只是删清单，&lt;strong&gt;垃圾回收停写执行&lt;/strong&gt;才能真正把磁盘空间收回来。&lt;/li&gt;
&lt;li&gt;仓库数据就是一个目录，备份和恢复演练都要跟上。&lt;/li&gt;
&lt;li&gt;等权限分级、漏洞扫描、跨仓库复制这些需求真的出现时，再沿着 Harbor 的路线升级——工具跟着规模走，不要反过来。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>Rootless Docker 与 Podman：不用 root 的容器路线</title><link>https://www.anexns.cloudns.org/posts/docker-rootless-podman/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-rootless-podman/</guid><description>守护进程不再以 root 常驻：Rootless Docker 的用户命名空间原理与安装、它的能力限制，以及无守护进程的 Podman 怎么用、和 Docker 的命令兼容与选型对比。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;Docker 用起来很方便，但它有一个从第一天起就被反复讨论的问题：&lt;code&gt;dockerd&lt;/code&gt; 守护进程是以 root 身份常驻运行的，容器里的进程默认也离 root 不远。平时自己用没感觉，一旦把服务暴露到公网、跑来路不明的镜像、或者把 &lt;code&gt;docker.sock&lt;/code&gt; 挂给了某个容器，风险面就会突然放大。&lt;/p&gt;
&lt;p&gt;这一篇走另一条路线：&lt;strong&gt;不用 root 跑容器&lt;/strong&gt;。主线分三段：先讲清为什么要 rootless、它靠什么原理做到；再完整实操一遍 Rootless Docker 的安装和使用限制；最后介绍完全无守护进程的 Podman，并把标准 Docker、Rootless Docker、Podman 三者放在一张表里做选型。安全基础还没补的，建议先看《Docker 安全与资源限制实战》：/posts/docker-security-resources/ ，这一篇是它的进阶延续。&lt;/p&gt;
&lt;h2&gt;一、为什么要 Rootless&lt;/h2&gt;
&lt;p&gt;先把风险说具体，不吓唬人，只摆事实。&lt;/p&gt;
&lt;p&gt;标准模式下，Docker 的架构是客户端加守护进程：你敲的每一条 &lt;code&gt;docker&lt;/code&gt; 命令，都是发给以 root 运行的 &lt;code&gt;dockerd&lt;/code&gt; 去执行的。这带来三个现实问题：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;风险点&lt;/th&gt;
&lt;th&gt;具体含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;守护进程是 root&lt;/td&gt;
&lt;td&gt;&lt;code&gt;dockerd&lt;/code&gt; 本身或它拉起的组件一旦出漏洞，攻击者直接拿到宿主机 root&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;容器里的 root 约等于宿主机 root&lt;/td&gt;
&lt;td&gt;默认没有用户命名空间隔离时，容器内 uid 0 就是宿主机 uid 0，逃逸成功即完全控制&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker.sock&lt;/code&gt; 等于 root 权限&lt;/td&gt;
&lt;td&gt;谁能访问 &lt;code&gt;/var/run/docker.sock&lt;/code&gt;，谁就能起一个挂载宿主机根目录的特权容器，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把 docker.sock 挂进容器等于把宿主机 root 交出去&amp;lt;/span&amp;gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;所以判断标准很简单：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Rootless 的核心价值，是把「容器逃逸」的后果从拿到宿主机 root，降级为只拿到一个普通用户。&amp;lt;/span&amp;gt;攻击者就算突破了容器边界，出去之后也只是一个没权限的普通账号，&lt;code&gt;sudo&lt;/code&gt; 都未必有。&lt;/p&gt;
&lt;p&gt;适合考虑 rootless 的场景：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;服务器上要跑第三方镜像、来路不完全可控的服务&lt;/li&gt;
&lt;li&gt;多人共用一台机器，每人想自己管自己的容器&lt;/li&gt;
&lt;li&gt;对外提供服务，想给安全多加一层兜底&lt;/li&gt;
&lt;li&gt;公司合规、安全审计明确要求守护进程不能以 root 运行&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;代价也要提前说清：rootless 不是免费的，它在端口、网络、资源限制上有若干限制，后文第四节会逐条列并给出解法。&lt;/p&gt;
&lt;h2&gt;二、原理：用户命名空间与 uid 映射&lt;/h2&gt;
&lt;p&gt;Rootless 能成立，靠的是 Linux 的用户命名空间（User Namespace）。&lt;/p&gt;
&lt;h3&gt;2.1 什么是用户命名空间&lt;/h3&gt;
&lt;p&gt;用户命名空间允许一个进程在「自己的小世界」里拥有独立的 uid/gid 视图：进程在命名空间内看自己是 uid 0（root），但在宿主机真实视角里，它只是一个普通用户，比如 uid 1000。&lt;/p&gt;
&lt;p&gt;Rootless Docker 启动时，会为当前普通用户创建一个用户命名空间，&lt;code&gt;dockerd&lt;/code&gt; 和它管理的所有容器都活在这个命名空间里面。于是：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;容器里你看到的 root，是假的 root，只在命名空间内有效&lt;/li&gt;
&lt;li&gt;这个假 root 对应到宿主机，是运行 &lt;code&gt;dockerd&lt;/code&gt; 的那个普通用户&lt;/li&gt;
&lt;li&gt;容器内进程对宿主机文件、进程的访问权限，按普通用户计算，碰不到别人的东西&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;2.2 subuid 与 subgid：映射的原材料&lt;/h3&gt;
&lt;p&gt;问题来了：容器镜像里常常不只有 root 一个用户，还有 uid 1、33、999 等各种系统账号。这些 uid 在命名空间里也要有位置，总不能全挤到同一个宿主机 uid 上。&lt;/p&gt;
&lt;p&gt;解决办法是 &lt;code&gt;/etc/subuid&lt;/code&gt; 和 &lt;code&gt;/etc/subgid&lt;/code&gt;。系统会给每个普通用户分配一段&lt;strong&gt;从属 uid 范围&lt;/strong&gt;，默认每人 65536 个，写在文件里长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;anex:100000:65536
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;含义是：用户 &lt;code&gt;anex&lt;/code&gt; 可以使用宿主机 uid 100000 到 165535 这一段，用来映射命名空间内的 uid。映射关系大致如下：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命名空间内 uid&lt;/th&gt;
&lt;th&gt;宿主机真实 uid&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;0（root）&lt;/td&gt;
&lt;td&gt;1000&lt;/td&gt;
&lt;td&gt;运行 dockerd 的用户本人&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;100001&lt;/td&gt;
&lt;td&gt;从 subuid 段顺延&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;33&lt;/td&gt;
&lt;td&gt;100033&lt;/td&gt;
&lt;td&gt;镜像里的系统用户&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;999&lt;/td&gt;
&lt;td&gt;100999&lt;/td&gt;
&lt;td&gt;常见服务账号&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;65535&lt;/td&gt;
&lt;td&gt;165535&lt;/td&gt;
&lt;td&gt;一段范围的上限&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;实际完成这段映射设置的，是 &lt;code&gt;newuidmap&lt;/code&gt; 和 &lt;code&gt;newgidmap&lt;/code&gt; 两个带 setuid 的小工具，它们由 &lt;code&gt;uidmap&lt;/code&gt; 软件包提供，这也是后文安装前置依赖里必须有它的原因。&lt;/p&gt;
&lt;p&gt;一句话总结原理：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Rootless 不是把权限做小了，而是把容器里的 root 翻译成了宿主机上的普通人。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;:::warning
用户命名空间本身也曾出过本地提权漏洞，所以 rootless 是「多一层隔离」，不是「绝对安全」。宿主机内核要保持更新，这个前提在任何模式下都成立。
:::&lt;/p&gt;
&lt;h2&gt;三、Rootless Docker 安装实战&lt;/h2&gt;
&lt;p&gt;以下以 Debian / Ubuntu 系、普通用户 &lt;code&gt;anex&lt;/code&gt; 为例。整个过程&lt;strong&gt;不需要先卸载&lt;/strong&gt;标准 Docker，但两者不要在同一用户下混用，迁移注意事项见第八节。&lt;/p&gt;
&lt;h3&gt;3.1 前置依赖&lt;/h3&gt;
&lt;p&gt;先装齐依赖，缺一个后面都会卡：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo apt update
sudo apt install -y uidmap dbus-user-session slirp4netns fuse-overlayfs
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐个说明它们干什么：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;依赖&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;uidmap&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;提供 &lt;code&gt;newuidmap&lt;/code&gt; / &lt;code&gt;newgidmap&lt;/code&gt;，完成 subuid 映射&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;dbus-user-session&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;让普通用户能跑 &lt;code&gt;systemd --user&lt;/code&gt; 用户级服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;slirp4netns&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;给 rootless 容器提供用户态网络，是默认的网络实现&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;fuse-overlayfs&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;普通用户无法挂载 overlayfs 时的替代存储驱动，性能略差但兼容性好&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;确认 subuid 已分配：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;grep &quot;^$(whoami):&quot; /etc/subuid /etc/subgid
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;正常会输出两行各 65536 的范围。如果为空，用下面命令手动补（把 &lt;code&gt;anex&lt;/code&gt; 换成你的用户名）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 anex
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再确认内核允许普通用户创建用户命名空间（Debian 默认允许，个别加固过的系统会关）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sysctl kernel.unprivileged_userns_clone
# 期望输出 1；若为 0：
sudo sysctl -w kernel.unprivileged_userns_clone=1
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;3.2 取得安装脚本&lt;/h3&gt;
&lt;p&gt;Rootless 模式的安装脚本随 Docker 官方静态包分发，也在官方仓库里提供。最稳妥的路径是装好官方源之后，用包管理器安装 rootless 扩展包：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo apt install -y docker-ce-rootless-extras
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;装完后，当前用户目录下可直接调用脚本（注意：&lt;strong&gt;不要加 sudo&lt;/strong&gt;，全程用普通用户执行）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;dockerd-rootless-setuptool.sh install
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;脚本会自动做这些事：检查依赖与 subuid、生成 &lt;code&gt;~/.config/docker/daemon.json&lt;/code&gt;、写入用户级 systemd 单元 &lt;code&gt;~/.config/systemd/user/docker.service&lt;/code&gt;、把 &lt;code&gt;DOCKER_HOST&lt;/code&gt; 的提示打在输出末尾。&lt;/p&gt;
&lt;h3&gt;3.3 配置环境变量并启动&lt;/h3&gt;
&lt;p&gt;Rootless 的 socket 不在 &lt;code&gt;/var/run/docker.sock&lt;/code&gt;，而在用户自己的运行时目录里。把这两行加进 &lt;code&gt;~/.bashrc&lt;/code&gt;（或你用的 Shell 配置文件）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;export PATH=/usr/bin:$PATH
export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重新登录或 &lt;code&gt;source ~/.bashrc&lt;/code&gt; 后，用用户级 systemd 启动和管理：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl --user start docker
systemctl --user enable docker
systemctl --user status docker
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;验证一把：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker info | grep -i rootless
docker run --rm hello-world
docker run -d --name web -p 8080:80 nginx
curl http://127.0.0.1:8080
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;docker info&lt;/code&gt; 里能看到 &lt;code&gt;rootless&lt;/code&gt; 字样、且 &lt;code&gt;hello-world&lt;/code&gt; 与 Nginx 都正常，就装好了。日常命令和标准 Docker 完全一致，&lt;code&gt;docker ps&lt;/code&gt;、&lt;code&gt;docker compose up -d&lt;/code&gt; 该怎么用还怎么用。&lt;/p&gt;
&lt;h3&gt;3.4 让退出登录后服务不死：enable-linger&lt;/h3&gt;
&lt;p&gt;用户级 systemd 有个默认行为：用户最后一个登录会话退出后，它的用户服务会被一并停掉。服务器场景这显然不行，容器必须常驻。解决办法是给该用户开启 linger：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo loginctl enable-linger anex
loginctl show-user anex | grep Linger
# 输出 Linger=yes 即生效
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;开启后，即使 SSH 断开、用户完全退出，&lt;code&gt;systemctl --user&lt;/code&gt; 管理的 Docker 和容器也会继续运行，开机后也会自动拉起。这一步&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;漏掉的话，会出现「一退出 SSH 容器全没了」的灵异现象&amp;lt;/span&amp;gt;，务必在交付前检查。&lt;/p&gt;
&lt;h2&gt;四、Rootless Docker 的限制清单&lt;/h2&gt;
&lt;p&gt;Rootless 的限制大多来自「你只是个普通用户」这一事实。每条都给解法，能接受再上：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;限制&lt;/th&gt;
&lt;th&gt;原因&lt;/th&gt;
&lt;th&gt;解法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;默认绑不了 1024 以下端口&lt;/td&gt;
&lt;td&gt;普通用户无权绑定特权端口&lt;/td&gt;
&lt;td&gt;改用 8080/8443 再由反代转发；或放宽限制：&lt;code&gt;sudo sysctl -w net.ipv4.ip_unprivileged_port_start=0&lt;/code&gt; 并写入 &lt;code&gt;/etc/sysctl.conf&lt;/code&gt; 持久化&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;容器里 &lt;code&gt;ping&lt;/code&gt; 可能不通&lt;/td&gt;
&lt;td&gt;ICMP 需要 &lt;code&gt;ping_group_range&lt;/code&gt; 许可&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sudo sysctl -w net.ipv4.ping_group_range=&quot;0 2147483647&quot;&lt;/code&gt;，同样建议持久化&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;资源限制不完整&lt;/td&gt;
&lt;td&gt;cgroup v1 下普通用户无权管理 cgroup&lt;/td&gt;
&lt;td&gt;宿主机切到 cgroup v2（统一层级），&lt;code&gt;docker info&lt;/code&gt; 里确认 &lt;code&gt;Cgroup Version: 2&lt;/code&gt; 后，&lt;code&gt;--memory&lt;/code&gt;、&lt;code&gt;--cpus&lt;/code&gt; 等限制才完整可用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;存储驱动性能&lt;/td&gt;
&lt;td&gt;不能挂载内核 overlayfs 时会退到 &lt;code&gt;fuse-overlayfs&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;内核与发行版较新时优先用原生 overlayfs（rootless 已支持）；老系统接受 fuse-overlayfs 的性能损耗，或把数据卷放在快盘上&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;网络性能略低&lt;/td&gt;
&lt;td&gt;默认走 slirp4netns 用户态转发&lt;/td&gt;
&lt;td&gt;对延迟和吞吐敏感的服务先实测；新版本可关注 rootlesskit 的加速选项，达不到要求就用标准模式&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;部分需要特权的操作不可用&lt;/td&gt;
&lt;td&gt;如 &lt;code&gt;--privileged&lt;/code&gt;、&lt;code&gt;--network host&lt;/code&gt; 语义受限&lt;/td&gt;
&lt;td&gt;这类需求本质与 rootless 冲突，单独评估，一般结论是这类服务不适合放 rootless&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;AppArmor 等主机级配置&lt;/td&gt;
&lt;td&gt;普通用户改不了宿主机安全模块&lt;/td&gt;
&lt;td&gt;需要改宿主机配置的部分仍要管理员配合一次&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
把 &lt;code&gt;net.ipv4.ip_unprivileged_port_start&lt;/code&gt; 改成 0 意味着这台机器上&lt;strong&gt;任何&lt;/strong&gt;普通用户都能绑 80/443 等低端口，这是拿一点宿主机安全性换便利。多用户共用的机器上请慎用，单人服务器相对可控。
:::&lt;/p&gt;
&lt;p&gt;总体判断：纯 Web 服务、API、个人项目这些主流场景，rootless 的限制基本都能绕过去；重度依赖底层网络和高性能存储的场景，要先小规模实测再决定。&lt;/p&gt;
&lt;h2&gt;五、Podman：干脆不要守护进程&lt;/h2&gt;
&lt;p&gt;如果说 Rootless Docker 是「守护进程还在，只是换成普通用户跑」，那 Podman 的思路更彻底：&lt;strong&gt;根本不要守护进程&lt;/strong&gt;。&lt;/p&gt;
&lt;h3&gt;5.1 fork/exec 模型&lt;/h3&gt;
&lt;p&gt;Podman 由红帽主导开发。它的命令直接以当前用户身份 fork/exec 出容器进程，没有一个常驻的、权限很高的中间人：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;你是谁，容器就以谁的权限跑，天然默认 rootless&lt;/li&gt;
&lt;li&gt;&lt;code&gt;podman&lt;/code&gt; 进程执行完就退出，不留常驻进程，攻击面随之消失&lt;/li&gt;
&lt;li&gt;也提供了一个可选的 &lt;code&gt;podman.socket&lt;/code&gt; 兼容接口给工具调用，但那是按需的，不是必需品&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这带来的直接好处是和 systemd 的集成非常自然：容器就是普通进程，systemd 可以直接管它的生命周期、日志和重启，不需要再套一层守护进程去对接。&lt;/p&gt;
&lt;h3&gt;5.2 Pod 概念与 Kubernetes 的渊源&lt;/h3&gt;
&lt;p&gt;Podman 有一个 Docker 没有的一等概念：&lt;strong&gt;Pod&lt;/strong&gt;。一个 Pod 里可以放多个容器，它们共享同一个网络命名空间，也就是共享 IP 和端口空间、可以互相用 &lt;code&gt;localhost&lt;/code&gt; 访问。&lt;/p&gt;
&lt;p&gt;这个概念正是从 Kubernetes 借来的——Kubernetes 里最小的调度单位就是 Pod。于是 Podman 多了一条独特的工作流：本地用 Podman 把一组容器跑顺之后，可以用 &lt;code&gt;podman generate kube&lt;/code&gt; 把它导出成 Kubernetes 的 YAML，再拿去集群里部署；反过来也能 &lt;code&gt;podman play kube&lt;/code&gt; 直接按 YAML 起容器。对有朝一日要碰 Kubernetes 的人，这条桥很顺手。&lt;/p&gt;
&lt;h3&gt;5.3 与 systemd 集成：从 generate systemd 到 Quadlet&lt;/h3&gt;
&lt;p&gt;老办法是生成 systemd 单元文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;podman generate systemd --name web --files --new
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它会吐出一个 &lt;code&gt;.service&lt;/code&gt; 文件，放进用户或系统的 systemd 目录后，就能用 &lt;code&gt;systemctl&lt;/code&gt; 管理容器启停。需要注意：&lt;code&gt;generate systemd&lt;/code&gt; 在新版本 Podman 里已经标记为不推荐继续使用，官方主推的是 &lt;strong&gt;Quadlet&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;Quadlet 的写法是声明式的：你写一个 &lt;code&gt;web.container&lt;/code&gt; 文件，描述镜像、端口、卷，长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Container]
Image=nginx:latest
PublishPort=8080:80

[Service]
Restart=always

[Install]
WantedBy=default.target
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把它放到 &lt;code&gt;~/.config/containers/systemd/&lt;/code&gt;，执行 &lt;code&gt;systemctl --user daemon-reload&lt;/code&gt; 后，systemd 会自动生成对应的服务，之后 &lt;code&gt;systemctl --user start web&lt;/code&gt; 即可。配置即代码、开机自启、日志进 journal，一套全齐，这是目前 Podman 官方推荐的常驻服务方式。&lt;/p&gt;
&lt;h2&gt;六、Podman 上手与命令对照&lt;/h2&gt;
&lt;p&gt;Podman 在命令行层面高度兼容 Docker，迁移成本主要在习惯，不在语法：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;操作&lt;/th&gt;
&lt;th&gt;Docker&lt;/th&gt;
&lt;th&gt;Podman&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;拉镜像&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker pull nginx&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;podman pull nginx&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;完全一致&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;起容器&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker run -d -p 8080:80 nginx&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;podman run -d -p 8080:80 nginx&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;参数基本通用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;看容器&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker ps&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;podman ps&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;一致&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;看镜像&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker images&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;podman images&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;一致&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;看日志&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker logs web&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;podman logs web&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;一致&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;进容器&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker exec -it web sh&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;podman exec -it web sh&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;一致&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;构建镜像&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker build -t app .&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;podman build -t app .&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;底层是 Buildah，Dockerfile 通用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;编排&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker compose up -d&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;podman compose up -d&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;见下文说明&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;系统信息&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker info&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;podman info&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;输出字段略有差异&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;正因为兼容到这个程度，很多人直接在 Shell 配置里写一行别名先用起来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;alias docker=podman
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;绝大多数日常命令和脚本不用改就能跑。差异主要出现在少数高级参数、以及依赖 &lt;code&gt;docker.sock&lt;/code&gt; 的第三方工具上——那些工具需要改走 &lt;code&gt;podman.socket&lt;/code&gt;，兼容性要逐个验证。&lt;/p&gt;
&lt;p&gt;Podman Compose 的现状要说清：早期是独立的 Python 项目 &lt;code&gt;podman-compose&lt;/code&gt;，功能追赶中；现在的 Podman 自带 &lt;code&gt;podman compose&lt;/code&gt; 子命令，它会调用系统里可用的 Compose 提供者（可以是 Docker Compose，也可以是 podman-compose）。常规的 &lt;code&gt;services&lt;/code&gt;、&lt;code&gt;volumes&lt;/code&gt;、&lt;code&gt;networks&lt;/code&gt;、&lt;code&gt;ports&lt;/code&gt;、&lt;code&gt;environment&lt;/code&gt; 这些主流字段兼容度已经不错，但涉及 &lt;code&gt;deploy&lt;/code&gt;、复杂网络和某些扩展字段时仍可能有出入。&lt;strong&gt;从 Docker 迁过去的 Compose 文件，先在测试环境完整跑一遍再上生产&lt;/strong&gt;，这是稳妥做法。&lt;/p&gt;
&lt;p&gt;补一个 rootful 的说明：Podman 也能用 &lt;code&gt;sudo podman&lt;/code&gt; 以 root 方式运行，但它的设计初衷和最大优势都在 rootless。用 Podman 还全程加 &lt;code&gt;sudo&lt;/code&gt;，等于把它的核心卖点丢了一半。&lt;/p&gt;
&lt;h2&gt;七、三方选型对比&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;标准 Docker&lt;/th&gt;
&lt;th&gt;Rootless Docker&lt;/th&gt;
&lt;th&gt;Podman&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;守护进程&lt;/td&gt;
&lt;td&gt;有，以 root 常驻&lt;/td&gt;
&lt;td&gt;有，以普通用户运行&lt;/td&gt;
&lt;td&gt;无守护进程（socket 可选）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;逃逸后果&lt;/td&gt;
&lt;td&gt;直接宿主机 root&lt;/td&gt;
&lt;td&gt;降为普通用户&lt;/td&gt;
&lt;td&gt;降为普通用户（默认 rootless）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;命令兼容&lt;/td&gt;
&lt;td&gt;本体&lt;/td&gt;
&lt;td&gt;与标准 Docker 完全一致&lt;/td&gt;
&lt;td&gt;高度兼容，少数高级参数有差异&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Compose 生态&lt;/td&gt;
&lt;td&gt;最成熟&lt;/td&gt;
&lt;td&gt;与标准 Docker 完全一致&lt;/td&gt;
&lt;td&gt;可用，复杂文件需验证&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;第三方工具生态&lt;/td&gt;
&lt;td&gt;最丰富，面板/脚本默认支持&lt;/td&gt;
&lt;td&gt;多数支持，需改 socket 路径&lt;/td&gt;
&lt;td&gt;依赖 docker.sock 的工具要适配&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;systemd 集成&lt;/td&gt;
&lt;td&gt;靠 Docker 自己的重启策略&lt;/td&gt;
&lt;td&gt;用户级 systemd 加 linger&lt;/td&gt;
&lt;td&gt;最原生，Quadlet 声明式管理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;限制&lt;/td&gt;
&lt;td&gt;无特殊限制&lt;/td&gt;
&lt;td&gt;低端口、cgroup、网络有若干限制&lt;/td&gt;
&lt;td&gt;个别内核特性与网络场景需验证&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;运维成本&lt;/td&gt;
&lt;td&gt;最低，大家都熟&lt;/td&gt;
&lt;td&gt;中等，要懂用户命名空间&lt;/td&gt;
&lt;td&gt;中等，红帽系资料最全&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;明确建议，分场景给结论：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;个人单机服务器、就自己用&lt;/strong&gt;：默认继续用标准 Docker 就好，生态省心；但务必把安全基本功做足——不乱挂 &lt;code&gt;docker.sock&lt;/code&gt;、不随便 &lt;code&gt;--privileged&lt;/code&gt;、镜像来源可控。这些在 /posts/docker-security-resources/ 里都写过。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;要跑第三方服务、多人共用、或安全要求明确&lt;/strong&gt;：优先 Rootless Docker。命令和 Compose 零学习成本，风险面实打实变小，限制也基本有解。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;红帽系发行版（RHEL / Rocky / AlmaLinux）、重度 systemd 用户、或有 Kubernetes 规划&lt;/strong&gt;：Podman 是更顺的选择，发行版原生支持最好，Pod 到 K8s 的路径也最短。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;依赖大量 Docker 生态工具&lt;/strong&gt;（某些面板、监控、自动化脚本写死了 docker.sock）：先别硬迁，逐个验证兼容性再决定，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;生产环境不要在没验证的情况下直接替换容器运行时&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;八、迁移注意事项&lt;/h2&gt;
&lt;p&gt;从标准 Docker 切到 rootless 或 Podman，有三个坑提前知道：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;**镜像和卷不互通。**三套环境各有自己的存储目录：标准 Docker 在 &lt;code&gt;/var/lib/docker&lt;/code&gt;，Rootless Docker 在 &lt;code&gt;~/.local/share/docker&lt;/code&gt;，Podman 在 &lt;code&gt;~/.local/share/containers&lt;/code&gt;。切过去之后 &lt;code&gt;docker images&lt;/code&gt; 看到的是空的，需要重新 &lt;code&gt;pull&lt;/code&gt;，或用 &lt;code&gt;docker save&lt;/code&gt; / &lt;code&gt;docker load&lt;/code&gt; 把镜像包搬过去；数据卷里的数据要单独导出导入，别指望原地继承。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;**Compose 文件要回归测试。**Rootless Docker 用的是同一套 Compose，基本无感；Podman 侧如第六节所说，主流字段没问题，边角字段（扩展网络、特殊设备映射、健康检查细节）逐项验。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;**别在同一台生产机上长期混装两套。**调试期并存没问题，但长期混装会带来端口占用分不清、镜像版本对不上、排障时不知道命令打到哪套环境的问题。选定一套，把另一套的容器迁完就清理干净。特别是 socket 路径：标准模式是 &lt;code&gt;/var/run/docker.sock&lt;/code&gt;，rootless 是 &lt;code&gt;/run/user/&amp;lt;uid&amp;gt;/docker.sock&lt;/code&gt;，&lt;code&gt;DOCKER_HOST&lt;/code&gt; 指错地方时会出现「命令能跑但容器列表是空的」这种误导性现象，先查这个变量。&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;迁移节奏建议：先在一台测试机或一个不重要的服务上试点，跑满一两周，把端口、备份、自动更新、监控这些周边都接回去，确认无坑后再迁主力服务。&lt;/p&gt;
&lt;h2&gt;九、排障小节&lt;/h2&gt;
&lt;h3&gt;9.1 Rootless Docker 装完起不来，先查 XDG_RUNTIME_DIR&lt;/h3&gt;
&lt;p&gt;典型报错是启动时提示找不到运行时目录或 socket 路径异常。多见于没通过正常登录会话、直接用 &lt;code&gt;su&lt;/code&gt; 切用户或在某些 cron / 脚本环境里执行。&lt;/p&gt;
&lt;p&gt;排查顺序：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;echo $XDG_RUNTIME_DIR
# 应输出 /run/user/1000 这类路径，为空就是问题所在
ls -ld /run/user/$(id -u)
systemctl --user status docker
journalctl --user -u docker -n 50
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;XDG_RUNTIME_DIR&lt;/code&gt; 为空时，先退出去、用正常方式重新 SSH 登录该用户再试；仍不行，检查 &lt;code&gt;pam_systemd&lt;/code&gt; 是否正常工作、以及该用户的 linger 是否已开。&lt;/p&gt;
&lt;h3&gt;9.2 端口绑不上：permission denied 或对外不通&lt;/h3&gt;
&lt;p&gt;分两种情况：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 情况一：绑 80/443 直接报权限错误
sysctl net.ipv4.ip_unprivileged_port_start
# 输出 1024 说明特权端口下限没放宽，按第四节处理，或改走高位端口加反代

# 情况二：容器起来了但外部访问不通
docker port web
curl -v http://127.0.0.1:8080
ss -tlnp | grep 8080
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;本机 &lt;code&gt;curl&lt;/code&gt; 不通先看容器本身和端口映射；本机通、外网不通，再查宿主机防火墙与云厂商安全组，这与 rootless 无关，别在容器里绕圈子。&lt;/p&gt;
&lt;h3&gt;9.3 systemd 用户服务一退出登录就停&lt;/h3&gt;
&lt;p&gt;症状非常典型：人一断开 SSH，容器全停；重新登录后服务显示 inactive。这就是 linger 没开：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;loginctl show-user $(whoami) | grep Linger
# Linger=no 就是它
sudo loginctl enable-linger $(whoami)
systemctl --user enable docker
systemctl --user start docker
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;顺手确认 &lt;code&gt;docker.service&lt;/code&gt; 是用户级单元而不是系统级：文件应在 &lt;code&gt;~/.config/systemd/user/docker.service&lt;/code&gt;，命令也始终是 &lt;code&gt;systemctl --user&lt;/code&gt;，漏了 &lt;code&gt;--user&lt;/code&gt; 会打到系统级 systemd 上，报找不到单元。&lt;/p&gt;
&lt;h3&gt;9.4 Podman 侧两个常见小问题&lt;/h3&gt;
&lt;p&gt;拉镜像报 short-name 未解析，是因为 Podman 默认要求完整镜像名。把 &lt;code&gt;nginx&lt;/code&gt; 写全为 &lt;code&gt;docker.io/library/nginx&lt;/code&gt; 即可，或在 &lt;code&gt;/etc/containers/registries.conf&lt;/code&gt; 里配置 &lt;code&gt;unqualified-search-registries&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;普通用户跑容器时存储报错、提示 overlay 挂载失败，一般是内核或发行版不支持 rootless overlay，切到 &lt;code&gt;fuse-overlayfs&lt;/code&gt; 即可，在 &lt;code&gt;~/.config/containers/storage.conf&lt;/code&gt; 里把 driver 改为 &lt;code&gt;overlay&lt;/code&gt; 并确保已装 &lt;code&gt;fuse-overlayfs&lt;/code&gt;，或直接使用 &lt;code&gt;vfs&lt;/code&gt; 先跑通（性能最差，只作临时验证）。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇把「不用 root 跑容器」的两条路线讲完了：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;为什么&lt;/strong&gt;：标准 Docker 的守护进程与容器 root 权限过大，逃逸即 root、&lt;code&gt;docker.sock&lt;/code&gt; 即 root，是最值得先堵的口子&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Rootless Docker&lt;/strong&gt;：靠用户命名空间把容器 root 映射成宿主机普通用户，命令与 Compose 零变化，代价是低端口、ping、cgroup v2 等几条可解的限制；装完别忘了 &lt;code&gt;loginctl enable-linger&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Podman&lt;/strong&gt;：更进一步取消守护进程，默认 rootless，与 systemd 和 Kubernetes 的衔接最顺，命令高度兼容 Docker，但依赖 docker.sock 的工具要逐个验证&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;选型&lt;/strong&gt;：个人单机重生态就标准 Docker 加安全基本功，安全优先选 Rootless Docker，红帽系与 K8s 路线选 Podman&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;无论选哪条，都记住一句话：rootless 是纵深防御的一层，不能替代镜像来源审查、最小权限和及时更新。把这一篇和安全篇配合起来看，你的容器安全体系才算完整。&lt;/p&gt;
</content:encoded></item><item><title>Docker 安全与资源限制实战</title><link>https://www.anexns.cloudns.org/posts/docker-security-resources/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-security-resources/</guid><description>把容器关进笼子：非 root 运行、capabilities 收紧、只读文件系统、no-new-privileges，CPU/内存/PID 资源限额的 Compose 写法，以及 docker.sock 挂载、端口暴露、镜像供应链这三类最常见的真实风险。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;前面几篇我们把 Docker 装好、把容器跑起来、又让它能自动更新。但有个问题一直没正面讲：&lt;strong&gt;容器到底有多安全？&lt;/strong&gt; 很多人下意识把容器当成虚拟机，觉得「就算容器里被攻破，也出不了这个盒子」。这篇就把这层窗户纸捅破：先讲清容器默认的权限到底有多大，再一条一条把笼子扎紧——非 root 运行、收紧 capabilities、只读文件系统、资源限额，最后讲三类最常见的真实风险：docker.sock、端口暴露、镜像供应链。文末有一份汇总好的加固版 Compose 模板，可以直接抄。&lt;/p&gt;
&lt;h2&gt;先认清：容器不是虚拟机&lt;/h2&gt;
&lt;p&gt;虚拟机有自己的一套内核，宿主机和虚拟机之间隔着 hypervisor；容器不一样——&lt;strong&gt;所有容器共享宿主机的同一个内核&lt;/strong&gt;，容器里的进程本质上就是宿主机上的进程，只是被 namespace 隔离了视野、被 cgroup 限制了资源。&lt;/p&gt;
&lt;p&gt;更关键的是默认身份：容器里跑的进程默认是 &lt;strong&gt;root（uid 0）&lt;/strong&gt;。由于容器与宿主机共用内核、默认也没有开启 user namespace 重映射，这个 root 虽然被关在隔离环境里，但它离宿主机 root 的距离，远比你想象的近：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;一旦出现内核漏洞或容器运行时漏洞，容器内的 root 就是第一个摸到逃逸门的人；&lt;/li&gt;
&lt;li&gt;挂载配置写错（比如把宿主机目录可读写地挂进容器），容器里的 root 就能直接改宿主机文件；&lt;/li&gt;
&lt;li&gt;给了过大的 capability 或者干脆开了特权模式，隔离基本等于不存在。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;把容器和虚拟机的差别摆在一起看，会更直观：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;虚拟机&lt;/th&gt;
&lt;th&gt;容器&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;内核&lt;/td&gt;
&lt;td&gt;每台虚拟机一套独立内核&lt;/td&gt;
&lt;td&gt;全部容器共享宿主机内核&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;隔离层&lt;/td&gt;
&lt;td&gt;hypervisor（硬件虚拟化）&lt;/td&gt;
&lt;td&gt;namespace（视野隔离）+ cgroup（资源限制）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;默认身份&lt;/td&gt;
&lt;td&gt;虚拟机内的 root 与宿主机无关&lt;/td&gt;
&lt;td&gt;容器内 root 默认就是宿主机的 uid 0&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;逃逸难度&lt;/td&gt;
&lt;td&gt;要打穿 hypervisor 或虚拟机内核&lt;/td&gt;
&lt;td&gt;内核、运行时任一环节出洞都可能直达宿主机&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;容器的两根支柱里，namespace 负责「看不见」——看不见其他容器的进程、网络、挂载点；cgroup 负责「用不多」——CPU、内存、进程数都有配额。但请注意，这两根支柱管的都是「正常情况下」的行为，它们不是为对抗「容器内已经拿到 root 的攻击者」设计的。攻击者手里有了容器内 root，他要做的事情就是在内核的系统调用接口上找缝、在你配错的挂载和权限里找门。宿主机内核暴露给每个容器的系统调用有数百个，这就是容器逃逸新闻隔一段时间就出现一次的根本原因。&lt;/p&gt;
&lt;p&gt;所以容器安全的核心思路不是「相信隔离」，而是&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;最小权限&lt;/strong&gt;&amp;lt;/span&amp;gt;：能不给 root 就不给 root，能不给的能力就不给，能不写的目录就不让写，能不占的资源就限死。下面逐项来。这几项措施还有一个共同点：它们防的不只是外部攻击者，也防应用自己——一个有 bug 的程序以 root 身份在可写文件系统里跑出破坏，损失和被攻击没有区别。&lt;/p&gt;
&lt;h2&gt;一、非 root 运行：把默认 root 换掉&lt;/h2&gt;
&lt;p&gt;这是收益最大、成本最低的一项加固。分两种情况：镜像本身支持用普通用户跑的，你只需要在 Compose 里指定；镜像默认必须 root 启动的，就要在 Dockerfile 里自己建用户。&lt;/p&gt;
&lt;h3&gt;Compose 里直接指定 user&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    user: &quot;1000:1000&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;user&lt;/code&gt; 的格式是 &lt;code&gt;uid:gid&lt;/code&gt;。这里的 1000 是宿主机上你普通用户的编号，先在宿主机上查清楚再写：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;id
# 输出示例：uid=1000(anex) gid=1000(anex) groups=1000(anex),...
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;写成和宿主机用户相同的 uid/gid，还有个附带好处：容器往数据卷里写的文件，属主正好就是你本人，宿主机上管理起来不会出现一堆 root 属主的文件。&lt;/p&gt;
&lt;h3&gt;Dockerfile 里建用户&lt;/h3&gt;
&lt;p&gt;自己打的镜像，在 Dockerfile 里建一个专用用户并切换过去：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;FROM node:22-alpine

WORKDIR /app
COPY . .

# 建一个无登录权限的普通用户
RUN addgroup -S app &amp;amp;&amp;amp; adduser -S app -G app \
    &amp;amp;&amp;amp; chown -R app:app /app

USER app

CMD [&quot;node&quot;, &quot;server.js&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;USER&lt;/code&gt; 要写在需要 root 权限的操作（装依赖、改属主）之后。上面用的是 Alpine 的 &lt;code&gt;addgroup/adduser&lt;/code&gt; 写法；如果是 Debian 系基础镜像，对应命令是 &lt;code&gt;groupadd&lt;/code&gt; / &lt;code&gt;useradd&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;RUN groupadd -r app &amp;amp;&amp;amp; useradd -r -g app -s /usr/sbin/nologin app
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;很多官方镜像（PostgreSQL、Redis、Nginx 等）内部已经定义了普通用户，有的还提供入口脚本在启动时自动降权，这类镜像保持默认即可，不用强行再套一层 &lt;code&gt;user&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;还有一种常见模式值得了解：入口脚本&lt;strong&gt;先以 root 身份做准备工作&lt;/strong&gt;（建目录、改属主、生成配置），&lt;strong&gt;再降权到普通用户运行主进程&lt;/strong&gt;，工具通常是镜像自带的 &lt;code&gt;gosu&lt;/code&gt; 或 &lt;code&gt;su-exec&lt;/code&gt;。官方 PostgreSQL 镜像就是这么干的：初始化数据库必须先碰一堆 root 才能改的文件，初始化完立刻降权。这种镜像如果你强行在 Compose 里写 &lt;code&gt;user: &quot;1000:1000&quot;&lt;/code&gt;，入口脚本连准备工作都做不了，反而起不来。判断方法很简单：先看镜像文档有没有说支持指定用户；没把握时先不加 &lt;code&gt;user&lt;/code&gt; 跑一遍，再用下面这条命令确认容器里主进程实际是谁在跑：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec myapp ps aux
# 或只看 1 号进程的身份
docker exec myapp id
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出里主进程是普通用户，就说明镜像自己处理好了降权；全是 root，再考虑用 &lt;code&gt;user&lt;/code&gt; 或换镜像。&lt;/p&gt;
&lt;h3&gt;卷权限问题：加了 user 之后最常见的坑&lt;/h3&gt;
&lt;p&gt;容器改成 uid 1000 运行后，原先由 root 容器写过的数据卷目录，属主还是 root，容器一启动就报 &lt;code&gt;Permission denied&lt;/code&gt;。解决办法是把卷目录的属主改成对应用户，在宿主机上执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 数据卷是 bind 挂载的本地目录时
sudo chown -R 1000:1000 /opt/myapp/data

# 数据卷是命名卷时，先查它在宿主机上的实际路径
docker volume inspect myapp_data | grep Mountpoint
sudo chown -R 1000:1000 /var/lib/docker/volumes/myapp_data/_data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
不要图省事用 &lt;code&gt;chmod -R 777&lt;/code&gt; 解决问题。那等于把刚扎好的笼子又拆了：任何用户、&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;任何进程都能改你的数据&amp;lt;/span&amp;gt;。改属主（chown）才是正解。
:::&lt;/p&gt;
&lt;h2&gt;二、Capabilities：把 root 的超能力拆开卖&lt;/h2&gt;
&lt;p&gt;Linux 早就把 root 的权限拆成了四十多个独立的 capability（能力），比如绑定低位端口、改系统时间、加载内核模块，各是一项。Docker 默认给每个容器发了其中 14 项，包括 &lt;code&gt;CHOWN&lt;/code&gt;、&lt;code&gt;DAC_OVERRIDE&lt;/code&gt;（绕过文件权限检查）、&lt;code&gt;SETUID&lt;/code&gt;、&lt;code&gt;SETGID&lt;/code&gt;、&lt;code&gt;NET_RAW&lt;/code&gt;、&lt;code&gt;NET_BIND_SERVICE&lt;/code&gt; 等——对绝大多数应用来说，这份默认清单还是给多了：一个只提供 HTTP 接口的服务，既不需要绕过文件权限，也不需要发原始网络包。这些多余的能力平时躺着不动，可一旦进程被攻破，它们就全是攻击者手里的工具：&lt;code&gt;DAC_OVERRIDE&lt;/code&gt; 让他能读容器里本不该读的密钥文件，&lt;code&gt;NET_RAW&lt;/code&gt; 让他能伪造网络包横向探测内网。正确做法是&lt;strong&gt;先全部收回，再按需逐个加&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;常用 capability 对照：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Capability&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;什么时候需要加&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;NET_BIND_SERVICE&lt;/td&gt;
&lt;td&gt;绑定 1024 以下端口&lt;/td&gt;
&lt;td&gt;容器里直接监听 80/443（如 Nginx 不降权时）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;CHOWN&lt;/td&gt;
&lt;td&gt;修改文件属主&lt;/td&gt;
&lt;td&gt;入口脚本启动时要 chown 数据目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SETUID / SETGID&lt;/td&gt;
&lt;td&gt;切换用户身份&lt;/td&gt;
&lt;td&gt;入口脚本先用 root 做准备、再降权跑主进程（如官方 PostgreSQL 镜像）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;NET_RAW&lt;/td&gt;
&lt;td&gt;发原始包（ping 用的 ICMP）&lt;/td&gt;
&lt;td&gt;容器里需要 ping 探活&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SYS_TIME&lt;/td&gt;
&lt;td&gt;修改系统时间&lt;/td&gt;
&lt;td&gt;极少需要，容器不该改宿主机时间&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;NET_ADMIN&lt;/td&gt;
&lt;td&gt;改路由、防火墙规则&lt;/td&gt;
&lt;td&gt;VPN 类容器才需要，属于高危能力&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SYS_ADMIN&lt;/td&gt;
&lt;td&gt;挂载文件系统等一大票操作&lt;/td&gt;
&lt;td&gt;接近特权模式，能不用就不用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一个判断原则：&lt;code&gt;cap_add&lt;/code&gt; 之后容器起不来、日志报权限错误，再对照着补；一上来就把清单拉满，等于没做。&lt;/p&gt;
&lt;h3&gt;为什么永远别用 --privileged&lt;/h3&gt;
&lt;p&gt;Compose 里它长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    privileged: true
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;privileged: true&lt;/code&gt;（命令行是 &lt;code&gt;--privileged&lt;/code&gt;）意味着：给容器&lt;strong&gt;全部&lt;/strong&gt; capability、放行访问宿主机的全部设备、关掉 seccomp 和 AppArmor 的限制。说白了，它不是「权限大一点」，而是&lt;strong&gt;把 namespace 之外的隔离基本全部放弃&lt;/strong&gt;，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;容器里的 root 约等于宿主机 root&amp;lt;/span&amp;gt;，只剩一层薄薄的视野隔离。网上很多教程为了解决某个权限报错，直接让加 &lt;code&gt;privileged&lt;/code&gt;，这是典型的用拆墙来解决开门问题。真遇到权限问题，先去查到底缺哪个 capability、哪个设备，用 &lt;code&gt;cap_add&lt;/code&gt; 和 &lt;code&gt;devices&lt;/code&gt; 精确补，不要碰这个开关。个别场景（比如在容器里再跑 Docker 的 DinD、某些需要操作硬件的工具）确实离不开它，那也要清楚自己在放弃什么，并且只给那一个容器。&lt;/p&gt;
&lt;h2&gt;三、只读文件系统：容器只能写该写的地方&lt;/h2&gt;
&lt;p&gt;容器被攻破后，攻击者通常第一件事是往磁盘里塞东西：改二进制、放后门、写挖矿程序。如果把容器根文件系统设成只读，这条路直接堵死：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    read_only: true
    tmpfs:
      - /tmp
      - /var/run
    volumes:
      - app_data:/app/data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;read_only: true&lt;/code&gt; 让镜像层只读，程序改不了自己的代码和配置；&lt;/li&gt;
&lt;li&gt;应用总要写临时文件，用 &lt;code&gt;tmpfs&lt;/code&gt; 给 &lt;code&gt;/tmp&lt;/code&gt; 这类目录开一块内存盘，容器删了就没了，正好符合临时文件的定位；&lt;/li&gt;
&lt;li&gt;真正需要持久化的数据，走命名卷或 bind 挂载单独放行，如上面的 &lt;code&gt;/app/data&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;有的应用还要写缓存目录、日志目录，启动报错时看日志里缺哪个目录，逐个用 tmpfs 或卷补上，不要因为麻烦就把 &lt;code&gt;read_only&lt;/code&gt; 撤掉。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;只读文件系统还有个附带好处：倒逼你把「数据」和「程序」分清楚，备份、迁移时该带走哪些目录一目了然。&lt;/p&gt;
&lt;h2&gt;四、no-new-privileges：堵住提权后门&lt;/h2&gt;
&lt;p&gt;Linux 允许进程通过执行 setuid 程序获得更高权限（比如普通用户执行 &lt;code&gt;sudo&lt;/code&gt;）。容器里如果留着这条路，前面把进程降成普通用户的努力就可能被一个 setuid 二进制绕过去。加上这个开关后，进程无论如何都不能通过 exec 获得比父进程更高的权限：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    security_opt:
      - no-new-privileges:true
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;成本几乎为零，没有特殊需求就默认加上。举个具体的画面：不少镜像里带着 &lt;code&gt;passwd&lt;/code&gt;、&lt;code&gt;su&lt;/code&gt; 这类 setuid 程序，普通用户执行它们时能临时获得 root 身份去改密码文件——这正是 setuid 机制的用途，也是它的风险：历史上多次出现过靠 setuid 程序的漏洞把普通用户提成 root 的案例。&lt;code&gt;no-new-privileges&lt;/code&gt; 之后，这类程序在你的容器里会被「去势」：执行时不再赋予额外权限，漏洞的利用链当场断掉，而你的应用几乎不可能真的需要在运行时改密码，功能上毫无损失。注意：如果容器入口脚本本身依赖「先 root 准备、再用 gosu/su-exec 降权」这类流程，&lt;code&gt;no-new-privileges&lt;/code&gt; 一般不影响它们（降权是往下走，不是提权）；但如果应用在运行时需要调用 setuid 程序提权（很少见），就要斟酌。&lt;/p&gt;
&lt;h2&gt;五、资源限制：别让一个容器拖垮整台机器&lt;/h2&gt;
&lt;p&gt;隔离不只是防攻击，还要防失控：一个容器内存泄漏吃光 RAM、或者 fork 炸弹刷满进程表，整台宿主机上所有服务一起陪葬。资源限额就是给每个容器划好自己的饭碗。&lt;/p&gt;
&lt;h3&gt;Compose 的两种写法&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;写法一：deploy.resources（现行推荐）。&lt;/strong&gt; 这是 Compose 规范的正式写法。早期它只在 Swarm 模式下生效，但现在的 Docker Compose V2 在普通的非 Swarm 环境下同样会应用其中的 &lt;code&gt;limits&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    deploy:
      resources:
        limits:
          cpus: &quot;1.0&quot;
          memory: 512M
        reservations:
          memory: 128M
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;limits&lt;/code&gt; 是硬上限，超了就被限制（CPU 被节流、内存超限触发 OOM Kill）；&lt;code&gt;reservations&lt;/code&gt; 是软性的资源预留，主要影响调度。日常使用把 &lt;code&gt;limits&lt;/code&gt; 写好即可。&lt;/p&gt;
&lt;p&gt;两个容易混淆的点顺带说清。第一，&lt;strong&gt;内存上限和 swap 的关系&lt;/strong&gt;：只设 &lt;code&gt;memory&lt;/code&gt; 不设 swap 上限时，容器能用的 swap 默认可以达到内存上限的同等大小（即总可用量约为上限的两倍）。想彻底封死，可以用老式字段 &lt;code&gt;memswap_limit&lt;/code&gt; 把「内存+swap」总量设成和 &lt;code&gt;mem_limit&lt;/code&gt; 一样大，等于禁用该容器的 swap。第二，&lt;strong&gt;&lt;code&gt;cpus&lt;/code&gt; 和 CPU 权重的区别&lt;/strong&gt;：&lt;code&gt;cpus: &quot;1.0&quot;&lt;/code&gt; 是硬顶——无论机器多空闲，最多用满 1 个核；而 &lt;code&gt;cpu_shares&lt;/code&gt;（权重，默认 1024）只在多个容器抢 CPU 时决定分配比例，不设上限。本文讲的是「限死」，用 &lt;code&gt;cpus&lt;/code&gt; 就对了；权重适合那种「平时随便跑、忙起来按比例分」的场景。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法二：老式兼容写法。&lt;/strong&gt; 在 &lt;code&gt;deploy&lt;/code&gt; 出现之前，大家用的是服务级字段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    mem_limit: 512m
    cpus: 1.0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这套写法在 Compose V2 里仍然有效（会被转换成对应的 cgroup 限制），存量项目不用急着改。但要注意：&lt;strong&gt;如果用 &lt;code&gt;docker stack deploy&lt;/code&gt; 部署到 Swarm，这类非 &lt;code&gt;deploy&lt;/code&gt; 字段会被直接忽略&lt;/strong&gt;——同一份文件，本地跑有限制、上 Swarm 没限制，这种坑最阴。新写的配置统一用 &lt;code&gt;deploy.resources&lt;/code&gt;，一份写法两边都认。&lt;/p&gt;
&lt;h3&gt;pids_limit：防 fork 炸弹&lt;/h3&gt;
&lt;p&gt;内存和 CPU 之外，还有一个经常被忘的维度：进程数。一个失控（或被攻破）的进程无限 fork，能把宿主机的 PID 资源耗尽，让所有服务都起不了新进程。给它封顶：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    pids_limit: 200
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;普通应用几十到一两百个进程绰绰有余，按应用规模给，别留空。&lt;/p&gt;
&lt;h3&gt;ulimits：文件句柄等单项上限&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;ulimits&lt;/code&gt; 用来调单个进程的资源上限，最常见的是打开文件数（nofile）。高并发服务（如反向代理、数据库）经常需要把它调大：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    ulimits:
      nofile:
        soft: 65535
        hard: 65535
      nproc: 4096
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;soft&lt;/code&gt; 是实际生效的上限，&lt;code&gt;hard&lt;/code&gt; 是 soft 能往上调的天花板，一般两者写一致即可。&lt;/p&gt;
&lt;h3&gt;验证限制是否真的生效&lt;/h3&gt;
&lt;p&gt;写完别靠感觉，用 &lt;code&gt;docker stats&lt;/code&gt; 看实测：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker stats
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出里 &lt;code&gt;MEM USAGE / LIMIT&lt;/code&gt; 一列会直接显示每个容器的内存用量和上限——上限显示的是你设的 512MiB，而不是宿主机总内存，说明限制生效了。也可以查单个容器的 cgroup 限额：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker inspect app --format &apos;{{.HostConfig.Memory}} {{.HostConfig.NanoCpus}}&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出的字节数对得上你的配置（512M = 536870912），就是真的落地了。&lt;/p&gt;
&lt;h2&gt;六、专项风险一：docker.sock 挂载&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;/var/run/docker.sock&lt;/code&gt; 是 Docker 守护进程的控制入口。谁能访问这个 socket，谁就能创建任意容器、把宿主机根目录挂进特权容器读出来——&lt;strong&gt;挂 docker.sock 进容器，等于把宿主机 root 交给那个容器&lt;/strong&gt;。容器一旦被攻破，攻击者一条命令就能在宿主机上开一个带完整权限的新容器，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;前面所有加固全部归零&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;但偏偏有些工具离不开它：上一篇 &lt;a href=&quot;/posts/linux-docker-auto-update/&quot;&gt;《如何在Linux自动更新Docker容器》&lt;/a&gt; 里的 Watchtower 要靠它重建其他容器，日志工具 Dozzle 要靠它读容器列表。这类工具要用，但要按「不得不挂」来对待：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;只给真正需要的工具挂&lt;/strong&gt;，业务容器永远不挂；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;别被「只读挂载」骗了&lt;/strong&gt;：写成 &lt;code&gt;/var/run/docker.sock:/var/run/docker.sock:ro&lt;/code&gt; 并不能让它变只读——&lt;code&gt;ro&lt;/code&gt; 限制的是文件系统层面的改名删除，而通过 socket 发给守护进程的 API 请求（建容器、删容器）照样畅通无阻。指望靠 &lt;code&gt;:ro&lt;/code&gt; 防写，是自欺欺人；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;加一层 socket 代理&lt;/strong&gt;：用 &lt;code&gt;tecnativa/docker-socket-proxy&lt;/code&gt; 这类工具夹在中间，只放行白名单内的 API（比如只允许 &lt;code&gt;GET&lt;/code&gt; 查列表、禁止 &lt;code&gt;POST&lt;/code&gt; 建容器），业务工具连代理、不直连真 socket；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;只绑本机、加认证&lt;/strong&gt;：如果用的是 TCP 方式的 &lt;code&gt;DOCKER_HOST&lt;/code&gt;，必须绑 &lt;code&gt;127.0.0.1&lt;/code&gt; 并启用 TLS 双向认证，裸奔的 2375 端口在公网上等于公开送出一台宿主机。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;最后提一个根子上的备选方案：&lt;strong&gt;Rootless Docker&lt;/strong&gt;。它让 Docker 守护进程本身就以普通用户身份运行，并借助 user namespace 把容器里的 root 映射成宿主机上的一个无权用户——这样即使容器被攻破、即使攻击者摸到了 docker.sock，他在宿主机上也只是一个普通用户的权限，杀伤力小一个数量级。代价是部分功能受限（比如绑低位端口、某些网络模式需要额外配置）。新装机器、又特别在意这条线的，可以从一开始就按 rootless 模式部署；已有环境不必为此推倒重来，先把前面几节的常规加固做扎实，收益已经占了大头。&lt;/p&gt;
&lt;h2&gt;七、专项风险二：端口暴露面收敛&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;docker ps&lt;/code&gt; 里 &lt;code&gt;0.0.0.0:8080-&amp;gt;80/tcp&lt;/code&gt; 这一行，意思是这个端口对&lt;strong&gt;所有网卡&lt;/strong&gt;开放，包括公网网卡。很多数据库、面板就是这么被全网扫描扫到、然后被爆破的。收敛方法很简单：不需要公网直连的服务，只绑回环地址，再由反向代理统一对外：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:latest
    ports:
      - &quot;127.0.0.1:8080:8080&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这样端口只在本机可达，外面访问走 Nginx/Caddy 反向代理，加 HTTPS、加认证都在代理层统一做。养成定期巡检的习惯：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker ps --format &apos;table {{.Names}}\t{{.Ports}}&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐行看 &lt;code&gt;PORTS&lt;/code&gt; 列，凡是 &lt;code&gt;0.0.0.0&lt;/code&gt; 开头又不该对外的，当场改掉。再配合宿主机上 &lt;code&gt;ss -tlnp&lt;/code&gt; 核对实际监听，两边对得上才算干净。&lt;/p&gt;
&lt;p&gt;:::warning
一个常见误解：以为在云厂商防火墙或 ufw 里挡住就行。Docker 会自己写 iptables 规则转发端口，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;绕过 ufw 的默认策略&lt;/strong&gt;&amp;lt;/span&amp;gt;，不少人就是这样「防火墙明明没放行、端口却全网可达」。最可靠的收敛点是绑定地址本身：写死 &lt;code&gt;127.0.0.1&lt;/code&gt;，谁都绕不过去。
:::&lt;/p&gt;
&lt;h2&gt;八、专项风险三：镜像供应链&lt;/h2&gt;
&lt;p&gt;容器跑的代码，绝大部分不是你写的，是你从镜像仓库拉的。镜像来源不可信，前面所有加固都是在保护别人的后门。三条纪律：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;只用可信来源&lt;/strong&gt;：官方镜像、知名组织、或者自己构建的。来路不明的镜像——论坛里随手发的、教程里没头没尾的 &lt;code&gt;latest&lt;/code&gt;——不要跑，尤其不要给它任何挂载和特权。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;固定版本，别裸用 latest&lt;/strong&gt;：&lt;code&gt;nginx:latest&lt;/code&gt; 今天和下个月可能是两个东西，出问题都没法复现。写到明确版本号 &lt;code&gt;nginx:1.27.3&lt;/code&gt;，更新时人工改版本号，过程可控、可回滚。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;重要服务固定 digest&lt;/strong&gt;：版本标签也可能被覆盖推送，摘要（digest）是内容哈希，锁死了就绝无二义：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: nginx:1.27.3@sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;digest 可以在 &lt;code&gt;docker pull&lt;/code&gt; 后用 &lt;code&gt;docker inspect --format &apos;{{index .RepoDigests 0}}&apos; nginx:1.27.3&lt;/code&gt; 查到。配合 &lt;a href=&quot;/posts/linux-docker-auto-update/&quot;&gt;自动更新那篇&lt;/a&gt; 的做法：定期更新镜像、修补已知漏洞，但更新动作要经过你的确认，而不是无声地换成某个「最新版」。另外定期用 &lt;code&gt;docker scout&lt;/code&gt; 或 Trivy 扫一遍在用镜像的已知漏洞，做到心里有数。&lt;/p&gt;
&lt;p&gt;还有一条选镜像的经验：&lt;strong&gt;基础镜像越小，攻击面越小&lt;/strong&gt;。一个完整发行版镜像里塞着几百个你永远用不上的软件包，每一个都是潜在的漏洞载体。同样的应用，能选 Alpine 这类精简版就别选完整版；更进一步，Google 的 distroless 镜像连 shell 和包管理器都不带，攻击者就算进了容器，也没有趁手的工具可用。自己构建镜像时同理：多阶段构建把编译工具留在构建阶段，最终镜像只带运行必需的文件，这既是体积优化，更是实打实的安全优化。&lt;/p&gt;
&lt;h2&gt;九、加固版 Compose 模板（汇总）&lt;/h2&gt;
&lt;p&gt;把上面各项拼到一起，就是一份可以直接抄走改名的模板：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: myapp:1.4.2            # 固定版本，不用 latest
    container_name: app
    restart: unless-stopped
    user: &quot;1000:1000&quot;             # 非 root 运行
    read_only: true               # 根文件系统只读
    tmpfs:
      - /tmp
    volumes:
      - app_data:/app/data        # 只有数据目录可写
    ports:
      - &quot;127.0.0.1:8080:8080&quot;     # 只绑本机，对外走反向代理
    cap_drop:
      - ALL                       # 能力先全收
    cap_add:
      - NET_BIND_SERVICE          # 再按需加
    security_opt:
      - no-new-privileges:true    # 禁止提权
    pids_limit: 200               # 防 fork 炸弹
    deploy:
      resources:
        limits:
          cpus: &quot;1.0&quot;
          memory: 512M
    ulimits:
      nofile:
        soft: 65535
        hard: 65535
    logging:
      driver: json-file
      options:
        max-size: &quot;20m&quot;
        max-file: &quot;3&quot;

volumes:
  app_data:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;不是每个应用都要全套照搬：起不来就看日志，缺目录补 tmpfs、缺权限补 capability，一项项对着报错放宽，但每放宽一项都要知道自己在放什么。&lt;/p&gt;
&lt;p&gt;给存量服务上这份模板，建议一项一项来、每上一项重启验证一次，而不是十几行同时砸下去——真出了问题，git 记录里能清楚看到是哪一项引起的，回滚也只需要撤那一项。顺序上按三批推进：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;顺序&lt;/th&gt;
&lt;th&gt;措施&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;先上&lt;/td&gt;
&lt;td&gt;&lt;code&gt;no-new-privileges&lt;/code&gt;、资源限制、端口绑定&lt;/td&gt;
&lt;td&gt;无副作用，这三项基本不会让正常应用起不来&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;再上&lt;/td&gt;
&lt;td&gt;&lt;code&gt;cap_drop&lt;/code&gt;、&lt;code&gt;read_only&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;最容易触发权限报错，放在工作日手边有时间排障的时候做&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;最后&lt;/td&gt;
&lt;td&gt;&lt;code&gt;user&lt;/code&gt; 非 root 化&lt;/td&gt;
&lt;td&gt;影响面最大（涉及数据卷属主），单独处理&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;十、排障：加了限制之后容器起不来&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;一启动就退出、日志报 Permission denied。&lt;/strong&gt; 大概率是 &lt;code&gt;user&lt;/code&gt; 或 &lt;code&gt;read_only&lt;/code&gt; 引起的：先对照日志里报的路径，目录问题用 &lt;code&gt;chown&lt;/code&gt; 改属主或补 &lt;code&gt;tmpfs&lt;/code&gt;/卷；不要第一反应就把限制撤了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;容器莫名其妙消失/重启，日志里没报错。&lt;/strong&gt; 怀疑被 OOM Kill 了——内存超限时内核直接杀进程，应用自己来不及写日志。查容器的死因：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker inspect app --format &apos;{{.State.OOMKilled}} {{.State.ExitCode}}&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;OOMKilled&lt;/code&gt; 为 &lt;code&gt;true&lt;/code&gt; 就实锤了（退出码通常是 137）。宿主机层面也能在内核日志里找到记录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;dmesg | grep -i &quot;out of memory&quot;
# 或
journalctl -k | grep -i oom
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;确认是正常业务增长就适当调大 &lt;code&gt;memory&lt;/code&gt; 上限；如果是内存泄漏，调上限只是续命，该修还得修。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;CPU 限额设了但服务变卡。&lt;/strong&gt; &lt;code&gt;docker stats&lt;/code&gt; 里看 &lt;code&gt;%CPU&lt;/code&gt; 是否长期顶在限额附近（1.0 核的限额对应 100%）。顶格说明限额给小了或者应用有死循环，先分清再调。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;cap 砍完后端口绑不上。&lt;/strong&gt; 非 root 用户绑 1024 以下端口需要 &lt;code&gt;NET_BIND_SERVICE&lt;/code&gt;，要么把这个 capability 加回来，要么让应用监听高位端口（如 8080）、由外层映射解决。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;日志里刷 &lt;code&gt;Operation not permitted&lt;/code&gt;。&lt;/strong&gt; 这是 capability 被收走后的典型报错：进程想做一件它以前能做、现在没能力做的事。对照第二节的表逐项排查——改文件属主失败是缺 &lt;code&gt;CHOWN&lt;/code&gt;，入口脚本降权失败是缺 &lt;code&gt;SETUID&lt;/code&gt;/&lt;code&gt;SETGID&lt;/code&gt;，ping 不通是缺 &lt;code&gt;NET_RAW&lt;/code&gt;。一次只加一项验证，确认是哪一项再固定下来，别一口气把表全抄上。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;退出码 137 是什么意思。&lt;/strong&gt; 容器的退出码 137 等于 128+9，即进程是被 &lt;code&gt;SIGKILL&lt;/code&gt; 强杀的。除了上面说的 OOM Kill，宿主机内存整体不足时内核也会挑容器下手，排查路径相同：先看 &lt;code&gt;OOMKilled&lt;/code&gt; 标记，再翻内核日志确认凶手。与之相邻的 143（128+15）则是被 &lt;code&gt;SIGTERM&lt;/code&gt; 正常终止，一般是 &lt;code&gt;docker stop&lt;/code&gt; 的结果，不用慌。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;认知先行：容器共享内核、默认 root，隔离强度远不如虚拟机，加固的目标是最小权限；&lt;/li&gt;
&lt;li&gt;四件套默认全上：&lt;code&gt;user&lt;/code&gt; 非 root、&lt;code&gt;cap_drop: ALL&lt;/code&gt; 按需加、&lt;code&gt;read_only&lt;/code&gt; + tmpfs、&lt;code&gt;no-new-privileges&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;资源三限：&lt;code&gt;deploy.resources&lt;/code&gt; 限 CPU/内存、&lt;code&gt;pids_limit&lt;/code&gt; 限进程数、&lt;code&gt;ulimits&lt;/code&gt; 调句柄，写完用 &lt;code&gt;docker stats&lt;/code&gt; 验证；&lt;/li&gt;
&lt;li&gt;三个真实风险点：docker.sock 非必要不挂、端口只绑 &lt;code&gt;127.0.0.1&lt;/code&gt; 再走反代、镜像固定版本或 digest 只用可信来源；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;privileged: true&lt;/code&gt; 永远不要出现在你的配置里。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;最后给个推进路线，不用一次到位：今天先把所有服务的端口绑定检查一遍、把裸奔的 &lt;code&gt;0.0.0.0&lt;/code&gt; 收回 &lt;code&gt;127.0.0.1&lt;/code&gt;，这是十分钟的事；这周内给新部署的服务全部套上第九节的模板；存量服务按「先无副作用项、后权限项」的顺序逐台改造。安全加固最怕的不是技术难，而是总觉得「等有空再弄」——而攻击者和失控的进程，从不挑你有空的日子。&lt;/p&gt;
&lt;p&gt;笼子扎紧的代价，无非是部署时多写几行配置、多排一两次权限报错；换来的，是某个容器真出事的那天，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;损失能停在笼子里面&amp;lt;/span&amp;gt;。这笔账，划算。&lt;/p&gt;
</content:encoded></item><item><title>Docker Swarm 入门：多机集群与滚动更新</title><link>https://www.anexns.cloudns.org/posts/docker-swarm/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-swarm/</guid><description>单机装不下、停机不能忍时再往上走一步：Swarm 的经理与工作节点、服务与副本概念、三台机器组集群实战、用 stack 部署、滚动更新与回滚，以及它和 Compose、Kubernetes 的选型边界。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说清楚：什么时候单机不够用了&lt;/h2&gt;
&lt;p&gt;前面十几篇里，我们的服务都跑在一台机器上：一份 Compose 文件、一台服务器、一个 &lt;code&gt;docker compose up -d&lt;/code&gt; 搞定。这套打法简单、省心，但它有两个天花板，撞上任何一个，单机就真的不够用了。&lt;/p&gt;
&lt;p&gt;第一个是&lt;strong&gt;可用性&lt;/strong&gt;。单机意味着单点：服务器宕机、Docker 守护进程崩溃、机房断网，服务就整体消失。Watchtower 更新容器时那几秒的重启窗口可以忍，但机器本身挂掉几小时这种事，如果服务是对外营业的，就忍不了。更现实的场景是：你想给服务器打补丁、换内核、重启 Docker，单机上无路可退，只能挑深夜停机维护。&lt;/p&gt;
&lt;p&gt;第二个是&lt;strong&gt;横向扩容&lt;/strong&gt;。单机的 CPU 和内存就是上限。某个服务火了、流量翻了十倍，你在单机上能做的只有把 &lt;code&gt;replicas&lt;/code&gt; 写大——可副本再多也挤在同一台机器上抢资源，机器本身就是瓶颈。真正需要的是把副本分散到多台机器上，机器不够了再加一台。&lt;/p&gt;
&lt;p&gt;撞上这两堵墙，就需要&quot;集群编排&quot;：让多台机器组成一个整体，你只声明&quot;我要这个服务跑 3 个副本&quot;，系统自己决定每个副本落在哪台机器上，某台机器挂了，副本自动在别的机器上补回来。&lt;/p&gt;
&lt;p&gt;做这件事的工具，名气最大的是 Kubernetes，但它概念多、组件重，学习曲线陡峭。其实 Docker 自己就内置了一个编排器——&lt;strong&gt;Swarm&lt;/strong&gt;。它就藏在你已经装好的 Docker 里，不用额外安装任何软件，一条命令就能把单机 Docker 变成集群节点。Swarm 的定位就是：用你已经会的 Compose 知识，平滑地跨到多台机器上。本篇我们用三台机器把集群组起来，跑服务、玩自愈、做滚动更新，最后把 Swarm、单机 Compose、Kubernetes 三者的选型边界讲清楚。&lt;/p&gt;
&lt;p&gt;:::warning
Swarm 是 Docker 的内置功能，&lt;code&gt;docker swarm&lt;/code&gt; 系列命令在装好 Docker Engine 的机器上直接可用。本文的三台机器请提前各自按系列第一篇的方法装好 Docker，并确保它们之间网络互通（同机房、同内网最好）。
:::&lt;/p&gt;
&lt;h2&gt;核心概念：先把词对上号&lt;/h2&gt;
&lt;p&gt;Swarm 的概念不多，一张表对完号，后面实战就不会晕。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;概念&lt;/th&gt;
&lt;th&gt;人话解释&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;节点（Node）&lt;/td&gt;
&lt;td&gt;集群里的一台机器，装着 Docker 并加入了集群&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;经理节点（Manager）&lt;/td&gt;
&lt;td&gt;集群的&quot;大脑&quot;，保存集群状态、调度副本、接受你的命令；它自己也能干活跑容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;工作节点（Worker）&lt;/td&gt;
&lt;td&gt;纯&quot;干活的&quot;，只负责运行分给它的容器，不参与决策&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;服务（Service）&lt;/td&gt;
&lt;td&gt;你声明的期望状态：&quot;我要 nginx 镜像跑 3 个副本，暴露 80 端口&quot;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;任务（Task）&lt;/td&gt;
&lt;td&gt;服务拆出来的单个副本，落到某个节点上变成一个实际容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;副本（Replicas）&lt;/td&gt;
&lt;td&gt;同一个服务要维持的任务数量，少了 Swarm 自动补，多了自动删&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;栈（Stack）&lt;/td&gt;
&lt;td&gt;一组相关服务的集合，用一份 Compose 文件整体部署、整体管理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;overlay 网络&lt;/td&gt;
&lt;td&gt;跨机器的虚拟网络，不同机器上的容器像在同一个局域网里互相访问&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;路由网格（Routing Mesh）&lt;/td&gt;
&lt;td&gt;在任意节点访问服务的端口，都能被转到某个健康副本上，不用关心副本具体在哪&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这里面最重要的是理解**&quot;服务&quot;和&quot;容器&quot;的区别**。以前你操作的是容器：&lt;code&gt;docker run&lt;/code&gt; 出来一个，死了就是死了。现在你操作的是服务：你只负责声明&quot;应该是什么样&quot;，Swarm 负责让现实不断向声明靠拢——副本死了它补、节点挂了它迁移。这种&quot;声明式&quot;的思维方式，是所有编排系统的共同点，先在这里适应，后面看 Kubernetes 也不会陌生。&lt;/p&gt;
&lt;h2&gt;组集群实战：三台机器变一台&quot;大机器&quot;&lt;/h2&gt;
&lt;p&gt;假设三台机器的内网 IP 分别是：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;机器&lt;/th&gt;
&lt;th&gt;内网 IP&lt;/th&gt;
&lt;th&gt;计划角色&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;node1&lt;/td&gt;
&lt;td&gt;192.168.1.11&lt;/td&gt;
&lt;td&gt;Manager&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;node2&lt;/td&gt;
&lt;td&gt;192.168.1.12&lt;/td&gt;
&lt;td&gt;Worker&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;node3&lt;/td&gt;
&lt;td&gt;192.168.1.13&lt;/td&gt;
&lt;td&gt;Worker&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;第一步：在 node1 上初始化集群&lt;/h3&gt;
&lt;p&gt;在 node1 上执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker swarm init --advertise-addr 192.168.1.11
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--advertise-addr&lt;/code&gt; 是告诉集群其他节点&quot;用这个地址来找我&quot;，多网卡机器上必须写对，写错了后面加入会连不上。执行成功后输出大致如下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Swarm initialized: current node (xxxx) is now a manager.

To add a worker to this swarm, run the following command:

    docker swarm join --token SWMTKN-1-xxxxxx 192.168.1.11:2377
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这一刻，node1 就成了集群的第一个 Manager，集群诞生了。输出里那条现成的 join 命令带着令牌（token），就是给其他机器入伙用的&quot;邀请码&quot;。&lt;/p&gt;
&lt;h3&gt;第二步：其余机器加入&lt;/h3&gt;
&lt;p&gt;在 node2、node3 上分别执行输出里给的那条命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker swarm join --token SWMTKN-1-xxxxxx 192.168.1.11:2377
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;成功后会看到 &lt;code&gt;This node joined a swarm as a worker.&lt;/code&gt;。如果令牌忘了，也不用慌，在 Manager 上随时能重新查看：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 查看 worker 加入令牌
docker swarm join-token worker

# 查看 manager 加入令牌
docker swarm join-token manager
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两种令牌权限不同：拿 worker 令牌加入的只能当 Worker，拿 manager 令牌加入的会成为新的 Manager。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;join 令牌等于集群的入伙凭证，泄露了任何人都能把机器加进你的集群，务必当密码保管。&amp;lt;/span&amp;gt;怀疑泄露时用 &lt;code&gt;docker swarm join-token --rotate worker&lt;/code&gt; 一键轮换，旧令牌立即作废。&lt;/p&gt;
&lt;h3&gt;第三步：验证集群状态&lt;/h3&gt;
&lt;p&gt;回到 Manager（node1）上：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker node ls
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;ID                            HOSTNAME   STATUS   AVAILABILITY   MANAGER STATUS   ENGINE VERSION
a1b2c3 *                      node1      Ready    Active        Leader           27.x
d4e5f6                        node2      Ready    Active                          27.x
g7h8i9                        node3      Ready    Active                          27.x
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三台都是 &lt;code&gt;Ready&lt;/code&gt;，node1 是 &lt;code&gt;Leader&lt;/code&gt;，集群就组好了。注意：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;所有 &lt;code&gt;docker service&lt;/code&gt;、&lt;code&gt;docker stack&lt;/code&gt;、&lt;code&gt;docker node&lt;/code&gt; 管理命令只能在 Manager 上执行&amp;lt;/span&amp;gt;，在 Worker 上敲会直接报错，这是故意的——Worker 不持有集群状态，无权发号施令。&lt;/p&gt;
&lt;h3&gt;经理节点为什么要奇数个&lt;/h3&gt;
&lt;p&gt;Manager 之间靠 Raft 协议同步集群状态，任何决策都需要&quot;多数派&quot;同意。这就决定了 Manager 数量的选择不是越多越好，而是要看容错：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Manager 数量&lt;/th&gt;
&lt;th&gt;决策需要的多数&lt;/th&gt;
&lt;th&gt;能容忍挂掉的 Manager 数&lt;/th&gt;
&lt;th&gt;评价&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;0&lt;/td&gt;
&lt;td&gt;单点，仅适合尝鲜和测试&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;0&lt;/td&gt;
&lt;td&gt;和 1 台没区别，还更脆弱，不要用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;小集群的甜点配置&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;中等规模生产可用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;上限附近，再多同步成本大于收益&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;关键结论：&lt;strong&gt;2 台 Manager 是最差配置&lt;/strong&gt;——挂任意一台就凑不齐多数派，整个集群无法调度，还不如 1 台。所以生产环境要么 3 台、要么 5 台，永远是奇数。还有一个常见误区要避开：Manager 也能跑容器，但节点多了以后，建议用下面的命令把 Manager 设成只调度不干活，避免管理进程和业务容器抢资源：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker node update --availability drain node1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;drain&lt;/code&gt;（排空）会把该节点上的副本迁走并标记为不再接收新副本，这个命令在后面维护单台机器时也非常好用。&lt;/p&gt;
&lt;p&gt;:::warning
本文为了演示方便只设了 1 个 Manager，真实生产请至少 3 个。单 Manager 时它一旦宕机，正在运行的容器不会停（Worker 会继续跑已有副本），但集群无法再调度、无法补副本、无法更新服务——所以只是&quot;暂时死不了&quot;，不是高可用。
:::&lt;/p&gt;
&lt;h2&gt;第一个服务：亲眼看一次自愈&lt;/h2&gt;
&lt;p&gt;在 Manager 上创建第一个服务：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker service create --name web --replicas 3 --publish published=8080,target=80 nginx:alpine
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;参数逐个看：&lt;code&gt;--name web&lt;/code&gt; 服务名；&lt;code&gt;--replicas 3&lt;/code&gt; 要维持 3 个副本；&lt;code&gt;--publish published=8080,target=80&lt;/code&gt; 把容器内的 80 端口通过路由网格发布到集群所有节点的 8080 端口。注意新式写法推荐 &lt;code&gt;published=...,target=...&lt;/code&gt; 的长格式，比老式的 &lt;code&gt;-p 8080:80&lt;/code&gt; 更明确（短格式当然也能用）。&lt;/p&gt;
&lt;p&gt;查看服务与副本分布：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker service ls
docker service ps web
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;NAME   MODE        REPLICAS   IMAGE         PORTS
web    replicated  3/3        nginx:alpine  *:8080-&amp;gt;80/tcp

ID        NAME     IMAGE         NODE      CURRENT STATE
xxxx      web.1    nginx:alpine  node1     Running
yyyy      web.2    nginx:alpine  node2     Running
zzzz      web.3    nginx:alpine  node3     Running
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;REPLICAS 3/3&lt;/code&gt; 表示期望 3 个、实际 3 个，状态健康。Swarm 自动把三个副本均匀摊到了三台机器上。现在，在浏览器或用 curl 访问&lt;strong&gt;任意一台&lt;/strong&gt;机器的 8080 端口：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl http://192.168.1.13:8080
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;都能打开 nginx 的欢迎页——哪怕你访问的这台机器上根本没有空闲副本在监听，路由网格也会把请求转到有副本的节点。这就是集群的感觉：三台机器对外像一台。&lt;/p&gt;
&lt;p&gt;接下来见证自愈。去 node2 上，把 web.2 对应的容器强行删掉，或者干脆直接在 node2 上执行 &lt;code&gt;docker stop&lt;/code&gt; 停掉那个容器。然后回 Manager 上再看：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker service ps web
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;你会看到 web.2 的旧任务变成 &lt;code&gt;Shutdown/Failed&lt;/code&gt;，紧接着一个新的任务被创建并调度起来，&lt;code&gt;REPLICAS&lt;/code&gt; 很快回到 &lt;code&gt;3/3&lt;/code&gt;。整个过程你什么都没做。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;你声明了&quot;3 个副本&quot;，Swarm 就永远让现实等于 3 个，这就是编排的全部魔法。&amp;lt;/span&amp;gt;极端一点，你把 node2 整台机器关机，它的副本会被重新调度到 node1、node3 上补齐——单机时代那种&quot;机器挂了服务就没了&quot;的日子结束了。&lt;/p&gt;
&lt;p&gt;玩够了删掉服务：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker service rm web
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;stack 部署：把 Compose 文件搬上集群&lt;/h2&gt;
&lt;p&gt;单个服务用命令创建还行，真实项目是一组服务加网络加卷，还是得靠文件。这就是 stack：它吃的正是你已经写熟的 Compose 文件，部署命令是 &lt;code&gt;docker stack deploy&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;先看一份能直接用于 stack 的 Compose 文件（保存为 &lt;code&gt;stack.yml&lt;/code&gt;）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  web:
    image: nginx:alpine
    ports:
      - &quot;8080:80&quot;
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure
        max_attempts: 3
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;和普通 Compose 文件九成相同，区别集中在新增的 &lt;code&gt;deploy&lt;/code&gt; 段：&lt;code&gt;replicas&lt;/code&gt; 是副本数，&lt;code&gt;update_config&lt;/code&gt; 控制滚动更新的节奏，&lt;code&gt;restart_policy&lt;/code&gt; 控制副本失败后的重启策略。这些字段的思路在系列的 Compose 进阶篇里已经铺垫过，细节可以回去对照看：&lt;a href=&quot;/posts/docker-compose-advanced/&quot;&gt;Docker Compose 进阶：环境变量、健康检查与多环境&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;部署：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker stack deploy -c stack.yml myapp
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;myapp&lt;/code&gt; 是栈名，栈内所有服务、网络、卷的名字都会自动加上 &lt;code&gt;myapp_&lt;/code&gt; 前缀，避免多栈之间撞名。查看与管理：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker stack ls                 # 所有栈
docker stack services myapp     # 栈里的服务
docker stack ps myapp           # 栈里的全部任务
docker stack rm myapp           # 整个栈一键拆除
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;和 docker compose up 的区别，心里要有数&lt;/h3&gt;
&lt;p&gt;stack 用的是同一份文件格式，但执行者换成了 Swarm，两边行为有几处关键不同：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;docker compose up&lt;/th&gt;
&lt;th&gt;docker stack deploy&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;运行范围&lt;/td&gt;
&lt;td&gt;单台机器&lt;/td&gt;
&lt;td&gt;整个集群多台机器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;副本与调度&lt;/td&gt;
&lt;td&gt;容器就在本机&lt;/td&gt;
&lt;td&gt;按 replicas 分散到各节点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;build:&lt;/code&gt; 字段&lt;/td&gt;
&lt;td&gt;现场构建镜像&lt;/td&gt;
&lt;td&gt;被忽略，镜像必须提前构建好推到仓库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;depends_on&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;控制启动顺序&lt;/td&gt;
&lt;td&gt;被忽略，服务各自独立启动&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;deploy&lt;/code&gt; 段&lt;/td&gt;
&lt;td&gt;单机下基本被忽略（Swarm 模式专用）&lt;/td&gt;
&lt;td&gt;完整生效：副本、更新、重启、资源、放置约束&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;容器名&lt;/td&gt;
&lt;td&gt;可用 container_name 指定&lt;/td&gt;
&lt;td&gt;由 Swarm 自动生成，不可指定&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;更新方式&lt;/td&gt;
&lt;td&gt;up 时重建变化的容器&lt;/td&gt;
&lt;td&gt;声明式收敛 + 滚动更新&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;最需要记住的是 &lt;code&gt;build:&lt;/code&gt; 被忽略这一条：Swarm 节点是多台，每台现场构建既慢又不一致，所以&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;stack 部署的镜像必须先构建好并推送到所有节点都能拉取的镜像仓库&amp;lt;/span&amp;gt;（Docker Hub、私有 Registry 或 Harbor 都行），文件里只写镜像名和标签。本地没推仓库就 deploy，副本会在拉不到镜像的节点上反复失败。&lt;/p&gt;
&lt;h2&gt;滚动更新：换版本不停服&lt;/h2&gt;
&lt;p&gt;服务跑起来只是开始，真正体现编排价值的是更新。假设 nginx 出了新版本，要把镜像从 &lt;code&gt;nginx:1.27-alpine&lt;/code&gt; 升到 &lt;code&gt;nginx:1.28-alpine&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;先看用命令怎么滚动更新一个已有服务：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker service update \
  --image nginx:1.28-alpine \
  --update-parallelism 1 \
  --update-delay 10s \
  web
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--update-parallelism 1&lt;/code&gt; 表示一次只更新 1 个副本，&lt;code&gt;--update-delay 10s&lt;/code&gt; 表示每批更新之间停 10 秒观察。更新过程是：停掉一个旧副本 → 在原地（或别的节点）拉起新版副本 → 等它 Running → 隔 10 秒 → 再动下一个。3 个副本分三批换完，全程服务始终有副本在对外响应，&lt;strong&gt;零停机&lt;/strong&gt;。如果用的是 stack 管理，更新更简单：改掉 &lt;code&gt;stack.yml&lt;/code&gt; 里的镜像标签和 &lt;code&gt;update_config&lt;/code&gt;，重新执行一遍 &lt;code&gt;docker stack deploy -c stack.yml myapp&lt;/code&gt;，Swarm 会自己算出差异并滚动收敛。&lt;/p&gt;
&lt;p&gt;观察更新进度：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker service ps web
docker service inspect --pretty web
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;更新到一半发现新版有 bug？一条命令回滚到上一个版本：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker service rollback web
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Swarm 保存了服务的上一份规格，回滚同样是滚动执行的——旧版本副本逐个替换回来。注意 rollback 只能回退&lt;strong&gt;一步&lt;/strong&gt;，它不是版本历史系统；真正的版本管理靠你的镜像标签和 Git 里的 Compose 文件，这也是为什么 stack 文件要进版本库。&lt;/p&gt;
&lt;p&gt;:::warning
滚动更新零停机的前提是服务本身无状态、且新旧版本能短暂共存（比如数据库表结构变更要兼容新旧两个版本）。有状态的强一致服务别指望靠滚动更新蒙混过关，下一节细说。
:::&lt;/p&gt;
&lt;h2&gt;数据与状态：Swarm 的现实短板&lt;/h2&gt;
&lt;p&gt;必须把话说在前面：&lt;strong&gt;Swarm 天生适合无状态服务，有状态服务在它上面很难受。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;原因在于卷（volume）的本质。Docker 的本地卷是绑在某台具体机器上的：一个数据库服务的副本今天落在 node2，它的卷就在 node2 的硬盘里；明天 node2 宕机，Swarm 在 node3 上把这个副本补起来——可 node3 上没有那份数据，新副本面对的是一个空卷，等于数据&quot;丢&quot;了。对 nginx 这类无状态服务这完全不是问题，副本之间一模一样、随起随灭；但对 MySQL、PostgreSQL 这类服务，这是灾难。&lt;/p&gt;
&lt;p&gt;业界的通行处理方式有三条，按推荐程度排序：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方案&lt;/th&gt;
&lt;th&gt;做法&lt;/th&gt;
&lt;th&gt;适用情况&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;数据库不进 Swarm&lt;/td&gt;
&lt;td&gt;数据库单独部署（单机、主从或云数据库），Swarm 只跑无状态的应用层&lt;/td&gt;
&lt;td&gt;绝大多数中小项目，首选&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;放置约束钉住节点&lt;/td&gt;
&lt;td&gt;用 &lt;code&gt;deploy.placement.constraints&lt;/code&gt; 把有状态服务固定在某台机器，卷不漂移&lt;/td&gt;
&lt;td&gt;接受&quot;这台机器挂了该服务就停&quot;的妥协时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;分布式存储&lt;/td&gt;
&lt;td&gt;上 Ceph、GlusterFS、NFS 或云盘做共享卷&lt;/td&gt;
&lt;td&gt;有专门运维能力的大型场景&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;放置约束的写法长这样，把服务钉在 node2 上：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    deploy:
      placement:
        constraints:
          - node.hostname == node2
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;钉住之后它就不再漂移，本质上是&quot;借 Swarm 的壳、行单机之实&quot;，可用性回到了单机水平，但至少更新和管理统一了。我的建议很明确：&lt;strong&gt;应用层放心上 Swarm，数据库这类有状态核心先留在集群之外&lt;/strong&gt;，等规模真的逼到那一步，再考虑 Kubernetes 生态里的 StatefulSet 和专业存储方案。&lt;/p&gt;
&lt;h2&gt;secrets 与 configs：敏感信息别再写进环境变量&lt;/h2&gt;
&lt;p&gt;在单机 Compose 时代，密码经常直接写在 &lt;code&gt;.env&lt;/code&gt; 或环境变量里，多机集群下这更危险——环境变量在 &lt;code&gt;docker service inspect&lt;/code&gt; 里一览无余。Swarm 内置了 secrets（机密）和 configs（普通配置）两个机制：它们由 Manager 加密保存（静态加密于 Raft 日志中），只在运行时以文件形式挂进需要它的容器，路径是 &lt;code&gt;/run/secrets/&amp;lt;名字&amp;gt;&lt;/code&gt;，且只存在于内存文件系统里，不落盘。&lt;/p&gt;
&lt;h3&gt;secrets 最小例子&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 从标准输入创建 secret，不在命令行和 shell 历史里留明文
printf &apos;myS3cretPass&apos; | docker secret create db_pass -

# 创建服务时挂载
docker service create --name db \
  --secret db_pass \
  -e MYSQL_ROOT_PASSWORD_FILE=/run/secrets/db_pass \
  mysql:8
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意这里给应用的是 &lt;code&gt;MYSQL_ROOT_PASSWORD_FILE&lt;/code&gt; 这个&lt;strong&gt;文件路径&lt;/strong&gt;而不是密码本身——主流数据库镜像都支持用 &lt;code&gt;_FILE&lt;/code&gt; 后缀的环境变量从文件读密码。应用读到的仍是密码，但密码从未出现在环境变量、镜像和 Compose 文件里。&lt;/p&gt;
&lt;h3&gt;configs 最小例子&lt;/h3&gt;
&lt;p&gt;configs 是同一套机制的不加密版，用来分发 nginx 配置这类普通文件，改配置不用重做镜像：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker config create nginx_conf ./nginx.conf

docker service create --name web \
  --config source=nginx_conf,target=/etc/nginx/nginx.conf \
  nginx:alpine
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;配置更新时创建新版本 config 再 &lt;code&gt;docker service update --config-rm / --config-add&lt;/code&gt; 滚动替换即可。两者的小结：&lt;strong&gt;密码、令牌、证书私钥用 secret；普通配置文件用 config；都不要再塞环境变量和镜像层。&lt;/strong&gt;&lt;/p&gt;
&lt;h2&gt;选型：Swarm、Compose、Kubernetes 怎么选&lt;/h2&gt;
&lt;p&gt;最后把三者的边界一次说清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;单机 Compose&lt;/th&gt;
&lt;th&gt;Docker Swarm&lt;/th&gt;
&lt;th&gt;Kubernetes&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;机器数量&lt;/td&gt;
&lt;td&gt;1 台&lt;/td&gt;
&lt;td&gt;2 到几十台&lt;/td&gt;
&lt;td&gt;几台到成千上万台&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;学习成本&lt;/td&gt;
&lt;td&gt;最低，你已经会了&lt;/td&gt;
&lt;td&gt;低，复用 Compose 知识&lt;/td&gt;
&lt;td&gt;高，概念与组件成体系&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;高可用&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;副本自愈 + 多 Manager&lt;/td&gt;
&lt;td&gt;副本自愈 + 更细的控制面冗余&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;功能丰富度&lt;/td&gt;
&lt;td&gt;基础&lt;/td&gt;
&lt;td&gt;够用：滚动更新、secrets、overlay 网络&lt;/td&gt;
&lt;td&gt;极强：自动伸缩、丰富的调度与生态&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;有状态支持&lt;/td&gt;
&lt;td&gt;卷在本机，直观&lt;/td&gt;
&lt;td&gt;弱，需绕开或钉节点&lt;/td&gt;
&lt;td&gt;StatefulSet + 存储生态，完整但复杂&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;运维负担&lt;/td&gt;
&lt;td&gt;几乎为零&lt;/td&gt;
&lt;td&gt;很轻&lt;/td&gt;
&lt;td&gt;需要专人或托管服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;生态现状&lt;/td&gt;
&lt;td&gt;活跃&lt;/td&gt;
&lt;td&gt;仍在维护，功能稳定但生态在收缩&lt;/td&gt;
&lt;td&gt;事实标准，生态庞大&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;我的建议分三档：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;一台机器能装下、停机几分钟能接受&lt;/strong&gt;：继续单机 Compose，别折腾。这仍是个人项目和小型服务的最佳解。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;有了两三台机器、要高可用和不停机更新、团队不想再学一套新系统&lt;/strong&gt;：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;选 Swarm，它的每一分复杂度都花在了刀刃上。&amp;lt;/span&amp;gt;你前面十几篇积累的镜像、网络、Compose 知识全部直接复用，一个下午就能上线。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;规模奔着几十台以上、需要自动伸缩、复杂调度、接第三方生态（监控、日志、服务网格全家桶）&lt;/strong&gt;：直接 Kubernetes，不要在 Swarm 上硬撑。需要说明的是，Swarm 本身仍由 Docker 公司维护、没有停止更新，&quot;Swarm 已死&quot;的说法并不准确；但新功能与社区生态的重心确实在 Kubernetes 一边，选型时要把这点算进长期账。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;判断标准就一条：&lt;strong&gt;先看你的痛点是&quot;单机不够用&quot;还是&quot;需要平台级能力&quot;&lt;/strong&gt;，前者 Swarm 绰绰有余，后者一步到位上 Kubernetes，中间反复横跳才是最贵的。&lt;/p&gt;
&lt;h2&gt;排障：最常见的四类问题&lt;/h2&gt;
&lt;h3&gt;节点状态 Down 或 Disconnected&lt;/h3&gt;
&lt;p&gt;在 Manager 上 &lt;code&gt;docker node ls&lt;/code&gt; 看到某节点不是 &lt;code&gt;Ready&lt;/code&gt;：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;先查那台机器本身：Docker 服务是否在跑（&lt;code&gt;systemctl status docker&lt;/code&gt;）、机器是否宕机、磁盘是否写满（磁盘满会导致 Docker 异常）。&lt;/li&gt;
&lt;li&gt;查节点间连通性：Manager 与 Worker 之间要互通 &lt;strong&gt;2377/TCP&lt;/strong&gt;（集群管理）、&lt;strong&gt;7946/TCP+UDP&lt;/strong&gt;（节点间发现）、&lt;strong&gt;4789/UDP&lt;/strong&gt;（overlay 网络数据面），云服务器记得看安全组，很多人栽在这一步。&lt;/li&gt;
&lt;li&gt;临时失联的节点恢复网络后会自动归队；确认机器已报废的，用 &lt;code&gt;docker node rm -f &amp;lt;节点&amp;gt;&lt;/code&gt; 在 Manager 上强制清除，再决定是否补新机器。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;swarm join 失败&lt;/h3&gt;
&lt;p&gt;最常见三类报错与对策：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;现象&lt;/th&gt;
&lt;th&gt;常见原因&lt;/th&gt;
&lt;th&gt;处理&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;connection refused / timeout&lt;/td&gt;
&lt;td&gt;2377 端口被防火墙或安全组拦了&lt;/td&gt;
&lt;td&gt;放行 2377/TCP 后重试&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;token 相关的 unauthorized&lt;/td&gt;
&lt;td&gt;令牌抄错或已轮换&lt;/td&gt;
&lt;td&gt;在 Manager 上 &lt;code&gt;docker swarm join-token worker&lt;/code&gt; 重新取&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;node already part of a swarm&lt;/td&gt;
&lt;td&gt;这台机器以前加过别的集群&lt;/td&gt;
&lt;td&gt;先 &lt;code&gt;docker swarm leave&lt;/code&gt; 退出旧集群再加入&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;另外 &lt;code&gt;--advertise-addr&lt;/code&gt; 写错（写成了机器的另一张网卡地址）也会导致 join 时连不上 Manager init 时广播的地址，初始化时务必用其他节点真正能到达的那个 IP。&lt;/p&gt;
&lt;h3&gt;副本一直 Pending 或 Preparing 起不来&lt;/h3&gt;
&lt;p&gt;服务层面查起：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker service ps --no-trunc web
docker service inspect web
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;service ps&lt;/code&gt; 最后一列的错误信息最关键，逐个对：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Pending 且无错误信息&lt;/strong&gt;：没有节点满足调度条件——副本数超过可用节点、放置约束写错、或者节点都被 drain 了，&lt;code&gt;docker node ls&lt;/code&gt; 看 AVAILABILITY 列。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Preparing 反复重试&lt;/strong&gt;：多半在拉镜像，镜像名或标签写错、仓库要登录、私有仓库没在每台节点上 &lt;code&gt;docker login&lt;/code&gt;（Swarm 部署需要加 &lt;code&gt;--with-registry-auth&lt;/code&gt; 把登录凭证分发给各节点）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Rejected&lt;/strong&gt;：节点资源不足或端口冲突，看错误信息里的具体描述。&lt;/li&gt;
&lt;li&gt;进一步深挖单个任务：&lt;code&gt;docker service ps&lt;/code&gt; 找到任务所在节点，去那台机器上 &lt;code&gt;docker logs&lt;/code&gt; 看对应容器的日志，排障方法与单机完全一致。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;服务发布了端口却访问不通&lt;/h3&gt;
&lt;p&gt;先确认路由网格工作正常：&lt;code&gt;docker service ls&lt;/code&gt; 看 PORTS 列是否真的发布了；再查云安全组和系统防火墙是否放行了发布端口到&lt;strong&gt;所有节点&lt;/strong&gt;（路由网格是任意节点都能进，所以每台都要放行）；最后检查 overlay 数据面端口 4789/UDP 是否被拦，它不通时跨节点的转发会直接失效。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇我们跨过了单机到集群的门槛：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Swarm 是 Docker 内置编排器，不用另装，先想清楚&quot;可用性&quot;和&quot;横向扩容&quot;两个单机天花板再上；&lt;/li&gt;
&lt;li&gt;核心概念就一组：你声明&lt;strong&gt;服务&lt;/strong&gt;的期望状态，Swarm 用&lt;strong&gt;任务&lt;/strong&gt;副本去逼近它，副本死了自动补，这就是自愈；&lt;/li&gt;
&lt;li&gt;经理节点用 &lt;strong&gt;Raft 多数派&lt;/strong&gt;，数量只取奇数，3 台是小集群甜点，2 台是最差配置；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;docker stack deploy&lt;/code&gt; 复用 Compose 文件，但 &lt;code&gt;build:&lt;/code&gt; 会被忽略、镜像必须先推仓库，&lt;code&gt;deploy&lt;/code&gt; 段在集群里才真正生效；&lt;/li&gt;
&lt;li&gt;滚动更新靠 &lt;code&gt;--update-parallelism&lt;/code&gt; 与 &lt;code&gt;--update-delay&lt;/code&gt; 控制节奏，出事一条 &lt;code&gt;rollback&lt;/code&gt; 回退；&lt;/li&gt;
&lt;li&gt;有状态服务是 Swarm 的短板，数据库留在集群外、或用放置约束钉住节点，别让卷漂移；&lt;/li&gt;
&lt;li&gt;密码走 secrets、配置走 configs，别再进环境变量；&lt;/li&gt;
&lt;li&gt;选型记住一句话：单机痛点用 Swarm，平台级需求上 Kubernetes。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;至此，从单机部署、自动更新、监控、安全，一路走到多机集群，这套 Docker 系列的骨架就完整了。&lt;/p&gt;
</content:encoded></item><item><title>从 Docker 到 Kubernetes：概念对照</title><link>https://www.anexns.cloudns.org/posts/docker-to-kubernetes/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-to-kubernetes/</guid><description>已经会 Docker 和 Compose，下一步看 Kubernetes 就不再发怵：用你熟悉的概念逐个对照 Pod、Deployment、Service、Ingress 与存储，再讲清什么时候真的需要它、什么时候纯属自找麻烦。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说结论：你缺的不是技术，是翻译&lt;/h2&gt;
&lt;p&gt;学 Docker 的人第一次打开 Kubernetes（以下简称 K8s）文档，普遍会有一种被背叛的感觉：镜像还是那个镜像，容器还是那个容器，可满屏的 Pod、Deployment、Service、Ingress、ConfigMap 全是生词，YAML 一写就是上百行，跑个最简单的应用比写业务代码还累。很多人卡在这里，不是因为 K8s 本身有多难，而是因为没人把新概念翻译回他们已经懂的语言。&lt;/p&gt;
&lt;p&gt;这篇文章就是来做这件翻译工作的。主线很简单：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;先泼一盆冷水，讲清 K8s 的真实定位和成本，帮你判断自己到底需不需要它；&lt;/li&gt;
&lt;li&gt;用一张核心概念对照大表，把 K8s 的每个核心对象映射回 Docker 和 Compose 里的对应物；&lt;/li&gt;
&lt;li&gt;拿一个完整的 Compose 例子，逐段翻译成 K8s 的 YAML，让你亲眼看到「同一件事的两种写法」；&lt;/li&gt;
&lt;li&gt;给一份 kubectl 生存命令对照表、一条本地体验路线和一张选型判断表。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;读完你不一定会立刻去搭集群，但至少再看 K8s 的文章和文档时，每个名词你都能在脑子里对上号。至于 Compose 本身的进阶用法（环境变量、健康检查、多环境），可以先看本系列的 &lt;a href=&quot;/posts/docker-compose-advanced/&quot;&gt;Docker Compose 进阶&lt;/a&gt;，那是理解这篇的全部前置知识。&lt;/p&gt;
&lt;h2&gt;一、心态先行：K8s 不是更高级的 Docker&lt;/h2&gt;
&lt;p&gt;最常见的误解，是把 K8s 理解成「Docker 的高级版」或者「更强的 Compose」。这个定位从一开始就错了：&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;K8s 不是更高级的 Docker，而是一套集群操作系统。&amp;lt;/span&amp;gt;Docker 解决的是「在一台机器上怎么把应用装进容器跑起来」，K8s 解决的是「在几十上百台机器组成的集群里，怎么调度、编排、自愈、扩缩这些容器」。两者的抽象层级完全不同：Docker 面对的是一台机器，K8s 面对的是一个机房。&lt;/p&gt;
&lt;p&gt;这个区别决定了 K8s 的一切「繁琐」都有出处：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;你只有一台机器时，「容器挂了重启一下」是一句 &lt;code&gt;restart: unless-stopped&lt;/code&gt;；在集群里，机器本身都可能整台宕机，应用必须能自动漂移到别的机器上，这就需要调度器、控制器、健康探针一整套机制；&lt;/li&gt;
&lt;li&gt;你只有一台机器时，服务发现就是「容器名当主机名」；在集群里，容器的 IP 天天变，必须有一层稳定的访问入口，这就是 Service 存在的理由；&lt;/li&gt;
&lt;li&gt;你只有一台机器时，配置就是 &lt;code&gt;.env&lt;/code&gt; 文件；在集群里，配置要能统一下发、滚动更新、区分敏感与非敏感，于是有了 ConfigMap 和 Secret。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;所以先把成本算清楚。单机个人项目上 K8s，成本清单大概是这样的：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;成本项&lt;/th&gt;
&lt;th&gt;单机 Docker/Compose&lt;/th&gt;
&lt;th&gt;单机硬上 K8s&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;部署一个应用的配置量&lt;/td&gt;
&lt;td&gt;一个 compose 文件，几十行&lt;/td&gt;
&lt;td&gt;Deployment、Service、Ingress 等多个 YAML，上百行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;集群本身的资源占用&lt;/td&gt;
&lt;td&gt;无额外开销&lt;/td&gt;
&lt;td&gt;控制平面组件常驻，先吃掉一部分 CPU 和内存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;出问题时的排查链路&lt;/td&gt;
&lt;td&gt;看容器日志基本够了&lt;/td&gt;
&lt;td&gt;要分清是 Pod、节点、网络插件还是存储的问题&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;升级维护&lt;/td&gt;
&lt;td&gt;换镜像、重建容器&lt;/td&gt;
&lt;td&gt;还要管 K8s 自身的版本升级与组件兼容&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;学习曲线&lt;/td&gt;
&lt;td&gt;一两天上手&lt;/td&gt;
&lt;td&gt;概念体系庞大，摸到门道要以周计&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
个人单机、两三台小服务器的场景，硬上 K8s 属于典型的&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;用运维复杂度换根本用不上的能力&amp;lt;/span&amp;gt;：你为高可用、自愈、弹性扩缩付出了全部学习与维护成本，而你的流量和规模根本触发不了这些能力。先把 Compose 用透，收益高得多。
:::&lt;/p&gt;
&lt;p&gt;泼冷水不是劝退。K8s 是当下云原生生态的事实标准，托管服务、CI/CD、监控、服务网格全都围着它转，理解它的概念对任何做后端和运维的人都只有好处。但「理解它」和「在自己的小服务器上养一套它」是两回事。这篇的态度就是：先用对照法把概念学明白，什么时候真该上，后文有明确的判断表。&lt;/p&gt;
&lt;h2&gt;二、核心概念对照大表&lt;/h2&gt;
&lt;p&gt;先上全篇最重要的一张表。建议先通读一遍有个整体印象，后面每一节都会展开其中几行。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;你已经会的东西&lt;/th&gt;
&lt;th&gt;K8s 里的对应物&lt;/th&gt;
&lt;th&gt;关键区别说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;镜像 Image&lt;/td&gt;
&lt;td&gt;Image（完全同名同物）&lt;/td&gt;
&lt;td&gt;没有任何区别，K8s 用的就是 Docker 镜像格式，从同样的仓库拉取&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;容器 Container&lt;/td&gt;
&lt;td&gt;Pod 里的一个容器&lt;/td&gt;
&lt;td&gt;容器在 K8s 里不是最小单位，它被装进 Pod 里运行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker run&lt;/code&gt; 起一个容器&lt;/td&gt;
&lt;td&gt;Pod&lt;/td&gt;
&lt;td&gt;Pod 是最小调度单位，可以装一个或多个容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Compose 的一个 service&lt;/td&gt;
&lt;td&gt;Deployment ＋ Service&lt;/td&gt;
&lt;td&gt;Deployment 管「跑几个副本、怎么更新」，Service 管「怎么被访问」，一个职责拆成两个对象&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;docker-compose.yml&lt;/td&gt;
&lt;td&gt;一堆 YAML 文件（或一个文件多段）&lt;/td&gt;
&lt;td&gt;每个对象一段 YAML，用 &lt;code&gt;---&lt;/code&gt; 分隔，靠 &lt;code&gt;kubectl apply&lt;/code&gt; 一起提交&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据卷 Volume&lt;/td&gt;
&lt;td&gt;PV（持久卷）＋ PVC（持久卷声明）&lt;/td&gt;
&lt;td&gt;多了一层抽象：PVC 是「我要一块 10Gi 的盘」的申请，PV 是集群实际供给的那块盘&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Docker 自定义网络＋容器名互访&lt;/td&gt;
&lt;td&gt;Service ＋ 集群 DNS&lt;/td&gt;
&lt;td&gt;容器名换成 Service 名，跨命名空间还能带后缀，原理还是 DNS 解析&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Nginx 反向代理&lt;/td&gt;
&lt;td&gt;Ingress ＋ Ingress Controller&lt;/td&gt;
&lt;td&gt;Ingress 只是规则声明，真正干活的 Controller（如 ingress-nginx）要自己装&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.env&lt;/code&gt; 环境变量&lt;/td&gt;
&lt;td&gt;ConfigMap&lt;/td&gt;
&lt;td&gt;存非敏感配置，键值对形式，可挂成环境变量或文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;写在 compose 里的密码&lt;/td&gt;
&lt;td&gt;Secret&lt;/td&gt;
&lt;td&gt;存敏感配置，Base64 编码存储（注意：只是编码，不是加密）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;restart: unless-stopped&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;控制器自愈（Deployment 托管 Pod）&lt;/td&gt;
&lt;td&gt;不是容器自己重启，而是控制器发现副本数不对，重新拉起新 Pod&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose up -d&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl apply -f xxx.yaml&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;都是声明「我要什么」，让系统去达成&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker ps&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl get pods&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;看的不是容器列表，而是 Pod 列表&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;逐行说几个容易卡住的点。&lt;/p&gt;
&lt;p&gt;**镜像是唯一零成本迁移的东西。**你在 Dockerfile 里构建的镜像、在私有仓库里存的镜像，到了 K8s 里原样使用，一个字都不用改。这是整个迁移里最让人安心的一点：你的构建资产全部保值。&lt;/p&gt;
&lt;p&gt;**Compose 的一个 service，在 K8s 里被拆成了两个对象。**这是初学者最困惑的地方。Compose 里写一个 service，运行和访问两件事都齐了；K8s 把它拆开：Deployment 只负责「这个应用跑几个副本、镜像是哪个版本、挂了怎么补」，Service 只负责「给这组副本一个稳定的访问地址」。拆开的原因是职责确实不同：一组 Pod 可以被多个 Service 暴露（对内一个、对外一个），一个应用也可以只跑不被访问（后台任务）。理解了这个拆分，K8s 一半的对象就通了。&lt;/p&gt;
&lt;p&gt;**存储多了一层「申请与供给」。**Docker 里写个 volumes 映射，盘就是你的。K8s 里应用只能提需求（PVC：我要 10Gi、可读写），至于这块盘最终是云盘、NFS 还是本地目录，由集群的 PV 供给机制决定。应用不关心盘从哪来，这正是集群抽象的意义：换个集群，YAML 一行不用改。&lt;/p&gt;
&lt;p&gt;**Ingress 本身不干活。**这点和很多人想的不一样：Ingress 只是一份「域名＋路径 → 转发给哪个 Service」的规则声明，集群里必须额外装一个 Ingress Controller（最常见的是 ingress-nginx）来读规则并真正做反向代理。类比一下：Ingress 相当于你写好的 Nginx 配置文件，Controller 相当于 Nginx 进程本身，光有配置文件，没有进程读它，什么都不会发生。&lt;/p&gt;
&lt;p&gt;:::warning
Secret 只是 Base64 编码，不是加密。任何能读到 Secret 的人都能一条命令解出明文。把 Secret 当保险箱、把含 Secret 的 YAML 随手提交到公开仓库，属于&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把密码明文发到全世界&amp;lt;/span&amp;gt;。生产环境要配合 RBAC 权限控制，有条件再上外部密钥管理或静态加密。
:::&lt;/p&gt;
&lt;h2&gt;三、Pod 为什么要多一层&lt;/h2&gt;
&lt;p&gt;对照表里最核心的新概念就是 Pod。它是 K8s 的最小调度单位，理解了它为什么存在，其余概念都是顺水推舟。&lt;/p&gt;
&lt;p&gt;在 Docker 的世界里，容器就是最小单位，你想跑什么就 &lt;code&gt;docker run&lt;/code&gt; 什么。K8s 在容器外面包了一层 Pod，主要为了解决两个问题：&lt;/p&gt;
&lt;p&gt;**第一，同 Pod 内容器共享网络。**同一个 Pod 里的所有容器共用一个网络命名空间，也就是共享同一个 IP 地址和端口空间，彼此之间用 &lt;code&gt;localhost&lt;/code&gt; 就能互访。这意味着一组必须「贴身协作」的容器可以当成一个整体调度：它们永远落在同一台机器上，生一起生、死一起死，不会出现主容器在这台机器、辅助容器在另一台机器的尴尬。&lt;/p&gt;
&lt;p&gt;**第二，同 Pod 内容器共享存储。**Pod 可以定义卷，挂给 Pod 内的多个容器共同读写，适合主进程写日志、辅助进程收集日志这类配合。&lt;/p&gt;
&lt;p&gt;最常见的多容器模式叫 sidecar（边车）：主容器跑业务，旁边挂一个辅助容器干杂活，比如收集日志、做代理转发、同步配置。像服务网格里的流量代理，就是以 sidecar 形式注入到每个业务 Pod 里的。&lt;/p&gt;
&lt;p&gt;当然，绝大多数情况下一个 Pod 里就一个容器。单容器 Pod 你完全可以近似理解成「K8s 版的容器」，只是外面多了一层壳，多了标签、注解、探针这些集群管理需要的元数据。下面看一个最简单的 Pod 长什么样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apiVersion: v1
kind: Pod
metadata:
  name: my-nginx
  labels:
    app: nginx
spec:
  containers:
    - name: nginx
      image: nginx:1.27
      ports:
        - containerPort: 80
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;对照着 Docker 看：&lt;code&gt;image&lt;/code&gt; 还是那个镜像，&lt;code&gt;containerPort&lt;/code&gt; 就是你熟悉的容器端口，&lt;code&gt;containers&lt;/code&gt; 是个列表——这就是为多容器留的位置。实际工作中你很少直接写裸 Pod，因为裸 Pod 挂了没人管，真正用的是下一节的 Deployment。&lt;/p&gt;
&lt;h2&gt;四、声明式思维：从「过程」到「期望状态」&lt;/h2&gt;
&lt;p&gt;如果说 Pod 是概念上最核心的新东西，那声明式就是思想上最核心的新东西。&lt;/p&gt;
&lt;p&gt;Compose 其实已经是半声明式了：你写「我要跑这三个服务」，&lt;code&gt;docker compose up&lt;/code&gt; 负责把现状调整成文件里写的样子。但 Compose 的自愈能力到容器级为止：容器挂了靠 restart 策略原地重启，机器挂了，上面的一切都没了。&lt;/p&gt;
&lt;p&gt;K8s 是彻底的声明式。你提交 YAML，描述的是&lt;strong&gt;期望状态&lt;/strong&gt;：我要这个应用跑 3 个副本，用这个镜像，对外暴露这个端口。集群里的控制器会持续地对比「期望状态」和「实际状态」，发现不一致就动手修正，永远向期望靠拢。你不需要写任何「如果挂了就重启」的逻辑，因为&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;自愈不是某个功能，而是声明式的自然结果&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;这个差别，光说不如动手看一遍。下面这条演示命令链，建议你在本地体验环节亲手跑一次，冲击力比看十篇文章都强：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 部署一个 3 副本的应用
kubectl create deployment demo --image=nginx:1.27 --replicas=3

# 查看 Pod，可以看到 3 个副本都在运行
kubectl get pods

# 手动删掉其中一个 Pod（模拟它突然崩溃）
kubectl delete pod &amp;lt;上面任意一个Pod的名字&amp;gt;

# 立刻再看：一个新的 Pod 已经被自动创建出来补位
kubectl get pods

# 查看副本数，始终维持在 3
kubectl get deployment demo
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;你删掉的那个 Pod 没有「重启」，而是 Deployment 控制器发现「期望 3 个、实际 2 个」，立刻新建了一个补上。注意新 Pod 的名字和 IP 都变了——在 K8s 的世界里，Pod 是随时可替换的消耗品，身份不重要，数量和状态才重要。也正因为 Pod 朝生暮死，才必须有 Service 这一层稳定入口兜底，否则调用方根本追不上天天变的 Pod IP。&lt;/p&gt;
&lt;p&gt;理解了这一点，很多 K8s 的设计就都顺理成章了：滚动更新是「逐步把旧 Pod 换成新 Pod 并维持期望副本数」，扩缩容是「改一个数字，控制器去增删 Pod」，节点宕机恢复是「控制器发现一整台机器的 Pod 没了，在别的机器上重建」。全是同一套机制的不同表现。&lt;/p&gt;
&lt;h2&gt;五、完整对照实战：把一个 Compose 例子翻译成 K8s&lt;/h2&gt;
&lt;p&gt;下面进入全篇的重头戏。先看一个你已经很熟悉的 Compose 例子：一个后端应用加一个 Nginx 前置，Nginx 把流量反代给后端。&lt;/p&gt;
&lt;p&gt;Compose 版本（&lt;code&gt;docker-compose.yml&lt;/code&gt;）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  web:
    image: nginx:1.27
    ports:
      - &quot;8080:80&quot;
    depends_on:
      - app
  app:
    image: myapp:1.0
    environment:
      - APP_ENV=prod
    deploy:
      replicas: 2
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;翻译成 K8s，需要三个对象：app 的 Deployment、app 的 Service、web（Nginx）的 Deployment 加对外 Service。逐段来。&lt;/p&gt;
&lt;p&gt;第一段，app 的 Deployment，对应 Compose 里 &lt;code&gt;app&lt;/code&gt; 的「跑什么、跑几个」：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: app
          image: myapp:1.0
          ports:
            - containerPort: 8080
          env:
            - name: APP_ENV
              value: &quot;prod&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;对照着看：&lt;code&gt;replicas: 2&lt;/code&gt; 就是 Compose 里的副本数；&lt;code&gt;template&lt;/code&gt; 里描述的就是 Pod 本人，&lt;code&gt;image&lt;/code&gt;、&lt;code&gt;containerPort&lt;/code&gt;、&lt;code&gt;env&lt;/code&gt; 全部是你认识的东西，只是组织方式变了。&lt;code&gt;selector.matchLabels&lt;/code&gt; 和 &lt;code&gt;template.metadata.labels&lt;/code&gt; 这对标签是 Deployment 认领 Pod 的凭据，两边必须一致，这是新手最常写错的地方之一，记住「控制器靠标签找自己的孩子」就行。&lt;/p&gt;
&lt;p&gt;第二段，app 的 Service，对应 Compose 里「别的服务用名字 &lt;code&gt;app&lt;/code&gt; 就能访问它」这件事：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apiVersion: v1
kind: Service
metadata:
  name: app
spec:
  selector:
    app: myapp
  ports:
    - port: 80
      targetPort: 8080
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Service 靠 &lt;code&gt;selector&lt;/code&gt; 标签选中 app 的那组 Pod，给它们一个稳定的虚拟 IP 和 DNS 名。集群内任何地方访问 &lt;code&gt;http://app&lt;/code&gt; 都会被转到某个 app Pod 的 8080 端口——和 Compose 里用服务名互访是一模一样的体验，只是实现从 Docker 内置 DNS 换成了集群 DNS ＋ Service 转发。&lt;/p&gt;
&lt;p&gt;第三段，Nginx 前置。Compose 里 Nginx 既是应用又负责对外发布端口，K8s 里照样拆成 Deployment ＋ Service 两件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 1
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  type: LoadBalancer
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 80
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里的 Service 用了 &lt;code&gt;type: LoadBalancer&lt;/code&gt;，对应 Compose 里的 &lt;code&gt;ports: &quot;8080:80&quot;&lt;/code&gt; 对外发布：在云厂商的托管 K8s 上，它会自动给你配一个云负载均衡器和公网 IP；在本地 kind/minikube 里这个类型拿不到真正的外部 IP，后文体验环节会说明替代办法。另外，Nginx 反代后端的配置里，upstream 写 &lt;code&gt;http://app&lt;/code&gt; 即可，和 Compose 里写服务名的习惯无缝衔接。&lt;/p&gt;
&lt;p&gt;三段 YAML 放进一个文件（段与段之间用 &lt;code&gt;---&lt;/code&gt; 分隔），一条命令提交：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;kubectl apply -f app.yaml
kubectl get pods,svc
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把两边并排总结一下，翻译关系就彻底清楚了：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Compose 里的写法&lt;/th&gt;
&lt;th&gt;K8s 里的对应写法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;services.app.image&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Deployment 的 &lt;code&gt;template.spec.containers[].image&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;deploy.replicas&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Deployment 的 &lt;code&gt;spec.replicas&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;environment&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器 &lt;code&gt;env&lt;/code&gt; 字段，或抽到 ConfigMap/Secret 引用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ports: &quot;8080:80&quot;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Service 的 &lt;code&gt;port/targetPort&lt;/code&gt;，对外则选 LoadBalancer 或 Ingress&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;服务名互访（&lt;code&gt;http://app&lt;/code&gt;）&lt;/td&gt;
&lt;td&gt;Service 名互访（&lt;code&gt;http://app&lt;/code&gt;），机制换成集群 DNS&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;depends_on&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;无直接对应，靠应用自己重试或初始化容器解决&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose up -d&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl apply -f&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;最后一行值得多说一句：&lt;code&gt;depends_on&lt;/code&gt; 在 K8s 里没有对应物，这不是功能缺失，而是设计哲学不同——集群环境里依赖的服务随时可能重启漂移，应用必须自己具备「连不上就重试」的能力，而不是指望编排工具保证启动顺序。往 K8s 迁移时，这是应用代码层面最常见的改造点。&lt;/p&gt;
&lt;h2&gt;六、kubectl 生存命令对照表&lt;/h2&gt;
&lt;p&gt;操作层面，kubectl 就是 K8s 的 docker 命令行。下面这张表覆盖日常九成的动作，左边是你已经会的，右边是对应写法：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;你想干什么&lt;/th&gt;
&lt;th&gt;Docker/Compose&lt;/th&gt;
&lt;th&gt;Kubernetes&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;看运行中的实例&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker ps&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl get pods&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;看所有资源概览&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker compose ps&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl get all&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;部署/更新&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker compose up -d&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl apply -f app.yaml&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;看详细信息&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker inspect &amp;lt;容器&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl describe pod &amp;lt;名字&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;看日志&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker logs -f &amp;lt;容器&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl logs -f &amp;lt;Pod&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;进容器执行命令&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker exec -it &amp;lt;容器&amp;gt; sh&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl exec -it &amp;lt;Pod&amp;gt; -- sh&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;扩缩容&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker compose up -d --scale app=3&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl scale deployment app --replicas=3&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;更新镜像版本&lt;/td&gt;
&lt;td&gt;改 compose 文件后 &lt;code&gt;up -d&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl set image deployment/app app=myapp:2.0&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;看滚动更新状态&lt;/td&gt;
&lt;td&gt;无（直接替换）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl rollout status deployment/app&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;回滚版本&lt;/td&gt;
&lt;td&gt;改回旧镜像再 &lt;code&gt;up -d&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl rollout undo deployment/app&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;删掉一个实例&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker rm -f &amp;lt;容器&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl delete pod &amp;lt;名字&amp;gt;&lt;/code&gt;（托管 Pod 会自动补新）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;删除整套应用&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker compose down&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl delete -f app.yaml&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;看资源占用&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker stats&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl top pods&lt;/code&gt;（需装 metrics-server）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;把本地端口转发到服务&lt;/td&gt;
&lt;td&gt;靠 ports 发布&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl port-forward svc/web 8080:80&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;看配置文件原文&lt;/td&gt;
&lt;td&gt;&lt;code&gt;cat docker-compose.yml&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kubectl get deployment app -o yaml&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;有三个差异点要特别适应一下：&lt;/p&gt;
&lt;p&gt;第一，kubectl 的一切操作都围绕「资源对象」而不是「容器」。你 describe 的是 Pod、Deployment、Service，日志、执行命令也是先定位到 Pod。刚开始会觉得隔了一层，用久了会发现按对象思考正是集群管理的方式。&lt;/p&gt;
&lt;p&gt;第二，&lt;code&gt;kubectl delete pod&lt;/code&gt; 对新手是个陷阱：删掉 Deployment 托管的 Pod，它立刻补一个新的出来，看起来像「删不掉」。这恰恰是自愈在工作。要真正停掉应用，删的是 Deployment 或者把副本数调到 0。反过来，这也意味着&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;在生产集群里随手 delete pod 是危险动作&amp;lt;/span&amp;gt;，你以为在清理，它以为在故障恢复，流量可能被打到刚启动还没就绪的新 Pod 上。&lt;/p&gt;
&lt;p&gt;第三，&lt;code&gt;kubectl port-forward&lt;/code&gt; 是本地调试的神器：它能把集群里任意 Service 或 Pod 的端口转发到你本机，效果类似临时做了一条 SSH 隧道，不用为了调试就把服务暴露到公网。&lt;/p&gt;
&lt;h2&gt;七、本地体验路线：先在自己电脑上玩起来&lt;/h2&gt;
&lt;p&gt;理解 K8s 的正确姿势是先在本地起一个玩具集群，把第五节的 YAML 真跑一遍。本地工具有两个主流选择，二选一即可：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;工具&lt;/th&gt;
&lt;th&gt;特点&lt;/th&gt;
&lt;th&gt;适合&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;kind&lt;/td&gt;
&lt;td&gt;把集群节点跑在 Docker 容器里，轻量、起停快、贴合 CI 场景&lt;/td&gt;
&lt;td&gt;已经装好 Docker、想快速反复重建的人&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;minikube&lt;/td&gt;
&lt;td&gt;功能全，支持多种驱动，自带仪表盘和插件生态&lt;/td&gt;
&lt;td&gt;想顺带体验插件、Ingress 等完整功能的人&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;本系列读者都装了 Docker，所以推荐 kind。完整体验流程如下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 安装 kind（Linux 示例，其他系统去 kind 官网看对应方式）
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.24.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

# 2. 创建一个单节点集群（节点本身就是个 Docker 容器）
kind create cluster --name learn

# 3. 确认 kubectl 能连上
kubectl cluster-info
kubectl get nodes

# 4. 跑一遍第四节的自愈演示
kubectl create deployment demo --image=nginx:1.27 --replicas=3
kubectl get pods -w

# 5. 把第五节的 app.yaml 存好并部署
kubectl apply -f app.yaml
kubectl get pods,svc

# 6. web 的 Service 是 LoadBalancer 类型，本地没有云厂商给它分配外部 IP
#    改用端口转发在本机访问验证
kubectl port-forward svc/web 8080:80
# 浏览器打开 http://localhost:8080 即可

# 7. 玩完销毁集群，不留任何残留
kind delete cluster --name learn
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;跑这一圈时重点观察三件事：一是删 Pod 自动补位的全过程，二是 &lt;code&gt;kubectl describe&lt;/code&gt; 一个 Pod 时里面记录的事件（调度到哪个节点、镜像拉取进度、探针结果都在里面，这是 K8s 最主要的排障入口），三是 Service 的 DNS 名在容器内真实可用——可以 &lt;code&gt;kubectl exec&lt;/code&gt; 进任意 Pod 用 &lt;code&gt;curl http://app&lt;/code&gt; 验证。&lt;/p&gt;
&lt;p&gt;如果本地机器配置紧张，也完全可以直接用云厂商的托管 K8s 试用集群练手，概念完全一致，只是别忘了练完释放资源。&lt;/p&gt;
&lt;h2&gt;八、选型判断：什么时候该上，什么时候别上&lt;/h2&gt;
&lt;p&gt;学归学，真到给自己的项目做选型时，用下面这张表对照着判断：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;判断维度&lt;/th&gt;
&lt;th&gt;Compose 就够了&lt;/th&gt;
&lt;th&gt;该考虑 Swarm&lt;/th&gt;
&lt;th&gt;该考虑 K8s&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;机器数量&lt;/td&gt;
&lt;td&gt;1 台&lt;/td&gt;
&lt;td&gt;2–5 台&lt;/td&gt;
&lt;td&gt;5 台以上，或弹性伸缩的云环境&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;应用数量&lt;/td&gt;
&lt;td&gt;十几个服务以内&lt;/td&gt;
&lt;td&gt;十几个到几十个&lt;/td&gt;
&lt;td&gt;几十上百个服务、多团队共用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;高可用要求&lt;/td&gt;
&lt;td&gt;单机挂了人工恢复可接受&lt;/td&gt;
&lt;td&gt;希望单机故障自动漂移&lt;/td&gt;
&lt;td&gt;要求节点级、可用区级容灾&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;发布频率&lt;/td&gt;
&lt;td&gt;一天几次以内&lt;/td&gt;
&lt;td&gt;每天多次&lt;/td&gt;
&lt;td&gt;多团队高频发布、需要灰度/金丝雀&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;运维人力&lt;/td&gt;
&lt;td&gt;个人或兼职&lt;/td&gt;
&lt;td&gt;一两个人&lt;/td&gt;
&lt;td&gt;有专职平台/运维团队，或买托管版&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;生态需求&lt;/td&gt;
&lt;td&gt;基本没有&lt;/td&gt;
&lt;td&gt;基本没有&lt;/td&gt;
&lt;td&gt;需要服务网格、精细监控、云厂商深度集成&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;三条经验线可以直接套用：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;个人项目、自用服务、一台小服务器&lt;/strong&gt;：Compose 就是最优解，别犹豫。这也是本系列前十几篇一直在深耕 Compose 的原因——它覆盖了绝大多数个人和小团队场景。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;有三五台机器、想要基本的故障漂移和滚动更新，但没人愿意养 K8s&lt;/strong&gt;：可以看看 &lt;a href=&quot;/posts/docker-swarm/&quot;&gt;Docker Swarm&lt;/a&gt;，它和 Compose 共用一套心智模型，学习成本几乎为零，代价是生态和上限都有限。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;团队规模、多台机器、发布频繁、且有人能专职维护（或者愿意为托管版付费）&lt;/strong&gt;：K8s 的投入开始回本。特别是用云厂商托管 K8s 时，控制平面不用你管，成本会降一大截，这是现在大多数团队上 K8s 的实际姿势。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
最忌讳的选型理由是「简历上好看」和「别人都在用」。K8s 的复杂度是真金白银的日常成本：每一次排障、每一次升级、每一个新同事入职都要为它付费。规模没到、团队没到，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;上了 K8s 等于给自己请了个全职麻烦&amp;lt;/span&amp;gt;。反过来，规模真的到了还硬扛 Compose，人工运维的成本同样会反噬。选型没有高下，只有匹配与否。
:::&lt;/p&gt;
&lt;h2&gt;九、排障小节：新手最常撞的几个坑&lt;/h2&gt;
&lt;p&gt;**Pod 一直是 Pending 状态。**意思是调度器找不到能放它的节点。先 &lt;code&gt;kubectl describe pod &amp;lt;名字&amp;gt;&lt;/code&gt; 看 Events，常见原因是集群资源不够（本地 kind 只有一个节点，副本开太多、资源请求写太大就会这样），或者 PVC 没有可用的 PV 供给，Pod 在等存储。&lt;/p&gt;
&lt;p&gt;**Pod 反复重启，状态是 CrashLoopBackOff。**Pod 起来了但进程立刻退出，K8s 按退避策略反复拉起。用 &lt;code&gt;kubectl logs &amp;lt;Pod&amp;gt;&lt;/code&gt; 看当前日志、&lt;code&gt;kubectl logs &amp;lt;Pod&amp;gt; --previous&lt;/code&gt; 看上一次崩溃的日志，九成是应用本身的问题：配置错、依赖连不上、启动命令写错。记住这不是 K8s 的故障，是你的应用在集群里把在 Docker 里也会犯的错又犯了一遍，只是换了个状态名。&lt;/p&gt;
&lt;p&gt;**ImagePullBackOff 拉不到镜像。**同样先看 describe 的 Events。常见原因：镜像名或标签写错、私有仓库没配拉取凭证（imagePullSecrets）、本地 kind 集群里用了只存在于你本机 Docker 的镜像——kind 需要用 &lt;code&gt;kind load docker-image &amp;lt;镜像&amp;gt; --name learn&lt;/code&gt; 把本地镜像灌进集群节点，这是本地体验时最容易卡住的一步。&lt;/p&gt;
&lt;p&gt;**Service 访问不通。**按链路逐段查：&lt;code&gt;kubectl get svc&lt;/code&gt; 确认 Service 存在，&lt;code&gt;kubectl get endpoints &amp;lt;Service名&amp;gt;&lt;/code&gt; 确认它背后挂上了 Pod（为空说明 selector 标签和 Pod 标签对不上，这是最常见的原因），再确认 Service 的 &lt;code&gt;targetPort&lt;/code&gt; 和容器实际监听端口一致。整条链路就是「DNS 名 → Service → 标签选 Pod → 端口转发」，断在哪段查哪段。&lt;/p&gt;
&lt;p&gt;**apply 了 YAML 却没生效。**先确认改的是同一个对象（名字、命名空间是否一致，&lt;code&gt;kubectl&lt;/code&gt; 默认操作 default 命名空间，跨命名空间要用 &lt;code&gt;-n&lt;/code&gt; 指定），再用 &lt;code&gt;kubectl get &amp;lt;资源&amp;gt; -o yaml&lt;/code&gt; 把集群里的实际状态拉出来和文件逐字段对。声明式的好处是状态可查，别靠猜。&lt;/p&gt;
&lt;h2&gt;十、学习路线图&lt;/h2&gt;
&lt;p&gt;最后给一条不折腾的进阶路线，按顺序走，每一步都能在前一步的基础上小步验证：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;概念期&lt;/strong&gt;：吃透这篇的对照表，特别是 Pod、Deployment、Service、Ingress、ConfigMap/Secret 这六个对象的职责边界。能对着一张架构图说清每个对象干什么，这一期就毕业了。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;本地期&lt;/strong&gt;：用 kind 把第七节的流程完整跑两遍，第二遍试着自己改副本数、换镜像版本、删 Pod 看自愈、给应用加上 ConfigMap 管理配置。把第六节的 kubectl 命令都亲手敲过一遍。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;托管期&lt;/strong&gt;：在任意云厂商开一个最小规格的托管 K8s，把一个自己真实的小项目迁上去，完整经历域名解析、Ingress 配 HTTPS、镜像仓库凭证这些「玩具集群里没有的真实问题」。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;进阶期&lt;/strong&gt;：再往后才是 Helm（包管理）、探针与资源配额调优、监控告警体系、灰度发布这些话题。每一个都是大题目，按需学，不要提前囤。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::warning
千万别一上来就啃 K8s 源码或者试图自建生产集群。控制平面的组件（API Server、etcd、Scheduler、Controller Manager）各自都是一门学问，在没跑过托管版之前自建集群，学到的主要是踩坑而不是概念。先当好使用者，再决定要不要当建设者。
:::&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;K8s 不是更高级的 Docker，而是面向集群的操作系统；它的全部复杂度，都是为「多机调度、自愈、弹性」付的账，规模没到就不要替它买单。&lt;/li&gt;
&lt;li&gt;翻译关系记住三条主线：Pod 是容器的壳，Compose 的一个 service 拆成 Deployment（管运行）＋ Service（管访问），存储多了一层 PVC 申请、PV 供给。&lt;/li&gt;
&lt;li&gt;声明式是 K8s 的灵魂：你只描述期望状态，控制器负责无限逼近它，自愈、滚动更新、扩缩容都是同一机制的表现。&lt;/li&gt;
&lt;li&gt;kubectl 的操作对象是资源而不是容器，&lt;code&gt;describe&lt;/code&gt; 看事件、&lt;code&gt;logs&lt;/code&gt; 看日志、&lt;code&gt;apply&lt;/code&gt; 提交期望，是日常排障的铁三角。&lt;/li&gt;
&lt;li&gt;选型只看匹配度：单机个人项目用 Compose，三五台机器求轻量集群看 &lt;a href=&quot;/posts/docker-swarm/&quot;&gt;Swarm&lt;/a&gt;，规模与团队都到位再上 K8s，且优先托管版。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;把这篇的对照表存好，下次再看到任何 K8s 名词，先回表里查它对应你熟悉的哪个东西——发怵的感觉，基本就消了。&lt;/p&gt;
</content:encoded></item><item><title>镜像安全扫描：用 Trivy 给镜像查漏洞</title><link>https://www.anexns.cloudns.org/posts/docker-trivy-scan/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-trivy-scan/</guid><description>上线前先给镜像做体检：用 Trivy 扫描镜像漏洞与配置问题，读懂严重等级与可修复性、过滤噪音、只拦高危的门禁策略，以及把扫描接进自动更新与 CI 流程的方法。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;上一篇 &lt;a href=&quot;/posts/linux-docker-auto-update/&quot;&gt;《如何在Linux自动更新Docker容器》&lt;/a&gt; 解决的是「镜像怎么保持新」，&lt;a href=&quot;/posts/docker-security-resources/&quot;&gt;《Docker 安全与资源限制实战》&lt;/a&gt; 解决的是「容器运行时怎么关进笼子」。但还有一个问题夹在中间没人管：&lt;strong&gt;你拉下来的镜像，本身干不干净？&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;很多人有个错觉，觉得基础镜像用 &lt;code&gt;latest&lt;/code&gt;、依赖锁文件不乱动，就万事大吉。实际上&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;用着 latest，不等于用着安全&amp;lt;/span&amp;gt;：&lt;code&gt;nginx:latest&lt;/code&gt; 这类官方镜像里躺着几十上百个系统包，其中任何一个爆了 CVE（公共漏洞披露），你的容器就原样继承。更麻烦的是应用依赖——一个两年没动的 &lt;code&gt;package-lock.json&lt;/code&gt;，可能锁着早就上了通缉名单的库。&lt;/p&gt;
&lt;p&gt;这篇讲的工具是 Trivy：上线前先给镜像做一次体检，把漏洞按等级列清楚。这篇的主线先说在前面：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;扫描的目的不是零漏洞，而是分级处置&amp;lt;/span&amp;gt;——高危的拦下来修，低危的知晓并排期。抱着「扫出一条都不许上线」的心态用扫描器，最后只会把扫描器关掉，这在后面讲门禁时还会再强调一次。&lt;/p&gt;
&lt;h2&gt;为什么镜像里会有漏洞&lt;/h2&gt;
&lt;p&gt;先把账算清楚。一个镜像的漏洞来源就两处：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;来源&lt;/th&gt;
&lt;th&gt;典型内容&lt;/th&gt;
&lt;th&gt;谁负责更新&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;基础镜像的系统包&lt;/td&gt;
&lt;td&gt;OpenSSL、curl、glibc、zlib 等 OS 层库&lt;/td&gt;
&lt;td&gt;基础镜像维护者，你重新构建或拉新版才生效&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;应用依赖&lt;/td&gt;
&lt;td&gt;npm / pip / Go modules 等语言级依赖&lt;/td&gt;
&lt;td&gt;你自己，改锁文件、升版本&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;说白了，你对一个镜像的信任不应该来自「它是官方发布的」，而应该来自「我扫过，我知道里面装了什么、带着哪些已知问题」。前者是盲信，后者才是底数。&lt;/p&gt;
&lt;p&gt;这两处有个共同特点：&lt;strong&gt;漏洞是随时间「长」出来的&lt;/strong&gt;。镜像构建那天干干净净，过三个月，里面的某个库被披露了高危漏洞，镜像文件一个字节没变，安全状态却已经从「干净」变成「带病」。这就是为什么扫描不是构建时做一次就完事，而是要反复做——尤其是用了自动更新之后，新镜像进来之前更应该过一眼。&lt;/p&gt;
&lt;p&gt;应用依赖那一路出事起来更隐蔽。2021 年底的 Log4Shell（CVE-2021-44228）就是典型：一个几乎每个 Java 项目都在用的日志库爆出远程代码执行，无数服务镜像本身一行代码没改、基础镜像也没问题，仅仅因为依赖树里躺着这个库，一夜之间全成了高危。这类事件靠人工盯新闻根本盯不过来，只能靠工具把每个镜像的依赖清单和漏洞库逐条比对——这正是扫描器存在的意义：它不判断你的代码写得好不好，它只做一件苦力活，把「你用了哪些包、每个包现在有没有已知漏洞」这本账，随时算给你看。&lt;/p&gt;
&lt;p&gt;还有个反直觉的事实：&lt;strong&gt;漏洞数量多不代表镜像差&lt;/strong&gt;。Debian 这类全量基础镜像包多，扫出来上百条很常见，其中绝大多数是低危、或者根本没有修复版本、或者触发条件在你的场景里根本不成立。反过来，一个只扫出 3 条的镜像，如果其中一条是可远程利用的 CRITICAL，比 150 条低危严重得多。看扫描报告，永远先看等级和可修复性，再看数量。&lt;/p&gt;
&lt;h2&gt;Trivy 是什么，两种运行方式&lt;/h2&gt;
&lt;p&gt;Trivy 是 Aqua Security 开源的扫描器，一个工具能扫好几样东西：镜像漏洞、IaC 配置问题、项目依赖、硬编码密钥。这篇以镜像漏洞扫描为主，后面会带到配置扫描和依赖扫描。它的漏洞数据来自各发行版安全公告和 NVD 等公开库，本地缓存一份数据库，扫描时不需要把镜像传到任何云端，&lt;strong&gt;全程在本机完成&lt;/strong&gt;，这点对自托管场景很重要。&lt;/p&gt;
&lt;p&gt;先把它的边界说清，免得用错期待：Trivy 查的是&lt;strong&gt;已知漏洞&lt;/strong&gt;——已经被披露、编了号、进了数据库的那些。它查不出没人发现过的未知漏洞，也看不懂你的业务代码逻辑有没有问题。所以「扫描零高危」只能读作「没有已知的、可利用性明确的大问题」，不能读作「绝对安全」。它的定位是上线前的一道体检关卡，替代不了运行时加固和最小权限那些基本功，这也是为什么这篇要和安全篇配套着看。&lt;/p&gt;
&lt;p&gt;运行方式有两种，按场景选：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方式&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;th&gt;代价&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;安装二进制&lt;/td&gt;
&lt;td&gt;长期使用、接 CI、定时任务&lt;/td&gt;
&lt;td&gt;要装一次、偶尔升级&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;跑容器版 &lt;code&gt;aquasec/trivy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;临时扫一下、不想装东西&lt;/td&gt;
&lt;td&gt;每次要带一长串参数，漏洞库缓存要挂卷&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;方式一：安装二进制&lt;/h3&gt;
&lt;p&gt;Debian / Ubuntu 用官方 apt 源：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo apt-get install -y wget gnupg
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg &amp;gt; /dev/null
echo &quot;deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main&quot; | sudo tee /etc/apt/sources.list.d/trivy.list
sudo apt-get update
sudo apt-get install -y trivy
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;装完验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;trivy --version
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;方式二：跑容器版&lt;/h3&gt;
&lt;p&gt;不想装，就用官方镜像跑一次性容器。扫本机 Docker 里的镜像需要挂载 &lt;code&gt;docker.sock&lt;/code&gt;，漏洞库缓存挂个卷出来，不然每次都要重新下数据库：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $HOME/.cache/trivy:/root/.cache \
  aquasec/trivy:latest image nginx:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;挂载 docker.sock 约等于交出宿主机的 root 权限&amp;lt;/span&amp;gt;，这一点在安全篇里专门讲过。容器版 Trivy 只应该在你自己的机器上、扫你自己的镜像时这样用；生产服务器上更推荐装二进制，或者只扫远程镜像（见下文），不要为了图省事长期挂着 sock 跑来路不明的扫描容器。
:::&lt;/p&gt;
&lt;h3&gt;扫远程镜像：不用先 pull&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;trivy image&lt;/code&gt; 后面直接跟镜像名就行。本地 Docker 里没有这个镜像时，Trivy 会通过仓库 API 直接读取镜像的层来分析，&lt;strong&gt;不需要先 &lt;code&gt;docker pull&lt;/code&gt;&lt;/strong&gt;，也不会把镜像真正下载进本机 Docker：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 扫 Docker Hub 上的官方镜像
trivy image nginx:1.27

# 扫 GHCR 上的镜像
trivy image ghcr.io/owner/myapp:v1.2.0

# 扫本地镜像文件（离线搬运过来的 tar 包）
trivy image --input myapp.tar
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这意味着你可以在镜像真正部署之前，在任何一台机器上先把它扫一遍，扫完再决定要不要拉到服务器上。&lt;/p&gt;
&lt;h2&gt;第一次扫描实战：输出逐段解读&lt;/h2&gt;
&lt;p&gt;直接对最常见的官方镜像开扫：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;trivy image nginx:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第一次运行会先下载漏洞数据库（下一节专门讲），然后输出分两段。第一段是汇总头：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;nginx:latest (debian 12.8)
==========================
Total: 156 (UNKNOWN: 0, LOW: 85, MEDIUM: 47, HIGH: 21, CRITICAL: 3)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这一行交代了四件事：扫的是哪个镜像、它的 OS 是什么版本、总共多少条、按等级各多少。&lt;strong&gt;先看这里的 CRITICAL 和 HIGH 数字&lt;/strong&gt;，心里有个底，再往下看明细。&lt;/p&gt;
&lt;p&gt;第二段是明细表（以下为节选示意）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;┌────────────────┬────────────────┬──────────┬────────┬───────────────────┬───────────────┬──────────────────────────────────────────┐
│    Library     │ Vulnerability  │ Severity │ Status │ Installed Version │ Fixed Version │                 Title                  │
├────────────────┼────────────────┼──────────┼────────┼───────────────────┼───────────────┼──────────────────────────────────────────┤
│ libssl3        │ CVE-2023-5363  │ MODERATE │ fixed  │ 3.0.11-1~deb12u1  │ 3.0.11-1~   │ openssl: incorrect cipher key handling   │
│ curl           │ CVE-2023-38545 │ HIGH     │ fixed  │ 7.88.1-10         │ 7.88.1-10+  │ curl: SOCKS5 heap buffer overflow        │
│ ...            │ ...            │ ...      │ ...    │ ...               │ ...           │ ...                                      │
└────────────────┴────────────────┴──────────┴────────┬───────────────────┴───────────────┴──────────────────────────────────────────┘
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;每一列怎么看：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;列&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;怎么读&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Library&lt;/td&gt;
&lt;td&gt;出问题的包名&lt;/td&gt;
&lt;td&gt;先看认不认识：系统库还是应用依赖，决定找谁修&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Vulnerability&lt;/td&gt;
&lt;td&gt;漏洞编号，一般是 CVE 编号&lt;/td&gt;
&lt;td&gt;拿它去查详情、写忽略清单、跟同事沟通都用这个号&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Severity&lt;/td&gt;
&lt;td&gt;严重等级&lt;/td&gt;
&lt;td&gt;处置优先级的第一依据，下一节细讲&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Status&lt;/td&gt;
&lt;td&gt;修复状态&lt;/td&gt;
&lt;td&gt;&lt;code&gt;fixed&lt;/code&gt; 表示已有修复版；&lt;code&gt;affected&lt;/code&gt; 表示受影响但还没修复版；还有 &lt;code&gt;will_not_fix&lt;/code&gt;（官方明确不修）等&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Installed Version&lt;/td&gt;
&lt;td&gt;你镜像里装的版本&lt;/td&gt;
&lt;td&gt;和下一列对比，看差了多少&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Fixed Version&lt;/td&gt;
&lt;td&gt;修复版本&lt;/td&gt;
&lt;td&gt;空的或者没有这一项，就是暂时无药可救，只能等或换&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Title&lt;/td&gt;
&lt;td&gt;漏洞一句话说明&lt;/td&gt;
&lt;td&gt;快速判断跟自己有没有关系，比如一个打印组件的漏洞出现在纯 API 服务里，优先级自然靠后&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;读报告的顺序建议固定下来：&lt;strong&gt;先按 Severity 从高到低，只看 CRITICAL 和 HIGH；再在其中只看 Status 为 fixed、有 Fixed Version 的&lt;/strong&gt;——这批是「现在就能修」的。剩下的高危没修复版的，单独记下来评估风险；中低危扫一眼数量，做到心里有数即可。&lt;/p&gt;
&lt;p&gt;补一个范围问题：&lt;code&gt;trivy image&lt;/code&gt; 默认把两类包一起扫——OS 系统包和语言级依赖（镜像里能找到的 &lt;code&gt;package-lock.json&lt;/code&gt;、jar 包清单、Go 二进制的模块信息等），报告里如果条目特别多，先看 Library 列区分来源。如果只想看系统包、或者只想看应用依赖，用 &lt;code&gt;--vuln-type&lt;/code&gt; 限定：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 只看 OS 系统包
trivy image --vuln-type os nginx:latest
# 只看语言级依赖
trivy image --vuln-type library myapp:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;分开看的好处是责任清楚：OS 包的问题归基础镜像，升基础镜像解决；依赖的问题归代码仓库，改锁文件解决。混在一起看，很容易对着一堆系统包漏洞去改应用代码，白忙活。&lt;/p&gt;
&lt;h2&gt;严重等级体系与处置策略&lt;/h2&gt;
&lt;p&gt;Trivy 的等级来自各漏洞库的 CVSS 评分，共五档：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;等级&lt;/th&gt;
&lt;th&gt;大致含义&lt;/th&gt;
&lt;th&gt;处置策略&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;CRITICAL&lt;/td&gt;
&lt;td&gt;可远程利用、影响大，可能已有公开利用&lt;/td&gt;
&lt;td&gt;立刻处理：有修复版马上升级上线；没修复版评估是否先下线或加防护&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HIGH&lt;/td&gt;
&lt;td&gt;利用门槛不高或影响明显&lt;/td&gt;
&lt;td&gt;本轮就修：纳入最近一次发布，门禁拦截的下限一般设在这一档&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MEDIUM&lt;/td&gt;
&lt;td&gt;有利用条件限制，或影响有限&lt;/td&gt;
&lt;td&gt;排期处理：跟着基础镜像的常规更新一起走，定期回看&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;LOW&lt;/td&gt;
&lt;td&gt;触发条件苛刻，影响小&lt;/td&gt;
&lt;td&gt;知晓即可，不单独为它发版&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;UNKNOWN&lt;/td&gt;
&lt;td&gt;来源库没给评分&lt;/td&gt;
&lt;td&gt;当 LOW 对待，但要留意数量异常增多&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;注意两个坑。第一，&lt;strong&gt;等级是漏洞库给的，不是结合你的场景评的&lt;/strong&gt;。一个需要本地权限才能触发的 HIGH，在你的容器里可能根本够不着；反过来一个 MEDIUM 如果正好打在你暴露在公网的组件上，就得当 HIGH 处理。等级是起点，判断在你。第二，不同来源对同一 CVE 的评分可能不一致，Trivy 默认以发行版安全公告为准，这通常更贴近「这个包在当前系统上到底修没修」。&lt;/p&gt;
&lt;h2&gt;降噪三件套：把报告缩到能看的尺寸&lt;/h2&gt;
&lt;p&gt;全量报告动辄一两百条，没人看得下去。实战中靠三个手段把它缩到「一屏以内、条条要处理」：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一，只看高危。&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;trivy image --severity HIGH,CRITICAL nginx:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第二，只看有修复版的。&lt;/strong&gt; 没修复版的你看了也修不了，先从行动清单里拿掉，单独定期回看：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;trivy image --severity HIGH,CRITICAL --ignore-unfixed nginx:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这两条组合下来，156 条通常就剩个位数到十几条，这才是能真正动手处理的清单。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三，&lt;code&gt;.trivyignore&lt;/code&gt; 忽略已评估项。&lt;/strong&gt; 有些高危漏洞经过评估确实与自己无关（组件在，但相关功能没启用、接口不对外），或者暂时只能接受风险。在项目目录放一个 &lt;code&gt;.trivyignore&lt;/code&gt; 文件，Trivy 运行时会自动读取：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 示例编号，实际填写真实 CVE 编号
# 评估结论：该组件的漏洞路径需要本地文件访问，容器内无此场景，风险接受
# 评估人：Anexns，复查日期：2026-02-15
CVE-2025-12345
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;写法上三条规范：&lt;strong&gt;一个编号一行；每条必须写注释说明为什么忽略；注释里带上复查日期&lt;/strong&gt;。没有注释的忽略项，三个月后没人敢动、也没人记得为什么忽略，它就会变成永久盲区。忽略是「评估后接受」，不是「眼不见为净」，这两者的区别全在注释里。&lt;/p&gt;
&lt;p&gt;另外两个常用参数一并记住：&lt;code&gt;--scanners vuln&lt;/code&gt; 明确只扫漏洞（关掉密钥、配置等其他扫描器，出报告更快更干净）；&lt;code&gt;--format json&lt;/code&gt; 输出 JSON，适合把结果存档或喂给其他脚本做对比。&lt;/p&gt;
&lt;h2&gt;不止扫漏洞：配置扫描与依赖扫描&lt;/h2&gt;
&lt;p&gt;Trivy 还有两个顺手的功能，和镜像扫描配合着用效果更好。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;trivy config&lt;/code&gt; 扫配置问题。&lt;/strong&gt; 它检查 Dockerfile、docker-compose.yaml、Kubernetes 清单等文件里的错误配置，比如以 root 用户运行、特权模式、敏感端口暴露等：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 扫当前目录下所有配置文件
trivy config .

# 只扫某个 Dockerfile
trivy config ./Dockerfile
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出会给出检查项编号、问题描述和修改建议。它和 &lt;a href=&quot;/posts/docker-security-resources/&quot;&gt;《Docker 安全与资源限制实战》&lt;/a&gt; 里讲的那些加固项正好互补：那篇讲「应该怎么做」，这个工具帮你自动查「有没有做到」。注意它扫的是&lt;strong&gt;文件里的写法&lt;/strong&gt;，不代表运行时真实状态，两边都看才完整。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;trivy fs&lt;/code&gt; 扫项目依赖。&lt;/strong&gt; 它直接扫项目目录里的锁文件（&lt;code&gt;package-lock.json&lt;/code&gt;、&lt;code&gt;requirements.txt&lt;/code&gt;、&lt;code&gt;go.mod&lt;/code&gt; 等），不用先把镜像构建出来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;trivy fs --scanners vuln .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;适合在写代码阶段就发现某个依赖版本有问题，把修复点提前到构建之前。镜像扫描和 fs 扫描的关系是：fs 扫的是「源头清单」，镜像扫的是「最终成品」，成品为准，源头用来提前预警。&lt;/p&gt;
&lt;h2&gt;门禁策略：只拦高危，别把门禁做成摆设&lt;/h2&gt;
&lt;p&gt;扫描真正的价值，是接进流程里当一道门：镜像不合格就不许上线。Trivy 用 &lt;code&gt;--exit-code&lt;/code&gt; 实现这一点——默认扫描永远返回 0（扫到漏洞也算「成功执行」），加上这个参数后，发现符合条件的漏洞就返回非 0，脚本和 CI 就能拦住：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;trivy image --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 myapp:latest
echo $?   # 0 表示通过，非 0 表示被拦下
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;接进发布脚本，就是这么一段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
set -e
docker build -t myapp:latest .
# 门禁：存在「有修复版的高危漏洞」就中止发布
trivy image --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 myapp:latest
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;接进 GitHub Actions 这类 CI 也一样，把构建和扫描放进同一个 job，扫描不过，后面的推送、部署步骤自然不会执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;- name: Build image
  run: docker build -t myapp:${{ github.sha }} .
- name: Scan image
  run: |
    docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
      aquasec/trivy:latest image \
      --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 \
      myapp:${{ github.sha }}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;门禁阈值怎么定，是这件事成败的关键。&lt;strong&gt;不要把标准定成「有任何漏洞就拦截」&lt;/strong&gt;。基础镜像里常年躺着几十条中低危和无修复版的漏洞，全拦等于永远发不了版。后果不用猜：第一次大家改镜像，第二次开始申请例外，第三次&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;门禁天天误报，迟早被人整体关掉&amp;lt;/span&amp;gt;——很多团队的安全扫描就是这么变成摆设的。&lt;/p&gt;
&lt;p&gt;能长期跑下去的门禁长这样：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;拦截（返回失败）&lt;/th&gt;
&lt;th&gt;只报告（不拦）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;CRITICAL 且有修复版&lt;/td&gt;
&lt;td&gt;CRITICAL / HIGH 但无修复版（单独建清单定期回看）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HIGH 且有修复版&lt;/td&gt;
&lt;td&gt;MEDIUM / LOW / UNKNOWN 全部&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;逻辑很简单：&lt;strong&gt;只拦「你现在就能修」的问题&lt;/strong&gt;。拦下来的每一条都有明确动作（升级），执行的人没怨气，门禁才活得久。&lt;/p&gt;
&lt;p&gt;门禁之外，再养成一个存档习惯：每次发布用 &lt;code&gt;--format json&lt;/code&gt; 把完整报告存一份，文件名带上日期和镜像 digest。存档不是为了应付检查，而是为了能做对比——这次比上次多出来的条目，才是真正需要关注的「新增风险」；长期不变的老条目，说明它们已经在你的接受清单里。没有历史对比，每次面对全量报告都要从头判断一遍，扫描很快就会因为「太费神」被跳过。&lt;/p&gt;
&lt;h2&gt;和自动更新怎么配合&lt;/h2&gt;
&lt;p&gt;用了 &lt;a href=&quot;/posts/linux-docker-auto-update/&quot;&gt;《如何在Linux自动更新Docker容器》&lt;/a&gt; 里的 Watchtower 之后，更新是全自动的，扫描放哪一步？分两种情况：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;镜像来自你自己的 CI&lt;/strong&gt;：在 CI 里把关（构建 → 扫描门禁 → 推送仓库），Watchtower 只拉通过扫描的版本。服务器端什么都不用改，这是最干净的做法，前提是你的镜像不用 &lt;code&gt;latest&lt;/code&gt; 乱飘，而是用明确版本号，让「通过扫描的那一版」和「上线的那一版」是同一个。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;镜像来自第三方（官方镜像、开源项目）&lt;/strong&gt;：Watchtower 拉到什么全凭上游，你控制不了版本。务实的办法是加一个定期巡检：定时对正在跑的镜像扫一遍高危，把结果推给你自己看，而不是拦更新：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 每周巡检：只报告，不拦截，看完人工决定要不要处理
trivy image --severity HIGH,CRITICAL --ignore-unfixed \
  --format table $(docker ps --format &apos;{{.Image}}&apos; | sort -u)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;发现某个在跑的镜像爆了可利用的 CRITICAL，再人工介入：要么等上游出修复版后手动拉一次，要么临时加防护。自动更新管「保持新」，巡检管「新进来的干不干净」，两者不冲突。&lt;/p&gt;
&lt;h2&gt;扫出漏洞之后：修复的决策顺序&lt;/h2&gt;
&lt;p&gt;修复不是把报告里每个包挨个升一遍，按这个顺序来，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;先修基础镜像，再修应用依赖&amp;lt;/span&amp;gt;，大多数条目会在第一步就消失：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;升基础镜像&lt;/strong&gt;。报告里七成以上的系统包漏洞，是因为基础镜像旧。把 Dockerfile 里的 &lt;code&gt;FROM debian:12&lt;/code&gt; 对应的小版本更新、或者直接重新拉最新基础镜像重新构建，很多条目立刻没了——上游发行版早就修好了，只是你的镜像还停在旧快照上。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;定点升系统包&lt;/strong&gt;。基础镜像已经是最新、个别包还没跟上时，在 Dockerfile 里对那个包做定点升级。一般不建议无差别 &lt;code&gt;apt-get upgrade&lt;/code&gt; 把镜像层搅乱，但对明确有漏洞的包定点升，是可接受的临时手段，并把原因写在注释里。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;升应用依赖&lt;/strong&gt;。Library 列里是语言依赖的，改锁文件升到修复版本，重新构建。这类修复通常最快，因为版本跨度小。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;换更小的基础镜像&lt;/strong&gt;。如果某个服务总是被一堆用不上的系统包拖着报漏洞，考虑换 slim 甚至 distroless：包越少，攻击面越小，以后报告也越短。这是结构性修复，放在最后做，要回归测试。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;复扫验证&lt;/strong&gt;。修完重新扫一遍，对比 Total 和高危数量，确认目标条目真的消失、且没有引入新问题。&lt;strong&gt;没复扫的修复等于没修完&lt;/strong&gt;，因为你不知道升级动作到底有没有落到最终镜像里。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;实在修不了的（无修复版、或升级会牵动太多），回到 &lt;code&gt;.trivyignore&lt;/code&gt; 的流程：写清评估结论和复查日期，接受风险并留痕，而不是假装没看见。&lt;/p&gt;
&lt;h2&gt;漏洞数据库更新与离线环境&lt;/h2&gt;
&lt;p&gt;Trivy 的漏洞数据不在程序里，而是第一次运行时从官方仓库（GHCR 上的 &lt;code&gt;trivy-db&lt;/code&gt;）下载一份数据库到本地缓存（默认在 &lt;code&gt;~/.cache/trivy&lt;/code&gt;），之后每次运行会检查并增量更新。几个必须知道的点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;首次运行慢，主要是它在下数据库&lt;/strong&gt;，不是扫描慢。容器版如果不挂缓存卷，每次都是「首次」，这是最常见的慢因，解决办法就是前面部署时把 &lt;code&gt;$HOME/.cache&lt;/code&gt; 挂出来。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;--skip-db-update&lt;/code&gt; 是双刃剑&lt;/strong&gt;。CI 里为省时间、或网络受限时可以跳过数据库更新、用缓存里的旧库扫。但&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;长期跳过数据库更新，扫出来的「干净」是假的&amp;lt;/span&amp;gt;——新披露的漏洞根本不在你的库里，报告再绿也不能说明问题。跳过可以，必须同时有机制保证数据库定期真的更新一次。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;纯离线环境&lt;/strong&gt;（内网服务器不通外网）的做法：在一台能上网的机器上执行 &lt;code&gt;trivy image --download-db-only&lt;/code&gt; 把数据库下到缓存目录，把整个缓存目录打包拷到离线机器的相同位置，再配合 &lt;code&gt;--skip-db-update&lt;/code&gt;（有条件可再加 &lt;code&gt;--offline-scan&lt;/code&gt; 禁止一切外连尝试）运行；或者用 &lt;code&gt;--db-repository&lt;/code&gt; 把数据库来源指向内网自建的 OCI 镜像仓库。离线库的新鲜度靠你拷贝的频率，建议至少每周同步一次。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
数据库版本不同，同一镜像在不同时间扫出的结果可以不同：今天扫着干净，下周新 CVE 进库后同一镜像又报出高危，这不是工具不准，而是事实变了。对外汇报或留档时，养成习惯在报告旁记下扫描日期和镜像 digest，避免日后对不上账。
:::&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;扫描特别慢。&lt;/strong&gt; 先分清慢在哪一段：开头长时间没输出，多半在下数据库——检查缓存目录有没有挂对、网络到 GHCR 通不通；数据库就绪后还慢，通常是镜像层太多太大，或同时开了 config、secret 等其他扫描器。处理顺序：挂好缓存卷 → 加 &lt;code&gt;--scanners vuln&lt;/code&gt; 只扫漏洞 → CI 里把 &lt;code&gt;~/.cache/trivy&lt;/code&gt; 做成缓存复用。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;结果几百条，无从下手。&lt;/strong&gt; 这是没降噪的必然结果，不是镜像没救了。直接套降噪三件套：&lt;code&gt;--severity HIGH,CRITICAL --ignore-unfixed&lt;/code&gt; 先把清单缩到个位数；再按 Library 列看聚集在哪个基础层，优先升基础镜像，一步消掉一大批；剩下的逐条按修复顺序处理。永远不要从报告第一行开始逐条啃，那是按包名字母序排的，和重要程度无关。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;扫描结果和镜像版本对不上。&lt;/strong&gt; 最常见的原因是 tag 漂移：你以为扫的是服务器上跑的那一版 &lt;code&gt;myapp:latest&lt;/code&gt;，但本地的 &lt;code&gt;latest&lt;/code&gt; 是另一时间拉的另一个构建。tag 是会动的标签，不是一致性保证。处理办法：扫之前先 &lt;code&gt;docker pull&lt;/code&gt; 确保本地就是最新；要严格对账就按 digest 扫，把版本钉死：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 先看在跑的镜像 digest
docker inspect --format &apos;{{index .RepoDigests 0}}&apos; myapp:latest
# 按 digest 扫描，结果与线上严格对应
trivy image myapp@sha256:&amp;lt;digest&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;另一种对不上是两台机器数据库新旧不同导致的条目差异，按上一节说的，核对扫描日期和数据库更新时间即可，别急着怀疑镜像被换了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;明明升级了，还报同一条。&lt;/strong&gt; 先确认三件事：部署的容器是不是真的换成了新镜像（&lt;code&gt;docker ps&lt;/code&gt; 看镜像 ID 和创建时间，老容器没重建是最常见的原因）；你改的是不是最终进镜像的那一份文件（多阶段构建里改了构建阶段、运行阶段拷的还是旧产物，报告里会照报不误）；同一个包在镜像里是不是有多份（比如基础层一份、应用又 vendor 了一份，Trivy 按实际文件逐份报告，修掉一份还剩一份）。按这三条顺序查，基本都能对上。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;容器版报连不上 Docker。&lt;/strong&gt; 检查 &lt;code&gt;docker.sock&lt;/code&gt; 路径在不在、挂载参数有没有写错；有些环境 Docker 走了 rootless 或自定义 socket 路径，挂载源路径要跟着改。实在不行就装二进制版，少一层挂载少一类问题。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;镜像的漏洞来自基础镜像系统包和应用依赖两处，且会随时间「长」出来，所以扫描要反复做，不是构建时做一次就完事。&lt;/li&gt;
&lt;li&gt;Trivy 装二进制或跑容器版都行；扫远程镜像不用先 pull；容器版挂 &lt;code&gt;docker.sock&lt;/code&gt; 的权限风险心里要有数。&lt;/li&gt;
&lt;li&gt;读报告先看 CRITICAL / HIGH 且有修复版的那批；&lt;code&gt;--severity&lt;/code&gt;、&lt;code&gt;--ignore-unfixed&lt;/code&gt;、&lt;code&gt;.trivyignore&lt;/code&gt; 三件套把报告缩到能行动的尺寸，忽略必须写注释和复查日期。&lt;/li&gt;
&lt;li&gt;门禁只拦「高危且有修复版」，用 &lt;code&gt;--exit-code 1&lt;/code&gt; 接进发布脚本和 CI；全拦的门禁活不过一个月。&lt;/li&gt;
&lt;li&gt;修复顺序：升基础镜像 → 定点升系统包 → 升应用依赖 → 换更小的基础镜像，修完必须复扫。&lt;/li&gt;
&lt;li&gt;数据库是扫描的命根子：缓存要挂出来复用，&lt;code&gt;--skip-db-update&lt;/code&gt; 不能长期用，离线环境靠定期拷贝缓存或自建数据库镜像源。&lt;/li&gt;
&lt;li&gt;扫描报告要存档、版本要按 digest 对账：没有历史对比，每次都要对着全量报告从头判断一遍，工具迟早会因为太费神被跳过。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;把这篇和自动更新、安全加固两篇连起来看，就是一条完整的链：更新让镜像保持新，扫描让新进来的东西先过检，加固让跑起来的容器就算出事也掀不了桌子。&lt;/p&gt;
</content:encoded></item><item><title>Docker 数据卷与备份恢复：整站迁移实战</title><link>https://www.anexns.cloudns.org/posts/docker-volumes-backup/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/docker-volumes-backup/</guid><description>容器删了数据不能丢：命名卷、绑定挂载、tmpfs 三种数据存法对比，命名卷的打包备份与恢复标准做法，数据库备份的一致性要点，最后完整走一遍把整站搬到另一台服务器的迁移流程。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;容器是可以随时删掉重建的——镜像拉个新的、&lt;code&gt;docker compose up -d&lt;/code&gt; 一下就回来了。但容器里的数据不行：博客的文章、数据库的记录、面板的配置、上传的文件，这些东西一旦随着容器或者卷一起没了，没有任何「重新拉取」的办法。上一篇 &lt;a href=&quot;/posts/linux-docker-compose/&quot;&gt;《如何在Linux部署Docker&amp;amp;Compose》&lt;/a&gt; 讲了怎么把服务跑起来，这篇专门解决后顾之忧：&lt;strong&gt;数据到底存在哪、怎么备份、怎么恢复、出事了怎么把整站搬到另一台机器上&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;先把一句话刻在脑子里：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;容器可删，数据不行。&lt;/strong&gt;&amp;lt;/span&amp;gt; 所有备份方案的设计，都是围绕着把「数据」和「容器」分开管理展开的。&lt;/p&gt;
&lt;h2&gt;三种数据存法对比&lt;/h2&gt;
&lt;p&gt;Docker 里给容器存数据一共三种方式，先看全貌：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;存法&lt;/th&gt;
&lt;th&gt;数据实际位置&lt;/th&gt;
&lt;th&gt;谁管理&lt;/th&gt;
&lt;th&gt;备份难度&lt;/th&gt;
&lt;th&gt;典型场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;命名卷（volume）&lt;/td&gt;
&lt;td&gt;宿主机 &lt;code&gt;/var/lib/docker/volumes/&lt;/code&gt; 下&lt;/td&gt;
&lt;td&gt;Docker 全权管理&lt;/td&gt;
&lt;td&gt;中（要用容器辅助打包）&lt;/td&gt;
&lt;td&gt;数据库数据、应用持久数据&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;绑定挂载（bind mount）&lt;/td&gt;
&lt;td&gt;宿主机任意指定目录&lt;/td&gt;
&lt;td&gt;你自己&lt;/td&gt;
&lt;td&gt;低（就是普通文件，直接打包）&lt;/td&gt;
&lt;td&gt;配置文件、网站静态文件、代码目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;tmpfs&lt;/td&gt;
&lt;td&gt;宿主机内存&lt;/td&gt;
&lt;td&gt;Docker&lt;/td&gt;
&lt;td&gt;无法备份（重启即没）&lt;/td&gt;
&lt;td&gt;临时数据、敏感信息中转&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;再补两个容易混淆的点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;容器可写层&lt;/strong&gt;（不挂任何东西、直接往容器里写文件）不算一种「存法」：容器一删就全没，而且性能差。任何想留住的数据&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不许只写在容器可写层里&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;li&gt;命名卷和绑定挂载的区别不在性能（Linux 上两者性能基本一致），而在&lt;strong&gt;管理方式&lt;/strong&gt;：命名卷是 Docker 托管的「仓库」，绑定挂载是你自己当家做主的「自家柜子」。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;再顺带说清两个容易踩的概念：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;匿名卷&lt;/strong&gt;：有些镜像在 Dockerfile 里写了 &lt;code&gt;VOLUME&lt;/code&gt; 指令，或者你 run 时只写了 &lt;code&gt;-v /data&lt;/code&gt; 没给卷名，Docker 会自动生成一个名字是随机长字符串的匿名卷来接住数据。它能防止数据落进可写层，但名字不可读、没人记得住，时间一长 &lt;code&gt;docker volume ls&lt;/code&gt; 里攒一堆不知道是谁的卷，备份时也容易漏掉。重要数据一律用&lt;strong&gt;显式命名的卷&lt;/strong&gt;，匿名卷只配接无所谓的数据。用 &lt;code&gt;docker volume ls -f dangling=true&lt;/code&gt; 可以列出所有没有容器在用的卷，逐个确认后再清理。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;先看清家底再谈备份&lt;/strong&gt;：动手备份前，先用 &lt;code&gt;docker system df -v&lt;/code&gt; 看一眼每个卷的实际大小和引用情况——哪个卷在用、占了多少空间、有没有早就该删的僵尸卷，这个命令一屏全交代清楚。备份空间要按卷的实际体积预留，别等打包到一半才发现目标磁盘不够。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;选型口诀：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;数据库、应用内部数据 → &lt;strong&gt;命名卷&lt;/strong&gt;，交给 Docker 管，省心且跨平台行为一致；&lt;/li&gt;
&lt;li&gt;配置文件、要经常打开看/改的东西 → &lt;strong&gt;绑定挂载&lt;/strong&gt;，宿主机上直接能编辑；&lt;/li&gt;
&lt;li&gt;临时的、丢了无所谓的 → &lt;strong&gt;tmpfs&lt;/strong&gt; 或者干脆写可写层。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;命名卷操作全套&lt;/h2&gt;
&lt;h3&gt;基本命令&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 创建一个命名卷
docker volume create mydata

# 列出所有卷
docker volume ls

# 看某个卷的详情（挂载点、创建时间、被哪些容器用）
docker volume inspect mydata

# 删除一个卷（必须先停掉并删除使用它的容器）
docker volume rm mydata

# 清理所有没有容器在用的卷（危险，见下方警告）
docker volume prune
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;docker volume prune&lt;/code&gt; 和 &lt;code&gt;docker system prune&lt;/code&gt; 一样是「一键后悔药没有」类命令：它会&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;删掉所有当前没有容器引用的卷&amp;lt;/span&amp;gt;——包括你只是暂时把容器删了、打算一会儿重建后继续用的卷。执行前务必确认里面没有要留的数据。日常清理宁可手动 &lt;code&gt;docker volume rm&lt;/code&gt; 一个个来。
:::&lt;/p&gt;
&lt;h3&gt;卷在磁盘上的真实位置&lt;/h3&gt;
&lt;p&gt;命名卷的数据实际存放在宿主机：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/var/lib/docker/volumes/&amp;lt;卷名&amp;gt;/_data/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;比如卷 &lt;code&gt;mydata&lt;/code&gt; 的内容就在 &lt;code&gt;/var/lib/docker/volumes/mydata/_data/&lt;/code&gt; 里。知道这个位置是为了排障时能看一眼里面有什么，&lt;strong&gt;但不建议直接去改这个目录&lt;/strong&gt;：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Docker 假定这个目录只有它自己在管，你绕过它直接增删文件，权限和属主很容易被写歪，容器里再访问就报错；&lt;/li&gt;
&lt;li&gt;容器运行中直接改，应用层面的缓存和锁完全不知情，数据一致性没保证；&lt;/li&gt;
&lt;li&gt;有些存储驱动下这个路径并不长这样（比如用了远程卷插件），按路径操作的代码不可移植。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;正确姿势永远是：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;通过容器去读写卷&lt;/strong&gt;&amp;lt;/span&amp;gt;——下面的备份和恢复都是这么做的。&lt;/p&gt;
&lt;h3&gt;Compose 里怎么声明&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;services:
  db:
    image: postgres:16
    environment:
      - POSTGRES_PASSWORD=example
    volumes:
      - db_data:/var/lib/postgresql/data   # 短语法：卷名:容器内路径

volumes:
  db_data:        # 顶层 volumes 段：声明本项目用到的命名卷
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意一个关键细节：&lt;strong&gt;Compose 创建的卷名会带项目名前缀&lt;/strong&gt;。假设项目名（目录名）是 &lt;code&gt;myapp&lt;/code&gt;，你在文件里写的 &lt;code&gt;db_data&lt;/code&gt;，真实卷名是 &lt;code&gt;myapp_db_data&lt;/code&gt;。用 &lt;code&gt;docker volume ls&lt;/code&gt; 看到带前缀的卷别慌，那不是多出来的野卷子。排障一节会讲这个前缀带来的经典问题和解法。&lt;/p&gt;
&lt;p&gt;只读挂载和绑定挂载的写法也顺带记住：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    volumes:
      - db_data:/var/lib/postgresql/data        # 可读写（默认）
      - ./config:/etc/myapp/config:ro           # 绑定挂载 + 只读
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;绑定挂载的注意事项&lt;/h2&gt;
&lt;p&gt;绑定挂载把宿主机目录直接「投影」进容器，方便是方便，坑也最集中在这一块。&lt;/p&gt;
&lt;h3&gt;坑一：宿主机路径不存在时&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;docker run -v /host/path:/data ...&lt;/code&gt; 时如果 &lt;code&gt;/host/path&lt;/code&gt; 不存在，Docker 会&lt;strong&gt;自动以 root 身份创建一个空目录&lt;/strong&gt;。你以为挂的是自己准备好的目录，其实挂了个空的，应用写进去的数据落在一个 root 属主的陌生目录里。Compose 的短语法同样如此。用长语法可以明确禁止这种行为：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    volumes:
      - type: bind
        source: ./config
        target: /etc/myapp/config
        read_only: true
        bind:
          create_host_path: false   # 路径不存在就直接报错，而不是偷偷新建
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;坑二：属主与容器内 uid 对不上（最经典）&lt;/h3&gt;
&lt;p&gt;容器里的进程用什么 uid 运行，取决于镜像，常见情况：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;官方 &lt;code&gt;postgres&lt;/code&gt; 镜像里 postgres 用户是 uid 999；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;nginx&lt;/code&gt; 镜像 worker 进程是 uid 101；&lt;/li&gt;
&lt;li&gt;很多镜像默认直接用 root（uid 0）。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;绑定挂载&lt;strong&gt;不会做任何 uid 转换&lt;/strong&gt;：宿主机上属主是 uid 1000 的文件，进了容器就还是 uid 1000。于是经典报错就来了——容器内进程是 uid 999，宿主机目录属主是 1000 且权限 755，进程没有写权限，直接 &lt;code&gt;Permission denied&lt;/code&gt; 起不来。&lt;/p&gt;
&lt;p&gt;排查和处理：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 查宿主机上自己的 uid/gid
id

# 查目录现在的属主（显示数字 uid/gid）
ls -n /srv/myapp/data

# 把目录属主改成容器内进程需要的 uid（例：999）
sudo chown -R 999:999 /srv/myapp/data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个原则：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;不要无脑 &lt;code&gt;chmod 777&lt;/code&gt;&lt;/strong&gt;。777 能「解决」权限问题，也能让任何进程随便写你的数据，只是把报错换成了安全隐患。&lt;/li&gt;
&lt;li&gt;能选的话优先用命名卷：Docker 创建卷时会把卷目录的属主初始化为镜像里对应路径的属主，上面这个坑基本不会出现——这也是数据库类服务推荐命名卷的原因之一。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;坑三：只读挂载 &lt;code&gt;:ro&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;还有个写法上的细节：Compose 里绑定挂载用 &lt;code&gt;./config&lt;/code&gt; 这种相对路径时，它是相对于 &lt;strong&gt;Compose 文件所在目录&lt;/strong&gt;解析的，不是你执行命令时所在的目录。项目目录搬家时绑定挂载会跟着 Compose 文件走，这通常正是你想要的；但如果在别的目录用 &lt;code&gt;-f&lt;/code&gt; 指定 Compose 文件，就要意识到相对路径的锚点也随之变了，排障时先确认锚点再怀疑文件丢了。&lt;/p&gt;
&lt;p&gt;配置文件类挂载建议一律加 &lt;code&gt;:ro&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;      - ./nginx.conf:/etc/nginx/nginx.conf:ro
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;容器被攻破时写不进配置，也改不了你的站点文件，属于零成本的安全加固。注意 &lt;code&gt;:ro&lt;/code&gt; 只约束容器这一侧，宿主机上你自己照样能改。&lt;/p&gt;
&lt;h2&gt;命名卷备份：标准做法&lt;/h2&gt;
&lt;p&gt;命名卷的数据不在你的项目目录里，没法直接 &lt;code&gt;tar&lt;/code&gt; 项目目录了事。标准做法是&lt;strong&gt;起一个临时容器，把卷挂进去，在容器里把卷内容打包到挂进来的备份目录&lt;/strong&gt;。听起来绕，其实一条命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 在项目目录下先建好备份存放点
mkdir -p ~/backups

# 备份卷 myapp_db_data（换成你自己的真实卷名）
docker run --rm \
  -v myapp_db_data:/data:ro \
  -v ~/backups:/backup \
  alpine \
  tar czf /backup/db_data-$(date +%F).tar.gz -C /data .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐参数讲解，这条命令每一部分都有讲究：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;docker run --rm&lt;/code&gt;：临时容器，用完自动删除，不留垃圾；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;-v myapp_db_data:/data:ro&lt;/code&gt;：把要备份的卷挂到临时容器的 &lt;code&gt;/data&lt;/code&gt;，&lt;strong&gt;加 &lt;code&gt;:ro&lt;/code&gt; 只读&lt;/strong&gt;——备份是读操作，只读挂载保证备份过程绝不可能误伤原数据；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;-v ~/backups:/backup&lt;/code&gt;：把宿主机的备份目录挂到容器的 &lt;code&gt;/backup&lt;/code&gt;，打包产物写这里，容器删了产物还在宿主机上；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;alpine&lt;/code&gt;：用最小的工具镜像即可，它自带 &lt;code&gt;tar&lt;/code&gt;。手边有 &lt;code&gt;ubuntu&lt;/code&gt; 镜像也一样；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;tar czf /backup/db_data-$(date +%F).tar.gz -C /data .&lt;/code&gt;：在容器里执行打包。&lt;code&gt;-C /data .&lt;/code&gt; 的意思是「切到 /data 目录，把当前目录的内容打包」——打包的是&lt;strong&gt;内容&lt;/strong&gt;而不是 &lt;code&gt;data&lt;/code&gt; 这个目录本身，恢复时就不会多出一层目录（排障一节会讲这个经典失误）；文件名里用 &lt;code&gt;$(date +%F)&lt;/code&gt; 自动带上日期，如 &lt;code&gt;db_data-2026-11-15.tar.gz&lt;/code&gt;，一眼能看出是哪天的备份。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;另一种等价写法是 &lt;code&gt;--volumes-from&lt;/code&gt;，直接借用正在运行的容器所挂的全部卷：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run --rm \
  --volumes-from myapp-db-1 \
  -v ~/backups:/backup \
  alpine \
  tar czf /backup/all-volumes-$(date +%F).tar.gz -C /data .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--volumes-from &amp;lt;容器名&amp;gt;&lt;/code&gt; 会把那个容器挂的卷按相同路径挂到临时容器上。适合一个容器挂了好几个卷、想一次全打走的情况；缺点是路径要以原容器的挂载点为准，写命令前先 &lt;code&gt;docker inspect&lt;/code&gt; 确认清楚。新手建议优先用第一种 &lt;code&gt;-v 卷名:/data&lt;/code&gt; 的写法，路径自己说了算，不容易错。&lt;/p&gt;
&lt;p&gt;:::warning
备份文件生成后立刻验一下，别等恢复时才发现包是坏的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 能列出内容且不报错，包基本完好
tar tzf ~/backups/db_data-2026-11-15.tar.gz | head

# 顺手看一眼大小，0 字节或者小得离谱肯定有问题
ls -lh ~/backups/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;h2&gt;命名卷恢复：标准做法&lt;/h2&gt;
&lt;p&gt;恢复是备份的逆操作：先建一个空卷，再用临时容器把备份包解进卷里。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 创建目标卷（如果卷已存在且里面是旧数据，先确认再删掉重建）
docker volume create myapp_db_data

# 2. 把备份包解进卷
docker run --rm \
  -v myapp_db_data:/data \
  -v ~/backups:/backup \
  alpine \
  tar xzf /backup/db_data-2026-11-15.tar.gz -C /data

# 3. 验证：列一下卷里的内容，确认文件都在
docker run --rm -v myapp_db_data:/data alpine ls -la /data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;因为备份时打的是「&lt;code&gt;/data&lt;/code&gt; 里面的内容」，恢复时直接解到 &lt;code&gt;/data&lt;/code&gt; 就严丝合缝，&lt;strong&gt;不需要也不应该加 &lt;code&gt;--strip-components&lt;/code&gt;&lt;/strong&gt;；&lt;/li&gt;
&lt;li&gt;解包在容器里以 root 执行，文件属主会按包里记录的 uid/gid 还原（tar 默认保留属主），这正是我们想要的——原数据是 uid 999 的，回来还是 999；&lt;/li&gt;
&lt;li&gt;恢复前如果目标卷不是空的，旧文件会和解出来的文件混在一起。稳妥做法是恢复到&lt;strong&gt;新建的空卷&lt;/strong&gt;，确认无误后再让服务切换过去。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;验证不能只停在「文件在」。最后一定要把真正的服务挂上这个卷启动起来，看它能不能正常读数据：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose logs -f db   # 看数据库是否正常完成初始化/恢复
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;服务能起来、应用能读到历史数据，恢复才算完成。&lt;/p&gt;
&lt;p&gt;最后强调一句容易被跳过的话：&lt;strong&gt;没实际恢复过的备份，等于没有备份。&lt;/strong&gt; 备份文件能生成、能列表，不代表真出事时能还原——属主丢了、路径多一层、包在传输中损坏，都是恢复现场才会暴露的问题。建议每套备份流程第一次跑通后，立刻在一个临时卷上做一次完整的恢复演练，把命令和坑都验证一遍；之后每次大改备份脚本，也重复这个动作。演练花十分钟，换的是出事那天不用现学。&lt;/p&gt;
&lt;h2&gt;数据库备份的一致性：别直接拷文件&lt;/h2&gt;
&lt;p&gt;到这里有个必须单独讲清的问题：&lt;strong&gt;对正在运行的数据库，直接打包它的数据卷，得到的备份可能是一个坏档。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;原因不难理解：数据库运行时，数据一部分在磁盘文件里，一部分还在内存和预写日志（WAL）里，文件之间的一致性是靠数据库自己的机制在崩溃恢复时拼回去的。你在任意一个瞬间把文件整包拷走，拷到的是「半截子状态」——运气好，数据库启动时能靠日志回放自愈；运气不好，就是损坏、丢数据或者干脆起不来。文件级热拷贝对普通文件型应用（博客附件、上传目录）问题不大，对数据库是赌博。&lt;/p&gt;
&lt;p&gt;正确做法有两条路：&lt;/p&gt;
&lt;h3&gt;路线一：逻辑导出（推荐，热备）&lt;/h3&gt;
&lt;p&gt;用数据库自带的导出工具，得到的是一致的逻辑备份，服务不用停：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# PostgreSQL：导出为 SQL 文本
docker compose exec db pg_dump -U postgres myapp &amp;gt; ~/backups/mydb-$(date +%F).sql

# MySQL：--single-transaction 保证导出期间一致性且不锁表
docker compose exec db mysqldump -u root -p密码 --single-transaction myapp &amp;gt; ~/backups/mydb-$(date +%F).sql
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;恢复时反过来喂回去：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# PostgreSQL
cat ~/backups/mydb-2026-11-15.sql | docker compose exec -T db psql -U postgres myapp

# MySQL
cat ~/backups/mydb-2026-11-15.sql | docker compose exec -T db mysql -u root -p密码 myapp
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逻辑导出的额外好处：跨版本、跨机器恢复都兼容（卷文件直接拷则不行，老版本的数据文件新版本可能拒绝加载）。&lt;/p&gt;
&lt;h3&gt;路线二：停机冷备（简单粗暴但可靠）&lt;/h3&gt;
&lt;p&gt;能接受短暂停机的个人服务，直接停掉数据库再打包数据卷，文件处于静止状态，一致性天然成立：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose stop db
docker run --rm -v myapp_db_data:/data:ro -v ~/backups:/backup alpine \
  tar czf /backup/db_data-cold-$(date +%F).tar.gz -C /data .
docker compose start db
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;在 Compose 项目里固化成一条命令&lt;/h3&gt;
&lt;p&gt;把逻辑导出写进一个小脚本放项目里（比如 &lt;code&gt;backup.sh&lt;/code&gt;），手动和定时任务都能调：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
# 项目根目录执行：./backup.sh
set -e
mkdir -p ./backups
docker compose exec -T db pg_dump -U postgres myapp &amp;gt; ./backups/mydb-$(date +%F).sql
echo &quot;备份完成：./backups/mydb-$(date +%F).sql&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;docker compose exec&lt;/code&gt; 在脚本里要加 &lt;code&gt;-T&lt;/code&gt;（不分配伪终端），否则在 cron 这类非交互环境里会报错。&lt;/p&gt;
&lt;p&gt;:::warning
还有一个隐蔽坑：&lt;code&gt;pg_dump&lt;/code&gt; 出来的备份只包含数据库内容，&lt;strong&gt;不包含数据库的用户/角色等全局对象&lt;/strong&gt;。要全量兜底可以用 &lt;code&gt;pg_dumpall&lt;/code&gt;（整实例导出）。个人项目多数只用默认用户，知道有这回事即可，真迁移整实例时再换 &lt;code&gt;pg_dumpall&lt;/code&gt;。
:::&lt;/p&gt;
&lt;h2&gt;整站迁移实战：把服务搬到另一台服务器&lt;/h2&gt;
&lt;p&gt;前面几节的技能拼起来，就是完整的整站迁移。场景很常见：VPS 到期换商家、机器配置不够要升级、或者单纯想把几个服务合并到一台。下面以一个典型的 Compose 项目（应用 + PostgreSQL，项目名 &lt;code&gt;myapp&lt;/code&gt;，目录 &lt;code&gt;/opt/myapp&lt;/code&gt;）为例，全程走一遍。&lt;/p&gt;
&lt;p&gt;整体思路一句话：&lt;strong&gt;搬三样东西——项目目录（含配置）、数据卷、镜像清单，数据库单独逻辑导出最稳。&lt;/strong&gt;&lt;/p&gt;
&lt;h3&gt;第一步（旧机）：停服并打包项目目录&lt;/h3&gt;
&lt;p&gt;先停服务，保证打包期间文件不再变化：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/myapp
docker compose down
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意是 &lt;code&gt;down&lt;/code&gt; 不是 &lt;code&gt;down -v&lt;/code&gt;——&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;&lt;code&gt;-v&lt;/code&gt; 会把命名卷一起删掉&lt;/strong&gt;&amp;lt;/span&amp;gt;，迁移现场千万别顺手加上。&lt;/p&gt;
&lt;p&gt;打包整个项目目录（compose 文件、&lt;code&gt;.env&lt;/code&gt;、绑定挂载的配置和数据都在里面）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;tar czf ~/myapp-dir-$(date +%F).tar.gz -C /opt myapp
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;.env&lt;/code&gt; 文件里通常有数据库密码、密钥等敏感信息，它会被打进这个包。传输和存放时按敏感文件对待：只走加密通道（scp/rsync over SSH 本身是加密的）、别丢到任何公共网盘或公开仓库。
:::&lt;/p&gt;
&lt;h3&gt;第二步（旧机）：打包数据卷 + 导出数据库&lt;/h3&gt;
&lt;p&gt;命名卷逐个按前面的标准做法打包：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/backups
docker run --rm -v myapp_db_data:/data:ro -v ~/backups:/backup alpine \
  tar czf /backup/myapp_db_data-$(date +%F).tar.gz -C /data .
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;数据库额外再做一份逻辑导出，双保险（卷包用于整卷还原，SQL 用于卷还原出问题时兜底）。逻辑导出要在停机前做，所以实际操作顺序是：先 &lt;code&gt;pg_dump&lt;/code&gt; → 再 &lt;code&gt;docker compose down&lt;/code&gt; → 再打目录包和卷包：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose exec -T db pg_dump -U postgres myapp &amp;gt; ~/backups/mydb-$(date +%F).sql
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;记录镜像清单，到了新机好核对拉的版本对不对：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose images &amp;gt; ~/backups/images-list.txt
cat ~/backups/images-list.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第三步：传输到新机&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# rsync 断点续传，大文件更稳
rsync -avz -e ssh ~/myapp-dir-*.tar.gz ~/backups/ root@新机IP:~/migrate/

# 或者简单粗暴 scp
scp ~/myapp-dir-*.tar.gz ~/backups/*.tar.gz ~/backups/*.sql root@新机IP:~/migrate/
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第四步（新机）：装 Docker 并放回目录&lt;/h3&gt;
&lt;p&gt;新机先按 &lt;a href=&quot;/posts/linux-docker-compose/&quot;&gt;《如何在Linux部署Docker&amp;amp;Compose》&lt;/a&gt; 装好 Docker，然后：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/migrate &amp;amp;&amp;amp; cd ~/migrate   # 假设安装包都传到了这里

# 放回项目目录
tar xzf myapp-dir-*.tar.gz -C /opt
cd /opt/myapp
ls -la   # 确认 docker-compose.yml 和 .env 都在
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第五步（新机）：逐卷恢复&lt;/h3&gt;
&lt;p&gt;在启动服务&lt;strong&gt;之前&lt;/strong&gt;先建卷并灌数据。注意：卷名必须和 Compose 将要使用的完全一致（带项目名前缀 &lt;code&gt;myapp_db_data&lt;/code&gt;）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker volume create myapp_db_data
docker run --rm -v myapp_db_data:/data -v ~/migrate:/backup alpine \
  tar xzf /backup/myapp_db_data-*.tar.gz -C /data
docker run --rm -v myapp_db_data:/data alpine ls -la /data   # 验一眼
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后告诉 Compose「这个卷是现成的，别自己新建」——在顶层 &lt;code&gt;volumes&lt;/code&gt; 段给它标 &lt;code&gt;external: true&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;volumes:
  db_data:
    external: true
    name: myapp_db_data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;为什么需要这一步、忘了会怎样，排障一节细说。&lt;/p&gt;
&lt;h3&gt;第六步（新机）：启动并按清单验证&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/myapp
docker compose up -d
docker compose ps        # 所有服务都是 Up
docker compose logs -f   # 看一遍启动日志，有没有连不上数据库之类的报错
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;最后逐项过验证清单，三查缺一不可：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;查什么&lt;/th&gt;
&lt;th&gt;怎么查&lt;/th&gt;
&lt;th&gt;通过标准&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;数据&lt;/td&gt;
&lt;td&gt;登录应用后台/查数据库记录数&lt;/td&gt;
&lt;td&gt;文章、用户、历史数据都在且是最新&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;证书&lt;/td&gt;
&lt;td&gt;浏览器打开站点、点小锁看证书&lt;/td&gt;
&lt;td&gt;HTTPS 正常、证书未过期（反代在宿主机或另一台时记得同步改指向）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;DNS&lt;/td&gt;
&lt;td&gt;&lt;code&gt;dig +short 你的域名&lt;/code&gt; 或直接访问&lt;/td&gt;
&lt;td&gt;解析已切到新机 IP 且已生效&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;DNS 切换有个时间差：建议迁移前一天先把域名 TTL 调小（比如 300 秒），切换当天生效快、回滚也快。全部验证通过、观察一两天没问题之后，再去注销旧机——&lt;strong&gt;旧机就是你最后的回滚方案，别急着删&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;回滚预案也要在动手前想好：如果新机验证不过，最快的回滚就是把 DNS 解析切回旧机 IP（旧机在整个过程中只是停了服务、数据原封未动，切回后 &lt;code&gt;docker compose up -d&lt;/code&gt; 即可恢复）。所以迁移的正确心态是：旧机全程只读冻结、新机随便折腾，任何一步不对劲都能全身而退。等新机稳定运行几天、且在新机上已经产生了一份新备份之后，旧机才算完成历史使命。&lt;/p&gt;
&lt;h2&gt;定时自动备份：脚本 + 轮转 + cron&lt;/h2&gt;
&lt;p&gt;手动备份靠不住，迟早会忘。把前面的命令固化成脚本，cron 每天跑，并只保留最近 7 份：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
# /opt/scripts/backup-volumes.sh
# 备份指定命名卷，只保留最近 7 份
set -e

BACKUP_DIR=/root/backups
DATE=$(date +%F)
# 要备份的卷，空格分隔，按自己机器上的真实卷名填
VOLUMES=&quot;myapp_db_data myapp_uploads&quot;

mkdir -p &quot;$BACKUP_DIR&quot;

for vol in $VOLUMES; do
  docker run --rm \
    -v ${vol}:/data:ro \
    -v ${BACKUP_DIR}:/backup \
    alpine \
    tar czf /backup/${vol}-${DATE}.tar.gz -C /data .
  echo &quot;已备份 $vol&quot;
done

# 轮转：删掉 7 天以前的备份包
find &quot;$BACKUP_DIR&quot; -name &quot;*.tar.gz&quot; -mtime +7 -delete
echo &quot;备份全部完成&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;chmod +x /opt/scripts/backup-volumes.sh

# 先手动跑一次，确认能生成包、包能打开
/opt/scripts/backup-volumes.sh
ls -lh /root/backups/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;挂到 cron，每天凌晨 3 点执行、日志留痕：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;0 3 * * * /opt/scripts/backup-volumes.sh &amp;gt;&amp;gt; /var/log/volume-backup.log 2&amp;gt;&amp;amp;1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;脚本里用 &lt;code&gt;-mtime +7 -delete&lt;/code&gt; 做轮转有个前提：备份文件名各不相同（带日期）且目录里只放这类备份包，别把别的重要文件堆在这个目录里。&lt;/p&gt;
&lt;p&gt;还有个运维习惯：每周顺手瞄一眼 &lt;code&gt;/var/log/volume-backup.log&lt;/code&gt; 和备份目录里最新包的日期。定时备份最怕的不是报错，而是&lt;strong&gt;悄悄停摆&lt;/strong&gt;——cron 被误删、磁盘满了、卷名改了，脚本天天失败但没人看日志，等真要恢复时才发现最新备份是三个月前的。确认「昨晚的包在、大小正常」，这个动作只要十秒。&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;备份只存本机等于没完全备份。&lt;/strong&gt;&amp;lt;/span&amp;gt; 磁盘损坏、机器被注销、误操作 &lt;code&gt;rm&lt;/code&gt;，备份和原数据会一起没。脚本跑完后再加一步异地传输，哪怕只是传到另一台 VPS 或者对象存储：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 脚本末尾追加：同步到另一台机器
rsync -avz -e ssh /root/backups/ root@备份机IP:/root/backups-主站/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;原则是至少做到「两台机器、两份拷贝」，重要数据再考虑第三份到对象存储。
:::&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;h3&gt;恢复后服务起不来，日志报 Permission denied&lt;/h3&gt;
&lt;p&gt;九成是属主问题：备份打包或解包时如果没在容器里用 tar 而是手动 cp，或者解包工具没保留属主，文件会变成 root 或错误 uid 所有，应用进程（比如 uid 999 的 postgres）读不了自己的数据目录。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 对比原卷属主：看数据目录里的文件是谁的
docker run --rm -v myapp_db_data:/data alpine ls -ln /data

# 典型修复：把属主改回应用需要的 uid（以 PostgreSQL 的 999 为例）
docker run --rm -v myapp_db_data:/data alpine chown -R 999:999 /data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;根治办法是全程用本文的 tar 流程（tar 默认保留 uid/gid），别混用别的方法搬数据。&lt;/p&gt;
&lt;h3&gt;卷名对不上：Compose 新建了一个空卷，数据「消失」了&lt;/h3&gt;
&lt;p&gt;现象：迁移后服务能起来，但里面是全新空数据；&lt;code&gt;docker volume ls&lt;/code&gt; 里躺着两个长得像的卷。&lt;/p&gt;
&lt;p&gt;原因就是前面说的&lt;strong&gt;项目名前缀&lt;/strong&gt;：你在旧机手工建的卷叫 &lt;code&gt;db_data&lt;/code&gt;，而 Compose 按项目名拼出来的真实卷名是 &lt;code&gt;myapp_db_data&lt;/code&gt;，两者不是一个卷。Compose 找不到自己要的卷，就默默新建了一个空的。&lt;/p&gt;
&lt;p&gt;解法二选一：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 解法一（推荐）：顶层 volumes 段声明用现成的卷
volumes:
  db_data:
    external: true
    name: myapp_db_data     # 写真实卷名
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;# 解法二：建卷时就直接用 Compose 期望的名字
# 即一开始就 docker volume create myapp_db_data 并往里恢复，
# Compose 发现同名卷已存在会直接使用
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;排查时先 &lt;code&gt;docker volume ls&lt;/code&gt; 对一眼名字，能省下大量瞎猜的时间。&lt;/p&gt;
&lt;h3&gt;备份包解开多了一层目录&lt;/h3&gt;
&lt;p&gt;现象：恢复完进卷一看，数据不在 &lt;code&gt;/data&lt;/code&gt; 根下，而是躺在 &lt;code&gt;/data/data/&lt;/code&gt; 里，应用自然读不到。&lt;/p&gt;
&lt;p&gt;原因：打包时写的是 &lt;code&gt;tar czf ... /data&lt;/code&gt;（打了目录本身），包里所有路径都带个 &lt;code&gt;data/&lt;/code&gt; 前缀；解到 &lt;code&gt;/data&lt;/code&gt; 就成了套娃。本文备份命令用的是 &lt;code&gt;-C /data .&lt;/code&gt;（打目录里的&lt;strong&gt;内容&lt;/strong&gt;），从源头避开这个问题。&lt;/p&gt;
&lt;p&gt;如果手上的旧包已经是带目录层的，恢复时用 &lt;code&gt;--strip-components&lt;/code&gt; 削掉一层补救：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run --rm -v myapp_db_data:/data -v ~/backups:/backup alpine \
  tar xzf /backup/旧包.tar.gz -C /data --strip-components 1
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;打包到一半失败：no space left on device&lt;/h3&gt;
&lt;p&gt;备份本质是「读一份、再写一份」，目标磁盘至少要留出比源数据更大的空闲空间（压缩后通常会小不少，但日志、媒体这类已经压缩过的数据几乎压不动，要按原体积预估）。先用 &lt;code&gt;docker system df -v&lt;/code&gt; 确认卷的实际大小，再 &lt;code&gt;df -h&lt;/code&gt; 看备份目录所在磁盘的余量。空间实在紧张时，可以让 tar 直接通过管道交给 gzip 以上的压缩，或者把备份目录挂到另一块盘上，但别把备份打到和源卷同一块快满的盘上自欺欺人。&lt;/p&gt;
&lt;h3&gt;卷删不掉：volume is in use&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;docker volume rm&lt;/code&gt; 报在用，先查是谁在用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker ps -a --filter volume=myapp_db_data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;停掉的容器也算「在用」，把对应容器 &lt;code&gt;docker rm&lt;/code&gt; 后再删卷。确认里面数据真的不要了再动手。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;数据存法三选一：数据库和应用数据用&lt;strong&gt;命名卷&lt;/strong&gt;、配置和常看常改的文件用&lt;strong&gt;绑定挂载&lt;/strong&gt;、临时的用 &lt;strong&gt;tmpfs&lt;/strong&gt;；永远别把重要数据只留在容器可写层；&lt;/li&gt;
&lt;li&gt;命名卷备份恢复的标准姿势是&lt;strong&gt;临时容器 + tar&lt;/strong&gt;：备份时卷只读挂载、打包目录内容（&lt;code&gt;-C /data .&lt;/code&gt;）、文件名带日期，恢复时解到新建的空卷并启动服务验证；&lt;/li&gt;
&lt;li&gt;数据库不要赌文件级热拷贝：能逻辑导出就 &lt;code&gt;pg_dump&lt;/code&gt;/&lt;code&gt;mysqldump&lt;/code&gt;，或者停机做冷备；&lt;/li&gt;
&lt;li&gt;整站迁移搬三样：项目目录（含 &lt;code&gt;.env&lt;/code&gt;）、数据卷、镜像清单，上线后过&lt;strong&gt;数据、证书、DNS&lt;/strong&gt; 三查，旧机留几天再注销；&lt;/li&gt;
&lt;li&gt;备份要自动化：脚本 + cron + 只留最近 7 份轮转，并且&lt;strong&gt;至少再往另一台机器同步一份&lt;/strong&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;把这套流程跑顺，你对这台机器上所有容器都可以做到一句话：随便删，随便搬，反正数据丢不了。&lt;/p&gt;
</content:encoded></item><item><title>Dockerfile 入门：把自己的应用打包成镜像</title><link>https://www.anexns.cloudns.org/posts/dockerfile-guide/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/dockerfile-guide/</guid><description>从零写 Dockerfile：以一个 Python 小服务为主线走完 FROM 到 CMD 的每条指令、多阶段构建瘦身、.dockerignore、层缓存优化、非 root 运行，最后构建并推送自己的镜像。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;前两篇 &lt;a href=&quot;/posts/linux-docker-compose/&quot;&gt;《如何在Linux部署Docker&amp;amp;Compose》&lt;/a&gt; 和自动更新教程用的都是别人发布好的镜像：&lt;code&gt;nginx&lt;/code&gt;、&lt;code&gt;redis&lt;/code&gt;、Watchtower……但你自己写的脚本和小服务呢？总不能每次部署都先装环境、再拷代码、再手动启动。把自己的应用打包成镜像，这件事靠的就是 Dockerfile。这篇以一个极简的 Python HTTP 服务为主线，从第一版能跑的 Dockerfile 开始，一步步优化到生产可用：构建缓存、镜像瘦身、多阶段构建、非 root 运行，最后打标签推送到 Docker Hub。看完你应该能独立给任何一个小项目写出合格的 Dockerfile。&lt;/p&gt;
&lt;h2&gt;先搞清楚概念：镜像、Dockerfile、构建上下文&lt;/h2&gt;
&lt;p&gt;**镜像（Image）**是容器的「安装包」：里面装着应用代码、运行时、依赖库和启动命令，是只读的。容器是镜像跑起来之后的进程。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Dockerfile&lt;/strong&gt; 是制作镜像的「菜谱」：一个纯文本文件，一行一条指令，描述从哪个基础镜像开始、往里面放什么、装什么、最后怎么启动。&lt;code&gt;docker build&lt;/code&gt; 命令照着菜谱一层层执行，产出镜像。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;构建上下文（Build Context）&lt;strong&gt;是最容易被新手忽略的概念：执行 &lt;code&gt;docker build .&lt;/code&gt; 时，最后那个 &lt;code&gt;.&lt;/code&gt; 指的目录就是构建上下文，Docker 会先把&lt;/strong&gt;整个目录打包发送给 Docker 守护进程&lt;/strong&gt;，Dockerfile 里的 &lt;code&gt;COPY&lt;/code&gt; 只能复制这个目录里的文件。两个直接后果：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;不要在 home 目录、盘根目录这种地方执行 &lt;code&gt;docker build .&lt;/code&gt;，几个 GB 的无关文件会被一起打包发送，构建慢到怀疑人生；&lt;/li&gt;
&lt;li&gt;源码目录里混着的 &lt;code&gt;.git&lt;/code&gt;、&lt;code&gt;node_modules&lt;/code&gt;、虚拟环境、日志文件都会进上下文，这正是 &lt;code&gt;.dockerignore&lt;/code&gt; 要解决的问题，后文专门讲。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;层（Layer）&lt;/strong&gt;：Dockerfile 里每条会修改文件系统的指令（&lt;code&gt;FROM&lt;/code&gt;、&lt;code&gt;COPY&lt;/code&gt;、&lt;code&gt;RUN&lt;/code&gt; 等）都会生成一个只读层，镜像就是一层层叠起来的。层会被缓存——这是理解构建速度的关键，后文优化部分全在围绕它做文章。&lt;/p&gt;
&lt;p&gt;再补充两个和构建体验直接相关的点。其一，现在的 Docker 默认使用 &lt;strong&gt;BuildKit&lt;/strong&gt; 构建引擎（&lt;code&gt;docker build&lt;/code&gt; 背后就是它），它的输出会把每个步骤编号、并行处理互不依赖的阶段，还原生支持后文提到的多阶段构建和构建期密钥挂载。你在构建日志里看到的步骤编号和 &lt;code&gt;CACHED&lt;/code&gt; 标记，都来自它。其二，Dockerfile 的文件名默认就叫 &lt;code&gt;Dockerfile&lt;/code&gt;（没有扩展名，首字母大写），放在项目根目录；一个项目需要多个镜像时可以用 &lt;code&gt;-f&lt;/code&gt; 指定别的文件，比如 &lt;code&gt;docker build -f Dockerfile.worker -t myapp-worker:1.0 .&lt;/code&gt;，但没有特殊需求时保持默认名，工具链和同事都能一眼找到它。&lt;/p&gt;
&lt;h2&gt;主线例子：一个极简 Python 服务&lt;/h2&gt;
&lt;p&gt;先写应用本身。用 Flask 写一个只有两个接口的小服务，保存为 &lt;code&gt;app.py&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;from flask import Flask, jsonify
import os

app = Flask(__name__)


@app.route(&quot;/&quot;)
def index():
    return jsonify(message=&quot;hello from my image&quot;, env=os.environ.get(&quot;APP_ENV&quot;, &quot;prod&quot;))


@app.route(&quot;/health&quot;)
def health():
    return jsonify(status=&quot;ok&quot;)


if __name__ == &quot;__main__&quot;:
    app.run(host=&quot;0.0.0.0&quot;, port=8000)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;依赖清单 &lt;code&gt;requirements.txt&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;flask==3.0.3
gunicorn==22.1.0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意两个细节：一是 &lt;code&gt;app.run&lt;/code&gt; 监听 &lt;code&gt;0.0.0.0&lt;/code&gt; 而不是默认的 &lt;code&gt;127.0.0.1&lt;/code&gt;，容器里的服务只听本机回环的话，宿主机端口映射进来也连不上，这是新手最常见的坑之一；二是依赖&lt;strong&gt;钉死版本号&lt;/strong&gt;，保证半年后重新构建出来的镜像和今天的一致。&lt;/p&gt;
&lt;p&gt;生产环境不用 Flask 自带的开发服务器（&lt;code&gt;app.run&lt;/code&gt;），用 gunicorn 承载，所以它也在依赖清单里。&lt;code&gt;app.py&lt;/code&gt; 里的 &lt;code&gt;app.run&lt;/code&gt; 只留作本地直接运行调试。&lt;/p&gt;
&lt;p&gt;项目目录结构：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;myapp/
├── app.py
├── requirements.txt
└── Dockerfile
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;初版 Dockerfile：先跑起来再说&lt;/h2&gt;
&lt;p&gt;第一版怎么简单怎么来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;FROM python:3.12
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
EXPOSE 8000
CMD [&quot;gunicorn&quot;, &quot;-b&quot;, &quot;0.0.0.0:8000&quot;, &quot;app:app&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;构建并运行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd myapp
docker build -t myapp:0.1 .
docker run -d --name myapp -p 8000:8000 myapp:0.1
curl http://localhost:8000/
curl http://localhost:8000/health
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个接口都返回 JSON 就说明镜像做对了。&lt;code&gt;docker build&lt;/code&gt; 的 &lt;code&gt;-t&lt;/code&gt; 是给镜像起名字和标签（&lt;code&gt;名字:标签&lt;/code&gt;），结尾的 &lt;code&gt;.&lt;/code&gt; 是构建上下文路径，一个都不能少。&lt;/p&gt;
&lt;p&gt;这一版能跑，但毛病不少：镜像有 1 GB 上下（完整的 &lt;code&gt;python:3.12&lt;/code&gt; 带着全套编译工具）、改一行代码就要把依赖重装一遍、容器里是 root 在跑服务。下面逐条把指令讲透，边讲边改。&lt;/p&gt;
&lt;h2&gt;逐条讲指令&lt;/h2&gt;
&lt;h3&gt;FROM：选基础镜像&lt;/h3&gt;
&lt;p&gt;每个 Dockerfile 的第一条指令必须是 &lt;code&gt;FROM&lt;/code&gt;，指定基础镜像。选镜像有三条经验：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;优先官方镜像&lt;/strong&gt;：Docker Hub 上带「Official Image」标记的 &lt;code&gt;python&lt;/code&gt;、&lt;code&gt;node&lt;/code&gt;、&lt;code&gt;golang&lt;/code&gt; 等，维护和安全更新有保障；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;版本号钉到小版本&lt;/strong&gt;：写 &lt;code&gt;python:3.12.4&lt;/code&gt; 而不是 &lt;code&gt;python:3&lt;/code&gt; 甚至不带标签（默认 &lt;code&gt;latest&lt;/code&gt;），避免哪天上游更新把你的构建弄坏；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;体积和兼容性之间权衡变体&lt;/strong&gt;：同一个镜像通常有几种变体：&lt;/li&gt;
&lt;/ol&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;变体&lt;/th&gt;
&lt;th&gt;基础&lt;/th&gt;
&lt;th&gt;体积&lt;/th&gt;
&lt;th&gt;特点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;完整版（如 &lt;code&gt;python:3.12&lt;/code&gt;）&lt;/td&gt;
&lt;td&gt;Debian 全套&lt;/td&gt;
&lt;td&gt;约 1 GB&lt;/td&gt;
&lt;td&gt;工具齐全，构建和调试方便&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;slim&lt;/code&gt;（如 &lt;code&gt;python:3.12-slim&lt;/code&gt;）&lt;/td&gt;
&lt;td&gt;精简 Debian&lt;/td&gt;
&lt;td&gt;约 120–150 MB&lt;/td&gt;
&lt;td&gt;砍掉文档和多余工具，保留 glibc，兼容性好&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;alpine&lt;/code&gt;（如 &lt;code&gt;python:3.12-alpine&lt;/code&gt;）&lt;/td&gt;
&lt;td&gt;Alpine Linux&lt;/td&gt;
&lt;td&gt;约 50–70 MB&lt;/td&gt;
&lt;td&gt;最小，但用 musl libc 而不是 glibc&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
&lt;code&gt;alpine&lt;/code&gt; 虽然最小，但它用的 musl libc 和主流 glibc 不完全兼容：很多 Python 预编译包（wheel）是按 glibc 打的，在 alpine 上装不上、被迫现场编译，既慢又容易失败；DNS、时区等行为也有细微差异。除非你很清楚自己在做什么，Python/Node 这类服务优先选 &lt;code&gt;slim&lt;/code&gt;，省下的体积用多阶段构建去抠，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;别在 libc 上冒险&amp;lt;/span&amp;gt;。
:::&lt;/p&gt;
&lt;p&gt;本例把基础镜像换成 &lt;code&gt;python:3.12-slim&lt;/code&gt;，镜像立刻从约 1 GB 降到 200 MB 以内。&lt;/p&gt;
&lt;h3&gt;WORKDIR：工作目录&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;WORKDIR /app&lt;/code&gt; 指定后续指令的工作目录，不存在会自动创建。之后所有相对路径都以它为基准。它相当于每条指令前都先 &lt;code&gt;cd /app&lt;/code&gt;，但比在 &lt;code&gt;RUN&lt;/code&gt; 里写 &lt;code&gt;cd&lt;/code&gt; 干净得多。养成习惯：Dockerfile 开头就设 &lt;code&gt;WORKDIR&lt;/code&gt;，后面一律用相对路径。&lt;/p&gt;
&lt;h3&gt;COPY 与 ADD：往镜像里放文件&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;COPY . .&lt;/code&gt; 把构建上下文的全部内容复制到当前工作目录。&lt;code&gt;COPY&lt;/code&gt; 还支持指定来源和目标：&lt;code&gt;COPY app.py /app/&lt;/code&gt;、&lt;code&gt;COPY src/ /app/src/&lt;/code&gt;，以及多阶段构建里要用的 &lt;code&gt;--from&lt;/code&gt; 和改属主的 &lt;code&gt;--chown&lt;/code&gt;（后文都会用到）。&lt;/p&gt;
&lt;p&gt;另一个长得像的指令是 &lt;code&gt;ADD&lt;/code&gt;，区别如下：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;COPY&lt;/th&gt;
&lt;th&gt;ADD&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;普通文件/目录复制&lt;/td&gt;
&lt;td&gt;✅&lt;/td&gt;
&lt;td&gt;✅&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本地 tar 包自动解压&lt;/td&gt;
&lt;td&gt;❌&lt;/td&gt;
&lt;td&gt;✅&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;从远程 URL 下载文件&lt;/td&gt;
&lt;td&gt;❌&lt;/td&gt;
&lt;td&gt;✅（且不解压）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;结论：&lt;strong&gt;无脑用 &lt;code&gt;COPY&lt;/code&gt;&lt;/strong&gt;。&lt;code&gt;ADD&lt;/code&gt; 的自动解压和远程下载都是隐式行为，容易出意外（比如你只想拷一个 tar 包进去，它却给你解开了）；真需要下载远程文件，用 &lt;code&gt;RUN curl&lt;/code&gt; 写得明明白白。官方最佳实践也是优先 &lt;code&gt;COPY&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;RUN：构建时执行命令&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;RUN pip install -r requirements.txt&lt;/code&gt; 在&lt;strong&gt;构建阶段&lt;/strong&gt;执行，产物固化进这一层。常用来装依赖、编译代码、清理缓存。注意它和 &lt;code&gt;CMD&lt;/code&gt; 的根本区别：&lt;code&gt;RUN&lt;/code&gt; 是做镜像时跑的，镜像做好就不再执行；&lt;code&gt;CMD&lt;/code&gt; 是容器启动时跑的。&lt;/p&gt;
&lt;p&gt;一个常用技巧：装完依赖顺手清缓存，减小层体积。比如 pip：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;RUN pip install --no-cache-dir -r requirements.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--no-cache-dir&lt;/code&gt; 不把下载缓存留在镜像里，省几十 MB。apt 系则是 &lt;code&gt;RUN apt-get update &amp;amp;&amp;amp; apt-get install -y xxx &amp;amp;&amp;amp; rm -rf /var/lib/apt/lists/*&lt;/code&gt;，而且要写在&lt;strong&gt;同一条&lt;/strong&gt; &lt;code&gt;RUN&lt;/code&gt; 里——原因见下文层缓存与体积部分。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;RUN&lt;/code&gt; 也有两种写法：shell 形式（&lt;code&gt;RUN pip install flask&lt;/code&gt;，实际经 &lt;code&gt;/bin/sh -c&lt;/code&gt; 执行，可以用管道、变量展开）和 exec 形式（&lt;code&gt;RUN [&quot;pip&quot;, &quot;install&quot;, &quot;flask&quot;]&lt;/code&gt;，直接执行、不经过 shell）。构建命令通常需要 shell 的组合能力，所以 &lt;code&gt;RUN&lt;/code&gt; 以 shell 形式为主；但如果基础镜像精简到连 shell 都没有（比如 &lt;code&gt;scratch&lt;/code&gt;），就只能用 exec 形式，这一点在排查「exec: &quot;/bin/sh&quot;: stat /bin/sh: no such file or directory」这类报错时会用到。&lt;/p&gt;
&lt;p&gt;另外记住：连续多条相关的 &lt;code&gt;RUN&lt;/code&gt; 可以用 &lt;code&gt;&amp;amp;&amp;amp;&lt;/code&gt; 合并成一条，减少层数。不过也别走向另一个极端，把整个 Dockerfile 塞进一条巨型 &lt;code&gt;RUN&lt;/code&gt;——那样任何一小处改动都会让整层缓存失效，分层的度要服从后文的缓存原则。&lt;/p&gt;
&lt;h3&gt;ENV 与 ARG：两种变量&lt;/h3&gt;
&lt;p&gt;两者都能在 Dockerfile 里定义变量，区别在作用阶段：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;ARG&lt;/th&gt;
&lt;th&gt;ENV&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;作用阶段&lt;/td&gt;
&lt;td&gt;只在构建时&lt;/td&gt;
&lt;td&gt;构建时 + 容器运行时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;构建时赋值&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker build --build-arg VERSION=1.2&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;——&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;运行时可见&lt;/td&gt;
&lt;td&gt;❌（除非再转给 ENV）&lt;/td&gt;
&lt;td&gt;✅（&lt;code&gt;docker exec 容器 env&lt;/code&gt; 能看到）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;典型用途&lt;/td&gt;
&lt;td&gt;换基础镜像版本、构建开关、代理地址&lt;/td&gt;
&lt;td&gt;时区、语言、应用配置默认值&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;例子：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ARG PYTHON_VERSION=3.12
FROM python:${PYTHON_VERSION}-slim
ENV APP_ENV=prod \
    TZ=Asia/Shanghai \
    PYTHONUNBUFFERED=1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;ARG&lt;/code&gt; 甚至能用在 &lt;code&gt;FROM&lt;/code&gt; 之前（像上面这样），构建时一条 &lt;code&gt;--build-arg PYTHON_VERSION=3.11&lt;/code&gt; 就能换基础版本。&lt;code&gt;ENV&lt;/code&gt; 里 &lt;code&gt;PYTHONUNBUFFERED=1&lt;/code&gt; 值得一记：让 Python 日志不缓冲、直接输出，不然 &lt;code&gt;docker logs&lt;/code&gt; 里半天看不到日志。多个 &lt;code&gt;ENV&lt;/code&gt; 写在一条指令里用反斜杠续行，能少生几层。&lt;/p&gt;
&lt;p&gt;:::warning
不要用 &lt;code&gt;ARG&lt;/code&gt; 或 &lt;code&gt;ENV&lt;/code&gt; 放密码、Token 这类秘密：&lt;code&gt;ARG&lt;/code&gt; 会留在构建历史里，&lt;code&gt;ENV&lt;/code&gt; 在 &lt;code&gt;docker inspect&lt;/code&gt; 里一览无余。构建期秘密用 BuildKit 的 &lt;code&gt;--secret&lt;/code&gt; 挂载，运行期秘密用环境变量注入或密钥管理服务，别写进 Dockerfile。
:::&lt;/p&gt;
&lt;h3&gt;EXPOSE：声明端口&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;EXPOSE 8000&lt;/code&gt; 只是&lt;strong&gt;声明&lt;/strong&gt;这个容器对外提供服务的端口，起到文档和提示作用（&lt;code&gt;docker ps&lt;/code&gt;、自动生成映射时能看到）。它不会真的把端口发布到宿主机——真正发布还是靠 &lt;code&gt;docker run -p 8000:8000&lt;/code&gt; 或 Compose 的 &lt;code&gt;ports&lt;/code&gt;。写上它是个好习惯，别人接手镜像时一眼就知道该映射哪个端口。&lt;/p&gt;
&lt;h3&gt;USER：切换运行用户&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;USER appuser&lt;/code&gt; 指定之后 &lt;code&gt;RUN&lt;/code&gt;、&lt;code&gt;CMD&lt;/code&gt; 用哪个用户执行。默认是 root，非 root 运行的完整做法在后文专门一节，这里先记住有这条指令。&lt;/p&gt;
&lt;h3&gt;HEALTHCHECK：健康检查（简述）&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD python -c &quot;import urllib.request; urllib.request.urlopen(&apos;http://127.0.0.1:8000/health&apos;)&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它让 Docker 定时在容器内执行一条命令，成功返回 0、失败返回非 0，连续失败到 &lt;code&gt;--retries&lt;/code&gt; 次就把容器标记为 &lt;code&gt;unhealthy&lt;/code&gt;（&lt;code&gt;docker ps&lt;/code&gt; 的 STATUS 里能看到）。前面写的 &lt;code&gt;/health&lt;/code&gt; 接口就是给它用的。注意它只负责&lt;strong&gt;标记&lt;/strong&gt;状态，不会自动重启容器；要自动处理得靠 Compose 的 &lt;code&gt;restart&lt;/code&gt; 策略、Swarm/Kubernetes 的探针或外部监控。slim 镜像里通常没有 curl，所以示例用 Python 标准库发请求。&lt;/p&gt;
&lt;p&gt;还有两个参数值得知道：&lt;code&gt;--start-period&lt;/code&gt; 给应用留启动宽限期（比如 40 秒），宽限期内检查失败不计数，适合启动慢的服务；检查命令也可以换成任何容器内能跑的命令，数据库类镜像常用自带工具探活，比如 PostgreSQL 用 &lt;code&gt;pg_isready&lt;/code&gt;、Redis 用 &lt;code&gt;redis-cli ping&lt;/code&gt;。原则是探活命令要轻、要快，别让健康检查本身变成负担。&lt;/p&gt;
&lt;h3&gt;CMD 与 ENTRYPOINT：容器启动命令&lt;/h3&gt;
&lt;p&gt;这是最容易混的一对。容器启动时真正执行的命令 = &lt;code&gt;ENTRYPOINT&lt;/code&gt; + &lt;code&gt;CMD&lt;/code&gt; 拼起来的结果：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;ENTRYPOINT&lt;/th&gt;
&lt;th&gt;CMD&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;定位&lt;/td&gt;
&lt;td&gt;固定的主命令&lt;/td&gt;
&lt;td&gt;默认参数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker run 镜像 额外参数&lt;/code&gt; 时&lt;/td&gt;
&lt;td&gt;不变&lt;/td&gt;
&lt;td&gt;被额外参数整体替换&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;典型写法&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ENTRYPOINT [&quot;gunicorn&quot;]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;CMD [&quot;-b&quot;, &quot;0.0.0.0:8000&quot;, &quot;app:app&quot;]&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;配合起来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ENTRYPOINT [&quot;gunicorn&quot;]
CMD [&quot;-b&quot;, &quot;0.0.0.0:8000&quot;, &quot;app:app&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;平时 &lt;code&gt;docker run myapp:1.0&lt;/code&gt; 跑的就是 &lt;code&gt;gunicorn -b 0.0.0.0:8000 app:app&lt;/code&gt;；临时想换端口 &lt;code&gt;docker run myapp:1.0 -b 0.0.0.0:9000 app:app&lt;/code&gt;，只覆盖 &lt;code&gt;CMD&lt;/code&gt; 部分，主程序不变。如果只写 &lt;code&gt;CMD&lt;/code&gt; 不写 &lt;code&gt;ENTRYPOINT&lt;/code&gt;（初版就是这样），整条命令都能被 &lt;code&gt;docker run 镜像 /bin/bash&lt;/code&gt; 顶掉，适合通用镜像；如果镜像就是为单一服务而做，用 ENTRYPOINT 锁住主程序更稳妥。&lt;/p&gt;
&lt;p&gt;还有一个写法区别：&lt;strong&gt;exec 形式&lt;/strong&gt;（JSON 数组，&lt;code&gt;CMD [&quot;gunicorn&quot;, &quot;...&quot;]&lt;/code&gt;）直接执行程序、不经过 shell，程序就是容器里的 1 号进程，能正确收到 &lt;code&gt;docker stop&lt;/code&gt; 发的 SIGTERM 信号优雅退出；&lt;strong&gt;shell 形式&lt;/strong&gt;（&lt;code&gt;CMD gunicorn ...&lt;/code&gt;）会套一层 &lt;code&gt;/bin/sh -c&lt;/code&gt;，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;信号被 shell 吃掉&amp;lt;/span&amp;gt;，停容器时经常要等 10 秒超时被强杀。除非你需要 shell 的变量展开、管道等特性，一律用 exec 形式。&lt;/p&gt;
&lt;h2&gt;层缓存优化：改代码别重装依赖&lt;/h2&gt;
&lt;p&gt;回到初版的问题：为什么改一行 &lt;code&gt;app.py&lt;/code&gt;，&lt;code&gt;pip install&lt;/code&gt; 要全部重跑？因为构建缓存是&lt;strong&gt;按层&lt;/strong&gt;失效的：&lt;code&gt;COPY . .&lt;/code&gt; 这一层里任何文件变了（包括 app.py），这一层及其&lt;strong&gt;之后所有层&lt;/strong&gt;的缓存全部作废，排在它后面的 &lt;code&gt;RUN pip install&lt;/code&gt; 自然要重新执行。&lt;/p&gt;
&lt;p&gt;解法是把「变得少的」和「变得勤的」拆开：依赖清单很少变，源码天天变，那就先只拷依赖清单、装依赖，最后才拷源码：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD [&quot;gunicorn&quot;, &quot;-b&quot;, &quot;0.0.0.0:8000&quot;, &quot;app:app&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;对比效果立竿见影：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;初版（先 COPY 全部）&lt;/th&gt;
&lt;th&gt;优化版（先 COPY 依赖清单）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;首次构建&lt;/td&gt;
&lt;td&gt;全量，慢&lt;/td&gt;
&lt;td&gt;全量，慢&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;只改 app.py&lt;/td&gt;
&lt;td&gt;pip 全部重装，几十秒到几分钟&lt;/td&gt;
&lt;td&gt;pip 层直接命中缓存，只重拷源码，几秒&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;改 requirements.txt&lt;/td&gt;
&lt;td&gt;全量重装&lt;/td&gt;
&lt;td&gt;依赖层失效重装（应该的），其余照旧&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;记住这条通用原则：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;指令按「变化频率从低到高」排列&lt;/strong&gt;&amp;lt;/span&amp;gt;——基础镜像、系统包、依赖清单、依赖安装、源码，越靠前越稳定。这也是为什么经验丰富的 Dockerfile 都是这个套路。&lt;/p&gt;
&lt;p&gt;另外验证缓存时可以看构建输出：命中缓存的步骤会标 &lt;code&gt;CACHED&lt;/code&gt;。改一行 app.py 重新 &lt;code&gt;docker build&lt;/code&gt;，确认只有最后两三层在重跑，优化就生效了。&lt;/p&gt;
&lt;p&gt;还有一个体积相关的层常识：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;删除文件要在同一层里删&lt;/strong&gt;&amp;lt;/span&amp;gt;。镜像的层是只读叠加的，你在下一层 &lt;code&gt;RUN rm&lt;/code&gt; 删掉上一层装的东西，只是做了个「遮罩」，文件本体还躺在下层里，镜像一点没小。所以 apt 清列表、pip 不留缓存都要和安装写进同一条 &lt;code&gt;RUN&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;.dockerignore：别把垃圾打包进上下文&lt;/h2&gt;
&lt;p&gt;在项目根目录建 &lt;code&gt;.dockerignore&lt;/code&gt;，语法和 &lt;code&gt;.gitignore&lt;/code&gt; 一样，列出的文件在构建时&lt;strong&gt;既不发送给守护进程、也 COPY 不到&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;.git
__pycache__
*.pyc
.venv
venv
.env
*.log
.pytest_cache
Dockerfile
.dockerignore
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它的重要性有三层：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;构建速度&lt;/strong&gt;：上下文从几百 MB（带着 .git 和虚拟环境）瘦到几 MB，发送和 &lt;code&gt;COPY&lt;/code&gt; 都快得多；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;缓存准确&lt;/strong&gt;：不相干的文件（日志、缓存目录）变动不会让 &lt;code&gt;COPY . .&lt;/code&gt; 层失效，白白触发重构建；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;安全&lt;/strong&gt;：&lt;code&gt;.env&lt;/code&gt; 里常有数据库密码、Token，不写进 ignore 的话 &lt;code&gt;COPY . .&lt;/code&gt; 就把它们焊死在镜像里，谁拿到镜像谁就能翻出来——这是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;真实发生过很多次的泄露方式&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;每写一个新项目，先建 &lt;code&gt;.dockerignore&lt;/code&gt; 再写 Dockerfile。&lt;/p&gt;
&lt;p&gt;再细讲三条写法规则，避免踩坑：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;规则&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;路径相对于&lt;strong&gt;构建上下文根目录&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;写 &lt;code&gt;node_modules&lt;/code&gt; 只匹配根目录下的同名目录，写 &lt;code&gt;**/node_modules&lt;/code&gt; 才匹配任意层级&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Dockerfile&lt;/code&gt; 本身通常也写进 ignore&lt;/td&gt;
&lt;td&gt;它会被单独读取用于构建、不需要再被 &lt;code&gt;COPY&lt;/code&gt; 进镜像，但注意：如果你的构建过程需要在镜像里读取 Dockerfile（极少见），就不要排它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;排除后又想放行个别文件可以用 &lt;code&gt;!&lt;/code&gt; 取反&lt;/td&gt;
&lt;td&gt;比如先排 &lt;code&gt;*.md&lt;/code&gt; 再用 &lt;code&gt;!README.md&lt;/code&gt; 放行单个文件&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;还有一种常见误会要澄清：&lt;code&gt;.dockerignore&lt;/code&gt; 只影响&lt;strong&gt;构建时发送的上下文&lt;/strong&gt;，镜像里已经通过其他途径装进去的东西不受它管，它不是运行时文件过滤器。&lt;/p&gt;
&lt;h2&gt;多阶段构建：从几百 MB 瘦到几十 MB&lt;/h2&gt;
&lt;p&gt;有些应用构建时需要一整套重型工具链（编译器、开发头文件、Node 依赖），但运行时只需要编译产物。把工具链也塞进最终镜像，体积爆炸且攻击面变大。&lt;strong&gt;多阶段构建&lt;/strong&gt;的做法是：在一个 Dockerfile 里写多个 &lt;code&gt;FROM&lt;/code&gt;，前面的阶段负责构建，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;最后一个阶段只从前面拷产物&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;以 Go 服务为例（Go 编译出单个二进制，最能体现效果）。源码 &lt;code&gt;main.go&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;package main

import (
	&quot;fmt&quot;
	&quot;net/http&quot;
)

func main() {
	http.HandleFunc(&quot;/&quot;, func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, &quot;hello from go&quot;)
	})
	http.ListenAndServe(&quot;:8080&quot;, nil)
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两阶段 Dockerfile：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# ---------- 构建阶段 ----------
FROM golang:1.22 AS builder
WORKDIR /src
COPY go.mod ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/server .

# ---------- 运行阶段 ----------
FROM alpine:3.20
WORKDIR /app
COPY --from=builder /out/server .
EXPOSE 8080
CMD [&quot;./server&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拆解关键点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;FROM golang:1.22 AS builder&lt;/code&gt; 给第一阶段起名 &lt;code&gt;builder&lt;/code&gt;，这个阶段的镜像约 800 MB，装着完整 Go 工具链，但它只是中间产物，不会发布；&lt;/li&gt;
&lt;li&gt;最后阶段从只有约 7 MB 的 &lt;code&gt;alpine&lt;/code&gt; 重新开始，&lt;code&gt;COPY --from=builder /out/server .&lt;/code&gt; 只把编译好的二进制拷过来；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;CGO_ENABLED=0&lt;/code&gt; 编译出纯静态二进制，不依赖 glibc，所以能在 alpine（musl）甚至 &lt;code&gt;scratch&lt;/code&gt;（空镜像）里跑。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;最终镜像 = alpine 底 + 一个十几 MB 的二进制，&lt;strong&gt;总共不到 30 MB&lt;/strong&gt;，而单阶段直接用 &lt;code&gt;golang&lt;/code&gt; 镜像跑会是 800 MB 以上。前端项目同理：第一阶段用 &lt;code&gt;node&lt;/code&gt; 镜像 &lt;code&gt;npm run build&lt;/code&gt;，最终阶段用 &lt;code&gt;nginx:alpine&lt;/code&gt; 只拷 &lt;code&gt;dist&lt;/code&gt; 目录，几百 MB 的 &lt;code&gt;node_modules&lt;/code&gt; 一点都不带走。&lt;/p&gt;
&lt;p&gt;多阶段构建里层缓存的原则同样适用：例子中先 &lt;code&gt;COPY go.mod&lt;/code&gt; 并 &lt;code&gt;go mod download&lt;/code&gt;，再 &lt;code&gt;COPY . .&lt;/code&gt; 编译，改源码不会重下依赖。&lt;/p&gt;
&lt;p&gt;前端项目的两阶段写法也一并给出，套路完全相同——第一阶段负责「生产」，第二阶段只拿产物去「营业」：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# ---------- 构建阶段 ----------
FROM node:20-slim AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

# ---------- 运行阶段 ----------
FROM nginx:1.27-alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第一阶段里装着完整的 Node 环境和几百 MB 的 &lt;code&gt;node_modules&lt;/code&gt;，最终镜像却只有 Nginx alpine 加一份静态文件，通常不到 50 MB。这里还顺带用了缓存原则：先拷 &lt;code&gt;package.json&lt;/code&gt; 和锁文件装依赖，再拷源码构建，改页面代码不会触发重新装包。注意 &lt;code&gt;npm ci&lt;/code&gt; 是按锁文件精确安装，比 &lt;code&gt;npm install&lt;/code&gt; 更适合构建场景，结果可复现。&lt;/p&gt;
&lt;h2&gt;非 root 运行：给服务一个普通用户&lt;/h2&gt;
&lt;p&gt;容器里默认 root 跑服务，意味着一旦应用被打穿，攻击者拿到的就是容器内的最高权限，再叠加内核或配置问题时风险更大。给应用建个普通用户只需要三步，写进 Dockerfile：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;FROM python:3.12-slim
WORKDIR /app

RUN groupadd -r appuser &amp;amp;&amp;amp; useradd -r -g appuser appuser

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY --chown=appuser:appuser . .

USER appuser
EXPOSE 8000
CMD [&quot;gunicorn&quot;, &quot;-b&quot;, &quot;0.0.0.0:8000&quot;, &quot;app:app&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;用户要在 &lt;code&gt;COPY&lt;/code&gt; 和 &lt;code&gt;USER&lt;/code&gt; 之前创建好（Debian 系用 &lt;code&gt;groupadd/useradd&lt;/code&gt;，alpine 是 &lt;code&gt;addgroup/adduser&lt;/code&gt;）；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;COPY --chown=appuser:appuser&lt;/code&gt; 在复制时直接把文件属主设成应用用户。否则文件全是 root 的，&lt;code&gt;USER&lt;/code&gt; 切过去之后应用想写日志、写临时文件会 permission denied。不加 &lt;code&gt;--chown&lt;/code&gt; 就得额外 &lt;code&gt;RUN chown -R&lt;/code&gt;，那会再复制一份文件数据，白白多一层体积；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;USER&lt;/code&gt; 写在 &lt;code&gt;CMD&lt;/code&gt; 之前，它决定运行时的身份；它之前的 &lt;code&gt;RUN pip install&lt;/code&gt; 仍然是 root 执行，装系统级依赖不受影响；&lt;/li&gt;
&lt;li&gt;普通用户不能监听 1024 以下的特权端口，所以容器内服务用 8000、8080 这类高位端口，再用 &lt;code&gt;-p 80:8000&lt;/code&gt; 映射出去，正好和我们的例子一致。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;改完后 &lt;code&gt;docker exec myapp whoami&lt;/code&gt; 应该输出 &lt;code&gt;appuser&lt;/code&gt;，验证生效。&lt;/p&gt;
&lt;h2&gt;给镜像打标签与推送&lt;/h2&gt;
&lt;h3&gt;标签规范：别只用 latest&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;latest&lt;/code&gt; 只是个默认标签，不代表「最新」，更不记录版本。出了问题想回滚，你根本分不清哪个是上周的版本。实用的标签规范是&lt;strong&gt;语义化版本 + 构建信息&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker build -t myapp:1.2.0 .
docker tag myapp:1.2.0 myapp:1.2
docker tag myapp:1.2.0 myapp:latest
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;同一个镜像可以有多个标签：&lt;code&gt;1.2.0&lt;/code&gt; 精确锁定版本（部署、回滚都用它），&lt;code&gt;1.2&lt;/code&gt; 和 &lt;code&gt;latest&lt;/code&gt; 作为浮动别名。CI 里还常见把 Git 短哈希打进标签（如 &lt;code&gt;1.2.0-a1b2c3d&lt;/code&gt;），能精确对应到哪次提交。&lt;/p&gt;
&lt;h3&gt;推送到 Docker Hub&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;在 hub.docker.com 注册账号（用户名假设为 &lt;code&gt;anexns&lt;/code&gt;）；&lt;/li&gt;
&lt;li&gt;本地登录：&lt;code&gt;docker login&lt;/code&gt;，输入用户名和密码（建议在账号设置里生成 Access Token 用它代替密码）；&lt;/li&gt;
&lt;li&gt;镜像名必须带上你的用户名前缀才能推送，重新打标签：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;docker tag myapp:1.2.0 anexns/myapp:1.2.0
docker push anexns/myapp:1.2.0
&lt;/code&gt;&lt;/pre&gt;
&lt;ol&gt;
&lt;li&gt;别人拉取就是 &lt;code&gt;docker pull anexns/myapp:1.2.0&lt;/code&gt;。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;推送只上传本地没有的层，基础层（如 python slim）官方已有，不会重复传，所以实际上传量不大。私有镜像在 Hub 上把仓库设为 Private 即可；团队内部也可以自建 Registry 或用各云厂商的镜像仓库服务，&lt;code&gt;tag&lt;/code&gt;/&lt;code&gt;push&lt;/code&gt; 的用法完全一样，只是把前缀换成仓库地址。&lt;/p&gt;
&lt;p&gt;两个推送环节的常见疑问：其一，&lt;code&gt;docker login&lt;/code&gt; 的凭据会保存在本机的 &lt;code&gt;~/.docker/config.json&lt;/code&gt; 里（默认是明文 base64，长期使用的机器建议配置凭据助手或至少保护好这个文件）；其二，推送时报 &lt;code&gt;denied: requested access to the resource is denied&lt;/code&gt;，九成是镜像名没带对用户名前缀、或者没登录、或者仓库名拼错，按「先 login、再 tag 成 &lt;code&gt;用户名/镜像名:标签&lt;/code&gt;、最后 push」的顺序核对一遍即可。&lt;/p&gt;
&lt;h3&gt;看清镜像内部：history 与 inspect&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker history myapp:1.2.0
docker image inspect myapp:1.2.0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;docker history&lt;/code&gt; 按层列出每条指令和该层大小，镜像为什么胖、哪一层胖，一眼定位——这是排查体积问题的第一工具。&lt;code&gt;docker image inspect&lt;/code&gt; 输出完整元数据 JSON：环境变量、启动命令、每层摘要等都在里面。把最终镜像的 &lt;code&gt;EXPOSE&lt;/code&gt;、&lt;code&gt;USER&lt;/code&gt;、&lt;code&gt;CMD&lt;/code&gt; 核对一遍再推送，是个好习惯。&lt;/p&gt;
&lt;h2&gt;汇总：生产可用的最终版 Dockerfile&lt;/h2&gt;
&lt;p&gt;把前面所有优化合到一起，本例的成品：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;FROM python:3.12-slim

ENV PYTHONUNBUFFERED=1 \
    TZ=Asia/Shanghai
WORKDIR /app

RUN groupadd -r appuser &amp;amp;&amp;amp; useradd -r -g appuser appuser

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY --chown=appuser:appuser . .

USER appuser
EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD python -c &quot;import urllib.request; urllib.request.urlopen(&apos;http://127.0.0.1:8000/health&apos;)&quot;
CMD [&quot;gunicorn&quot;, &quot;-b&quot;, &quot;0.0.0.0:8000&quot;, &quot;app:app&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;配合 &lt;code&gt;.dockerignore&lt;/code&gt; 使用。这版镜像约 180 MB，非 root 运行，改源码重构建只要几秒，健康状态在 &lt;code&gt;docker ps&lt;/code&gt; 里可见。&lt;/p&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;构建失败，先定位到哪一层。&lt;/strong&gt; &lt;code&gt;docker build&lt;/code&gt; 的输出是按步骤走的，报错的那一步就是出问题的指令。常见原因：&lt;code&gt;COPY&lt;/code&gt; 的源文件不在构建上下文里（路径写错或被 &lt;code&gt;.dockerignore&lt;/code&gt; 排除了）；&lt;code&gt;RUN&lt;/code&gt; 里命令返回非 0（依赖源连不上、包名写错）。想进到失败现场看看，可以构建到出问题的前一层打个临时镜像进去排查：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker build --target builder -t debug:tmp .
docker run -it --rm debug:tmp /bin/bash
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;（&lt;code&gt;--target&lt;/code&gt; 指定构建到多阶段中的某个阶段为止。）另外 &lt;code&gt;docker build --no-cache&lt;/code&gt; 可以排除缓存干扰，确认问题是不是缓存造成的，但别拿它当日常构建方式，那等于放弃全部缓存优化。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;构建特别慢。&lt;/strong&gt; 十有八九是上下文太大：构建开始时会显示发送上下文的大小（&lt;code&gt;Sending build context to Docker daemon  512MB&lt;/code&gt; 这种），真这么大就去补 &lt;code&gt;.dockerignore&lt;/code&gt;，尤其检查 &lt;code&gt;.git&lt;/code&gt;、&lt;code&gt;node_modules&lt;/code&gt;、&lt;code&gt;.venv&lt;/code&gt; 有没有被排掉。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;容器起来就退出 / 连不上。&lt;/strong&gt; 先 &lt;code&gt;docker logs 容器名&lt;/code&gt; 看应用自己的报错；再检查监听地址是不是 &lt;code&gt;0.0.0.0&lt;/code&gt;（只听 127.0.0.1 时端口映射无效）；然后核对 &lt;code&gt;-p&lt;/code&gt; 映射的容器端口和应用监听、Dockerfile 里 &lt;code&gt;EXPOSE&lt;/code&gt; 的是否一致。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;构建时装依赖超时或 404。&lt;/strong&gt; 先分清是网络问题还是版本问题：同一个命令在宿主机上直接跑一遍，能复现就是源或版本的问题（版本号写错、包被下架），宿主机正常而容器里失败，多半是构建环境没走代理或 DNS 有问题。国内网络装 pip、apt 慢，可以在构建时临时换镜像源（给 pip 加 &lt;code&gt;-i&lt;/code&gt; 参数指向国内源、apt 换源地址），但换源地址建议通过 &lt;code&gt;ARG&lt;/code&gt; 传入而不是写死在 Dockerfile 里，这样同一份文件在不同网络环境都能构建。&lt;strong&gt;构建成功但运行行为和本地不一致&lt;/strong&gt;，则优先怀疑三件事：基础镜像版本没钉死导致依赖漂移、时区和语言环境变量没设（日志时间对不上多半是它）、文件属主或权限不对（配合前文的 &lt;code&gt;--chown&lt;/code&gt; 检查）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;镜像太大，常见原因清单：&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;基础镜像用了完整版（换 slim/alpine 或多阶段构建）；&lt;/li&gt;
&lt;li&gt;构建工具链、开发依赖进了运行镜像（多阶段构建，或把 dev 依赖拆到单独的 requirements 文件）；&lt;/li&gt;
&lt;li&gt;pip/apt 缓存留在层里（&lt;code&gt;--no-cache-dir&lt;/code&gt;、清 apt lists，且和安装写在同一条 &lt;code&gt;RUN&lt;/code&gt;）；&lt;/li&gt;
&lt;li&gt;在后面的层里 &lt;code&gt;rm&lt;/code&gt; 前面层的文件（删不掉，用同一层删除或多阶段）；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;COPY . .&lt;/code&gt; 把 &lt;code&gt;.git&lt;/code&gt;、日志、大文件一起拷了进来（&lt;code&gt;.dockerignore&lt;/code&gt; 没写全）。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;定位顺序：&lt;code&gt;docker history&lt;/code&gt; 找到胖的那一层 → 对照上面清单逐项排除。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Dockerfile 是镜像的菜谱，构建上下文决定 &lt;code&gt;COPY&lt;/code&gt; 能拿到什么，先写 &lt;code&gt;.dockerignore&lt;/code&gt; 再构建；&lt;/li&gt;
&lt;li&gt;指令按变化频率从低到高排：依赖清单先于源码，改代码才不会重装依赖；&lt;/li&gt;
&lt;li&gt;基础镜像选 slim 而非 alpine 图小，libc 兼容性更重要；体积的大头靠多阶段构建砍；&lt;/li&gt;
&lt;li&gt;服务用普通用户跑，文件属主用 &lt;code&gt;COPY --chown&lt;/code&gt; 一步到位；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;CMD&lt;/code&gt;/&lt;code&gt;ENTRYPOINT&lt;/code&gt; 用 exec 形式，信号才能正确传给应用；&lt;/li&gt;
&lt;li&gt;标签打语义化版本，&lt;code&gt;latest&lt;/code&gt; 只当别名；推送前用 &lt;code&gt;docker history&lt;/code&gt; 和 &lt;code&gt;inspect&lt;/code&gt; 体检一遍。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;最后给一条练习路径建议：不要对着文档空学，拿自己手头任何一个小脚本，按「初版跑通 → 换 slim → 拆依赖层 → 补 .dockerignore → 切非 root」的顺序亲手改五遍，每改一步都 &lt;code&gt;docker history&lt;/code&gt; 看一眼体积、&lt;code&gt;docker build&lt;/code&gt; 掐一次时间。五遍走完，Dockerfile 的核心手感就有了，以后碰到别的语言（Java、Rust、PHP）也只是把构建命令换掉，骨架完全一样。&lt;/p&gt;
&lt;p&gt;下一篇可以把这个镜像放进 Compose 里正式部署，再接上自动更新——你的应用就此进入和官方镜像一样的运维轨道了。&lt;/p&gt;
</content:encoded></item><item><title>服务器备份策略：从 rsync 到恢复演练</title><link>https://www.anexns.cloudns.org/posts/linux-backup-strategy/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-backup-strategy/</guid><description>没恢复过的备份等于没有备份：先分清该备份什么、rsync 与 rclone 的用法、云厂商快照的定位、定时自动执行与保留策略，最后一定要做一次真实的恢复演练。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先讲一个备份圈的共识：没恢复过的备份等于没有备份&lt;/h2&gt;
&lt;p&gt;服务器运维里最惨的事故，往往不是&quot;没备份&quot;，而是&quot;以为有备份&quot;。脚本跑了三年，日志里全是成功，真出事那天打开一看：备份文件是空的、格式早就坏了、恢复步骤没人会、密钥不在备份里，服务根本拉不起来。&lt;/p&gt;
&lt;p&gt;所以这一篇的主线只有一条：&lt;strong&gt;备份不是目的，恢复才是&lt;/strong&gt;。全文按这个顺序展开：先分清该备份什么，再讲 rsync 的核心用法和增量快照，然后单独说数据库备份、rclone 上云、云厂商快照的定位，接着把自动化和保留策略落地，最后用一整节讲恢复演练——这是全篇最重要的一节，前面所有工作都是为它服务的。&lt;/p&gt;
&lt;h3&gt;3-2-1 原则讲透&lt;/h3&gt;
&lt;p&gt;备份领域有一条被反复验证的经验法则，叫 3-2-1 原则：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;要素&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;落到实处&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;3 份副本&lt;/td&gt;
&lt;td&gt;数据至少有 3 份（1 份在用 + 2 份备份）&lt;/td&gt;
&lt;td&gt;源数据、本地备份、异地备份&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2 种介质&lt;/td&gt;
&lt;td&gt;副本存放在 2 种不同的存储介质上&lt;/td&gt;
&lt;td&gt;服务器硬盘 + 对象存储，或者本地盘 + 另一台机器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1 份异地&lt;/td&gt;
&lt;td&gt;至少 1 份副本放在物理上不同的地方&lt;/td&gt;
&lt;td&gt;另一台不同机房的服务器、对象存储、家里的一块移动硬盘&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;为什么要这么苛刻？因为每一种灾难的&quot;杀伤半径&quot;不同：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;误删、改错配置&lt;/strong&gt;：杀伤半径是一个目录，本机另一块盘上的备份就能救。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;硬盘损坏、文件系统崩坏&lt;/strong&gt;：杀伤半径是整块盘，本机备份如果和源数据在同一块盘上，一起完蛋。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;机器被入侵、勒索病毒、云账号被盗&lt;/strong&gt;：杀伤半径是整台机器甚至整个账号，攻击者会顺手把你机器上的备份一起删掉、加密掉。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;机房故障、服务商跑路&lt;/strong&gt;：杀伤半径是整个机房或整个平台，只有异地副本能救。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;结论很直白：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;备份和源数据放在同一台机器上，等于没有备份&amp;lt;/span&amp;gt;，它只能防住误删这一种最轻的事故。真正的备份策略，必须至少有一份副本离开这台机器。&lt;/p&gt;
&lt;p&gt;再补一条进阶经验：重要的系统可以往 3-2-1-1-0 靠拢——多一份离线或不可变副本（比如对象存储开启版本控制和保留锁定），以及 0 个错误，即备份要经过校验和恢复验证。普通个人服务器做到 3-2-1 再加恢复演练，已经超过绝大多数人的水平了。&lt;/p&gt;
&lt;p&gt;还有一个经常被忽略的维度：备份文件本身也会坏。磁盘的静默数据损坏、传输中断留下的半成品、压缩包写坏一个字节，都可能让一份&quot;存在&quot;的备份变成不可用的废品。所以关键备份在生成后要顺手留一份校验和（比如对数据库导出文件执行 &lt;code&gt;sha256sum&lt;/code&gt; 并把结果随备份一起存放），异地同步完成后抽查比对；恢复演练时更要先验校验和再动手。校验和对不上时不要慌着用，先换一份其他日期或其他副本的备份，这正是保留多版本和多副本的意义所在。&lt;/p&gt;
&lt;h2&gt;第一步：先分类，该备份什么&lt;/h2&gt;
&lt;p&gt;新手最常见的错误是&quot;整盘打包&quot;，把几十 GB 的系统原样塞进备份，结果真正重要的数据淹没在垃圾里，备份慢、占空间、恢复时还分不清主次。正确的做法是先给服务器上的东西分类，不同类别用不同的备份方式和频率。&lt;/p&gt;
&lt;h3&gt;该备份的五类东西&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类别&lt;/th&gt;
&lt;th&gt;典型内容&lt;/th&gt;
&lt;th&gt;备份方式&lt;/th&gt;
&lt;th&gt;建议频率&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;业务数据&lt;/td&gt;
&lt;td&gt;网站上传文件、用户数据、应用数据目录&lt;/td&gt;
&lt;td&gt;rsync 文件级同步&lt;/td&gt;
&lt;td&gt;每天，重要业务每小时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;配置文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/etc&lt;/code&gt;、Nginx/Caddy 配置、systemd 单元、Compose 文件、crontab&lt;/td&gt;
&lt;td&gt;rsync 或打包进 Git 仓库&lt;/td&gt;
&lt;td&gt;每天，或每次变更后&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据库&lt;/td&gt;
&lt;td&gt;MySQL、PostgreSQL、Redis、SQLite 的数据&lt;/td&gt;
&lt;td&gt;逻辑导出（dump）+ 文件同步，见下文专节&lt;/td&gt;
&lt;td&gt;每天至少一次，按业务可提高&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;密钥与证书&lt;/td&gt;
&lt;td&gt;SSH 私钥、TLS 证书与私钥、API Token、&lt;code&gt;.env&lt;/code&gt; 文件&lt;/td&gt;
&lt;td&gt;加密后单独存放，权限最严&lt;/td&gt;
&lt;td&gt;变更时立即同步&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;系统状态&lt;/td&gt;
&lt;td&gt;已装软件清单、分区与挂载信息、用户与权限&lt;/td&gt;
&lt;td&gt;导出清单文件随配置一起备份&lt;/td&gt;
&lt;td&gt;每周或变更后&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个容易漏的点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;软件清单&lt;/strong&gt;：系统本身不用整盘备份，但要留一份&quot;重建说明书&quot;。Debian 上执行 &lt;code&gt;dpkg --get-selections &amp;gt; dpkg-list.txt&lt;/code&gt;，再把 &lt;code&gt;/etc/fstab&lt;/code&gt;、网卡配置一起存下来。真要重装系统，照着清单半小时就能把环境还原到八九成。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;crontab 和 systemd timer&lt;/strong&gt;：很多人把定时任务写进 root 的 crontab，重装后忘得一干二净。&lt;code&gt;crontab -l&lt;/code&gt; 的输出要进备份，自定义的 &lt;code&gt;.service&lt;/code&gt;、&lt;code&gt;.timer&lt;/code&gt; 文件同理。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Docker 相关&lt;/strong&gt;：Compose 文件属于配置文件必须备份；数据卷属于业务数据，备份方式在 Docker 数据卷篇里专门讲过（见 /posts/docker-volumes-backup/），本篇只讲通用文件级策略。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;不该备份的东西&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;内容&lt;/th&gt;
&lt;th&gt;为什么不备&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;操作系统本体（&lt;code&gt;/usr&lt;/code&gt;、&lt;code&gt;/bin&lt;/code&gt; 等）&lt;/td&gt;
&lt;td&gt;重装即可再生，备份它纯属浪费空间和时间&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Docker 镜像本身&lt;/td&gt;
&lt;td&gt;镜像可以重新拉取或构建，要备的是 Compose 文件和数据卷&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;缓存与临时文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/tmp&lt;/code&gt;、包缓存、各类 &lt;code&gt;.cache&lt;/code&gt; 目录，可再生&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;日志文件（历史部分）&lt;/td&gt;
&lt;td&gt;一般只保留最近几天用于排障，长期归档价值低且体积大&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;交换文件、回收站类目录&lt;/td&gt;
&lt;td&gt;无意义&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;把不该备的排除掉，一台典型业务服务器真正要备份的往往只有几百 MB 到几 GB，备份窗口从几小时缩短到几分钟，这才是可持续的策略。&lt;/p&gt;
&lt;h2&gt;rsync：文件级备份的主力工具&lt;/h2&gt;
&lt;p&gt;Debian 上安装很简单：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apt update &amp;amp;&amp;amp; apt install -y rsync
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;rsync 的核心价值是&lt;strong&gt;增量传输&lt;/strong&gt;：第一次全量同步，之后每次只传变化的部分（它会按文件大小和修改时间快速筛查，需要更严格时可以加 &lt;code&gt;--checksum&lt;/code&gt; 按内容校验）。这让每天甚至每小时跑一次备份都毫无压力。&lt;/p&gt;
&lt;h3&gt;最常用的命令骨架&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;rsync -aH --numeric-ids --delete \
  --exclude=&apos;/dev/*&apos; \
  --exclude=&apos;/proc/*&apos; \
  --exclude=&apos;/sys/*&apos; \
  --exclude=&apos;/tmp/*&apos; \
  --exclude=&apos;/run/*&apos; \
  --exclude=&apos;/mnt/*&apos; \
  --exclude=&apos;/media/*&apos; \
  --exclude=&apos;/lost+found&apos; \
  / /backup/server-root/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;参数逐个说明：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-a&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;归档模式，等价于 &lt;code&gt;-rlptgoD&lt;/code&gt;：递归、保留软链接、权限、修改时间、属主属组、设备文件。这是备份的必备参数，少了它恢复出来权限和属主全乱&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-H&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;保留硬链接关系，避免同一文件存多份&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--numeric-ids&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;按数字 UID/GID 同步而不是按用户名匹配，跨机器恢复时更可靠&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--delete&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;删除目标端有、源端没有的文件，让目标成为源的镜像&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--exclude&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;排除伪文件系统和临时目录，整机备份时必须&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-v&lt;/code&gt; / &lt;code&gt;--info=progress2&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;显示过程与总进度，手动执行时建议加上&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-n&lt;/code&gt; / &lt;code&gt;--dry-run&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只演练不真跑，改命令后先用它验证一遍&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;--delete 是一把双刃剑：源路径写错、源目录被误清空、磁盘没挂载导致源目录为空时，它会忠实地把目标端的备份一起删干净。&amp;lt;/span&amp;gt;两个防护习惯：第一，新写的 rsync 命令永远先加 &lt;code&gt;-n&lt;/code&gt; 干跑一遍，确认文件列表符合预期再去掉；第二，关键备份不要只依赖 &lt;code&gt;--delete&lt;/code&gt; 做镜像，配合下文的 &lt;code&gt;--link-dest&lt;/code&gt; 多版本快照，误删也能从昨天的快照里捞回来。
:::&lt;/p&gt;
&lt;h3&gt;两个最容易踩的路径坑&lt;/h3&gt;
&lt;p&gt;rsync 对源路径末尾的斜杠非常敏感：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 把 data 目录本身同步过去，结果是 /backup/data/...
rsync -a /srv/data /backup/

# 只同步 data 里面的内容，结果是文件直接铺在 /backup/ 下
rsync -a /srv/data/ /backup/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;写脚本时务必统一一种写法并亲自验证一次结果。另外，远程路径中的冒号会被当成&quot;主机:路径&quot;的分隔符，本地路径里带冒号时要用 &lt;code&gt;./&lt;/code&gt; 前缀消歧，这类小坑在排障一节还会提到。&lt;/p&gt;
&lt;h3&gt;本地与远程两种目标&lt;/h3&gt;
&lt;p&gt;备份到本机另一块盘或挂载的移动硬盘，就是上面的本地写法。备份到另一台服务器走 SSH：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;rsync -aH --numeric-ids --delete -e &quot;ssh -p 22 -i /root/.ssh/backup_key&quot; \
  /srv/data/ backupuser@192.0.2.50:/data/backup/web01/data/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;远程备份的几个要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;用专用密钥和专用账号&lt;/strong&gt;：备份机上建一个只有备份目录写权限的账号，不要用 root 密钥到处飞。更进一步可以在 &lt;code&gt;authorized_keys&lt;/code&gt; 里用 &lt;code&gt;command=&quot;rrsync ...&quot;&lt;/code&gt; 之类的受限命令把这个密钥锁死在备份用途上。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;推送还是拉取&lt;/strong&gt;：源机主动推（push）简单直观；但从安全角度，更推荐由备份机主动拉（pull）——源机被攻破时，攻击者拿不到通往备份机的钥匙。哪种都行，想清楚威胁模型再选。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;限速&lt;/strong&gt;：大文件初次同步可以加 &lt;code&gt;--bwlimit=20m&lt;/code&gt;（单位是 KB/s，这里约 20 MB/s）避免跑满带宽影响业务。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;用 --link-dest 做增量快照式备份&lt;/h2&gt;
&lt;p&gt;镜像式备份（&lt;code&gt;--delete&lt;/code&gt;）只有一个版本：今天的文件把昨天的覆盖掉。昨天误删的文件，今天同步完就彻底没了。解决办法是 rsync 的 &lt;code&gt;--link-dest&lt;/code&gt;：每次备份生成一个独立的日期目录，没变化的文件用硬链接指向上一份快照，不占额外空间；变了的文件存新副本。效果上等价于&quot;每天一份全量备份&quot;，实际占用却接近增量。&lt;/p&gt;
&lt;p&gt;原理一句话：硬链接让多个目录项指向同一份数据，只要还有一个链接在，数据就不释放。所以删掉旧快照时，只会删掉那些没有被新快照引用的旧版本文件。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
# /usr/local/bin/backup-snapshot.sh
set -euo pipefail

SRC=&quot;/srv/data/&quot;
DEST=&quot;/backup/snapshots&quot;
TODAY=&quot;$(date +%F)&quot;
LINK=&quot;&quot;

# 找到最近一份快照作为硬链接基准
LAST=&quot;$(ls -1d ${DEST}/????-??-?? 2&amp;gt;/dev/null | tail -n 1 || true)&quot;
if [ -n &quot;${LAST}&quot; ]; then
  LINK=&quot;--link-dest=${LAST}&quot;
fi

rsync -aH --numeric-ids ${LINK} &quot;${SRC}&quot; &quot;${DEST}/${TODAY}/&quot;

# 更新一个 latest 软链接，方便查看与恢复
ln -sfn &quot;${DEST}/${TODAY}&quot; &quot;${DEST}/latest&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;执行效果：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/backup/snapshots/
├── 2026-11-13/      ← 每天一个完整目录
├── 2026-11-14/
├── 2026-11-15/
└── latest -&amp;gt; /backup/snapshots/2026-11-15
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;想恢复三天前的文件，直接去对应日期目录里拷，不需要任何解压和还原工具——这是文件级快照最大的好处，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;恢复路径越短，出事时越不容易出错&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;注意事项：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;--link-dest&lt;/code&gt; 的路径建议写绝对路径，相对路径是相对于目标目录计算的，容易搞错。&lt;/li&gt;
&lt;li&gt;目标文件系统必须支持硬链接（ext4、XFS 都没问题；某些网盘挂载盘不行）。&lt;/li&gt;
&lt;li&gt;判断文件是否变化默认看大小和修改时间。数据库文件这类&quot;原地修改&quot;的大文件每次都会整份复制，快照省不了空间——这也是数据库要单独处理的原因之一。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;数据库必须单独备份&lt;/h2&gt;
&lt;p&gt;新手最容易犯的错：把 MySQL 的 &lt;code&gt;/var/lib/mysql&lt;/code&gt; 或 PostgreSQL 的数据目录直接 rsync 走，觉得&quot;文件都在，肯定能恢复&quot;。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;直接拷贝正在运行的数据库数据目录，恢复出来大概率是损坏的&amp;lt;/span&amp;gt;。原因不复杂：数据库运行时，数据一部分在内存里还没落盘，一部分正在写入，你拷到的文件是某个不一致瞬间的切片；而且 InnoDB、PostgreSQL 这类引擎依赖日志与数据文件的严格对应关系，拷错顺序就对不上。停库冷备倒是可以，但没人愿意每天停一次业务。&lt;/p&gt;
&lt;p&gt;正确做法是&lt;strong&gt;逻辑导出&lt;/strong&gt;：用官方工具把数据导出成 SQL 文本，再把导出文件纳入文件级备份。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# MySQL / MariaDB：导出全部库，--single-transaction 保证 InnoDB 一致性且不锁表
mysqldump --single-transaction --routines --triggers --events \
  -u root -p&apos;密码&apos; --all-databases | gzip &amp;gt; /backup/db/mysql-$(date +%F).sql.gz

# PostgreSQL：以 postgres 用户导出全部库
su - postgres -c &quot;pg_dumpall&quot; | gzip &amp;gt; /backup/db/pg-$(date +%F).sql.gz

# SQLite：用内置 .backup 命令导出一致性副本，不要直接拷 .db 文件
sqlite3 /srv/app/app.db &quot;.backup /backup/db/app-$(date +%F).db&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;要点补充：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;导出文件要&lt;strong&gt;先落到本地再同步走&lt;/strong&gt;，不要让 dump 直接写网络目标，中途断线会留下一个看似存在的半成品文件。&lt;/li&gt;
&lt;li&gt;dump 文件里包含全部数据，权限按敏感文件处理，不要裸奔放在 Web 可访问目录。&lt;/li&gt;
&lt;li&gt;数据库跑在 Docker 里时同理，用 &lt;code&gt;docker exec&lt;/code&gt; 在容器内执行 dump 命令输出到宿主机文件，再走文件级备份；数据卷层面的备份方法见 /posts/docker-volumes-backup/。&lt;/li&gt;
&lt;li&gt;数据量大到 dump 太慢时，再考虑主从复制、物理备份工具（如 Percona XtraBackup、pgBackRest）这类进阶方案，普通规模用 dump 足够。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;rclone：把备份再送一份上云&lt;/h2&gt;
&lt;p&gt;本地快照解决了版本问题，异地副本则交给 rclone。它支持几乎所有主流对象存储和网盘（S3、Cloudflare R2、Backblaze B2、Google Drive、OneDrive 等），用法和 rsync 类似，是把备份送出机房最省事的工具。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 安装
apt install -y rclone

# 交互式配置远程存储（按向导填 Access Key 等信息）
rclone config

# 把快照目录同步到对象存储
rclone sync /backup/snapshots remote:backup-bucket/web01/snapshots \
  --transfers 4 --checkers 8 --bwlimit 20M --log-file /var/log/rclone-backup.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;定位要摆正：rclone 是&quot;再送一份&quot;的搬运工，不是备份策略本身。它负责异地那一份副本，本地快照的历史版本管理还是 rsync 的活。&lt;/p&gt;
&lt;p&gt;两个提醒：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;rclone sync&lt;/code&gt; 同样是镜像语义（会删目标端多余文件），和 rsync 的 &lt;code&gt;--delete&lt;/code&gt; 一个脾气，路径写错同样危险，重要数据建议目标桶开启版本控制兜底。&lt;/li&gt;
&lt;li&gt;备份里有密钥、数据库导出这类敏感内容时，rclone 自带 &lt;code&gt;crypt&lt;/code&gt; 远程可以做客户端加密，密钥自己保管、云端只看到密文。代价是恢复时多一步解密，务必把 crypt 的密码另存一份在安全的地方——密码丢了，这份备份就等于不存在。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;云厂商快照的定位&lt;/h2&gt;
&lt;p&gt;阿里云、腾讯云、AWS 等平台都提供云盘快照功能，一键给整块云盘拍一张&quot;照片&quot;，回滚也是一键完成。用好它，但别神化它。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;云厂商快照&lt;/th&gt;
&lt;th&gt;文件级备份（rsync/rclone）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;恢复粒度&lt;/td&gt;
&lt;td&gt;整盘回滚&lt;/td&gt;
&lt;td&gt;任意文件、任意目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;恢复速度&lt;/td&gt;
&lt;td&gt;快，整机回退几分钟&lt;/td&gt;
&lt;td&gt;按文件量，单文件秒级、整机较慢&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;历史版本&lt;/td&gt;
&lt;td&gt;支持多版本，按量计费&lt;/td&gt;
&lt;td&gt;自己管理，成本可控&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;风险边界&lt;/td&gt;
&lt;td&gt;与云账号绑定，账号被盗、欠费、厂商故障时一起受影响&lt;/td&gt;
&lt;td&gt;副本在别处，风险隔离&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;典型用途&lt;/td&gt;
&lt;td&gt;系统升级、大改配置前的整机保险&lt;/td&gt;
&lt;td&gt;日常数据保护与长期归档&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;合理的分工是：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;快照管&quot;整机回退&quot;，文件级备份管&quot;数据保命&quot;&amp;lt;/span&amp;gt;。动手大改系统前手动打一张快照，改崩了一键回滚；日常的业务数据、配置和数据库，仍然老老实实走文件级备份并送一份出账号之外。另外注意多数平台的&quot;自动快照策略&quot;保留份数有限，且快照跟着云盘走，云盘删了快照可能跟着没，重要系统要确认快照的保留规则。&lt;/p&gt;
&lt;h2&gt;自动化：脚本、定时与保留策略&lt;/h2&gt;
&lt;p&gt;备份靠手动执行等于没有备份——人总会忘。把前面的命令收进一个脚本，交给 systemd timer 或 cron 定时跑。&lt;/p&gt;
&lt;p&gt;一个完整的备份脚本骨架：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
# /usr/local/bin/backup-all.sh
set -euo pipefail

LOG=/var/log/backup.log
exec &amp;gt;&amp;gt;&quot;${LOG}&quot; 2&amp;gt;&amp;amp;1
echo &quot;===== backup start: $(date &apos;+%F %T&apos;) =====&quot;

# 1. 数据库导出
mysqldump --single-transaction --all-databases -u root -p&apos;密码&apos; \
  | gzip &amp;gt; /backup/db/mysql-$(date +%F).sql.gz

# 2. 文件快照（--link-dest 增量）
/usr/local/bin/backup-snapshot.sh

# 3. 异地同步
rclone sync /backup/snapshots remote:backup-bucket/web01/snapshots --bwlimit 20M

# 4. 清理过期备份（见保留策略）
find /backup/snapshots -maxdepth 1 -type d -name &apos;????-??-??&apos; -mtime +35 -exec rm -rf {} +
find /backup/db -name &apos;*.sql.gz&apos; -mtime +35 -delete

echo &quot;===== backup done: $(date &apos;+%F %T&apos;) =====&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;用 systemd timer 每天凌晨执行（比 cron 更好查状态和日志）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# /etc/systemd/system/backup.service
[Unit]
Description=Daily backup
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/backup-all.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;# /etc/systemd/system/backup.timer
[Unit]
Description=Run backup daily

[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=600
Persistent=true

[Install]
WantedBy=timers.target
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;systemctl daemon-reload
systemctl enable --now backup.timer
systemctl list-timers backup.timer   # 确认下次执行时间
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;用 cron 也完全可以，一行搞定：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;30 3 * * * root /usr/local/bin/backup-all.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;保留策略：别只留最新一份&lt;/h3&gt;
&lt;p&gt;只留一份备份，等于把宝押在&quot;这份恰好没坏、且事故恰好发生在备份之后被发现之前&quot;。现实中很多事故是潜伏型的：文件三天前就被误删了、数据一周前就被写坏了，你发现时最新备份里早已同步了错误结果。所以要保留多个时间点，经典的配比是&lt;strong&gt;日 7、周 4、月 6&lt;/strong&gt;：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;层级&lt;/th&gt;
&lt;th&gt;保留份数&lt;/th&gt;
&lt;th&gt;实现方式&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;每日&lt;/td&gt;
&lt;td&gt;最近 7 天&lt;/td&gt;
&lt;td&gt;每天一份快照&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每周&lt;/td&gt;
&lt;td&gt;最近 4 周&lt;/td&gt;
&lt;td&gt;每周日的那份多留三周&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每月&lt;/td&gt;
&lt;td&gt;最近 6 个月&lt;/td&gt;
&lt;td&gt;每月 1 日的那份多留半年&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;--link-dest&lt;/code&gt; 的硬链接机制让这种保留几乎不花额外空间（只有变化的文件占新空间），上面脚本里的 &lt;code&gt;-mtime +35&lt;/code&gt; 是简化版清理，认真做可以用日期判断把周、月档挑出来延长保留。原则是：&lt;strong&gt;先定保留策略，再写清理逻辑&lt;/strong&gt;，清理永远只删超出策略的部分。&lt;/p&gt;
&lt;h3&gt;备份失败必须有人知道&lt;/h3&gt;
&lt;p&gt;脚本在无人值守时最常见的死法是静默失败：磁盘满了、网络断了、密码过期了，脚本报错退出，第二天照样&quot;无事发生&quot;，直到真出事才发现备份停在三个月前。对策：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;脚本里开启 &lt;code&gt;set -euo pipefail&lt;/code&gt;，任何一步失败立即整体退出并留下非零状态码，systemd 能记录到失败状态。&lt;/li&gt;
&lt;li&gt;在脚本末尾写一行成功标记（比如 &lt;code&gt;touch /var/lib/backup-last-success&lt;/code&gt; 并记录时间戳），由监控去查这个标记的新鲜程度。&lt;/li&gt;
&lt;li&gt;告警渠道怎么接、阈值怎么定，在服务器监控篇里有完整方案（见 /posts/linux-server-monitoring/），核心思想是：&lt;strong&gt;备份成功不用报，备份没成功必须报&lt;/strong&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;恢复演练：全篇最重要的一节&lt;/h2&gt;
&lt;p&gt;前面所有工作——分类、快照、异地、自动化——都只是在&quot;生产备份&quot;。备份到底有没有用，只有恢复演练能证明。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;从没做过恢复演练的备份，只能算&quot;可能能用&quot;，出事时赌的就是运气&amp;lt;/span&amp;gt;。而事故现场是最差的试错环境：业务停着、用户催着、手心冒汗，这时候才第一次研究怎么恢复，几乎必然出岔子。&lt;/p&gt;
&lt;h3&gt;演练怎么做&lt;/h3&gt;
&lt;p&gt;挑一个真实服务（比如博客或一个内部应用），在一台临时机器或测试目录里，完整地从备份恢复一遍：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;准备干净环境&lt;/strong&gt;：新开一台临时 VPS 或本机建一个测试目录，假设原机已经不存在，不许回去&quot;借&quot;任何文件。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;按备份清单取回数据&lt;/strong&gt;：从异地副本（不是本地快照，走最远的那条路）把配置、数据、数据库导出拉回来。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;恢复数据库&lt;/strong&gt;：建库、导入 dump，检查表数量和最新一条数据的时间。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;恢复配置与数据文件&lt;/strong&gt;：配置文件就位，业务数据用 rsync 拷回目标目录，注意属主和权限。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;补齐密钥与证书&lt;/strong&gt;：从加密存放处取回密钥、证书、&lt;code&gt;.env&lt;/code&gt;，没有这一步服务多半起不来——这正是演练要暴露的问题。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;启动服务并验证&lt;/strong&gt;：服务能起、页面能开、核心功能点一遍（登录、读写一条数据），而不是只看进程存在。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;记录全过程&lt;/strong&gt;：总耗时、每一步的命令、卡住的地方、缺的东西，整理成一份恢复操作手册，下次照着做。&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;# 演练时的典型恢复命令示例
# 1) 从异地拉回某天的快照
rclone sync remote:backup-bucket/web01/snapshots/2026-11-15 /restore/2026-11-15

# 2) 恢复数据库
zcat /restore/2026-11-15/db/mysql-2026-11-15.sql.gz | mysql -u root -p

# 3) 恢复业务数据与配置（注意 -a 保权限属主）
rsync -a /restore/2026-11-15/data/ /srv/data/
rsync -a /restore/2026-11-15/etc/ /etc/
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;演练的节奏&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;频率&lt;/strong&gt;：至少每季度一次；备份方案有任何改动（换了工具、换了目标存储、改了目录结构），改动后立即补一次。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;抽查文件&lt;/strong&gt;：每月随手从备份里抽几个文件出来，和源文件做一次校验对比（&lt;code&gt;diff&lt;/code&gt; 或校验和），确认备份内容是活的。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;记录耗时&lt;/strong&gt;：恢复总时长就是你的&quot;最短故障时间&quot;下限，心里有数才好做取舍。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;演练发现问题是常态，而且是好事：在演练里发现 &lt;code&gt;.env&lt;/code&gt; 没进备份，比在事故里发现便宜一万倍。&lt;/p&gt;
&lt;h2&gt;排障：备份环节的常见问题&lt;/h2&gt;
&lt;h3&gt;备份脚本静默失败&lt;/h3&gt;
&lt;p&gt;症状：以为一直在备份，查看时发现最新备份停在很久以前。&lt;/p&gt;
&lt;p&gt;排查顺序：先看日志（&lt;code&gt;journalctl -u backup.service&lt;/code&gt; 或脚本的日志文件）确认最后一次成功时间；再手动完整跑一遍脚本看卡在哪一步；常见元凶是目标盘满、rclone 的 Token 过期、SSH 密钥被换、源目录路径变更。根治办法见上文：成功标记 + 监控告警，永远不要靠&quot;没消息就是好消息&quot;。&lt;/p&gt;
&lt;h3&gt;rsync 删多了&lt;/h3&gt;
&lt;p&gt;症状：加了 &lt;code&gt;--delete&lt;/code&gt; 后目标端文件大批消失。&lt;/p&gt;
&lt;p&gt;先稳住：立刻停掉脚本，防止其他副本被继续同步覆盖。然后看你的保留结构——如果用了 &lt;code&gt;--link-dest&lt;/code&gt; 多版本快照，去前一天的日期目录里把文件拷回来，这正是多版本的价值。如果只有一份镜像备份且目标端已删，只能尝试从其他副本（异地、快照）找。预防重于补救：&lt;code&gt;--delete&lt;/code&gt; 的命令首次运行必须先 &lt;code&gt;-n&lt;/code&gt; 干跑，源路径末尾斜杠的含义要确认清楚，源目录是挂载点时在脚本里加一道检查（比如确认某个标志文件存在再执行，防止盘没挂上、源目录为空导致镜像被清空）。&lt;/p&gt;
&lt;h3&gt;备份把目标盘撑满&lt;/h3&gt;
&lt;p&gt;症状：备份盘 100%，新备份写不进去，旧备份也可能受损。&lt;/p&gt;
&lt;p&gt;原因通常是：保留策略没生效（清理逻辑没跑或写错）、某个大文件被频繁修改导致每个快照都存整份、日志或缓存目录忘了排除。处理：先按日期从旧到新删超出保留策略的快照腾空间；再用 &lt;code&gt;du -sh&lt;/code&gt; 逐层定位异常膨胀的目录；最后把清理逻辑和保留策略对一遍账，并给备份盘设置用量告警，别等满了才知道。&lt;/p&gt;
&lt;h3&gt;恢复出来权限全乱&lt;/h3&gt;
&lt;p&gt;症状：文件都回来了，但服务起不来，日志里全是 Permission denied，或者 Web 应用报目录不可写。&lt;/p&gt;
&lt;p&gt;根因基本是备份或恢复时没带 &lt;code&gt;-a&lt;/code&gt;：普通 &lt;code&gt;cp&lt;/code&gt;、不带参数的 rsync 会丢失属主、权限和软链接。确认三点：备份时用了 &lt;code&gt;-aH --numeric-ids&lt;/code&gt;；恢复时同样用 rsync &lt;code&gt;-a&lt;/code&gt; 而不是拖拽拷贝；恢复后按原环境核对关键目录的属主（&lt;code&gt;ls -ln&lt;/code&gt; 对照备份端）。用 root 执行备份和恢复也是前提，普通用户跑 rsync 无法保留他人的属主信息，rsync 会直接报错或悄悄降级。&lt;/p&gt;
&lt;h3&gt;远程同步中断、速度慢&lt;/h3&gt;
&lt;p&gt;大文件首次同步走 SSH 中断，多半是网络抖动或超时：rsync 支持断点续传，加 &lt;code&gt;--partial&lt;/code&gt;（或 &lt;code&gt;-P&lt;/code&gt;）重跑即可接着传。速度慢先分清瓶颈在带宽、磁盘还是 CPU（加密开销），老机器上可以给 SSH 换轻量加密算法或改用 rsync 守护进程模式，但内网之外不建议裸跑守护进程。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;备份的验收标准是恢复成功，不是脚本跑完。3-2-1 原则保证副本的数量、介质和地域分布，其中异地那一份不可省略。&lt;/li&gt;
&lt;li&gt;先分类再备份：业务数据、配置、数据库、密钥与证书、系统状态清单各自用合适的方式；系统本体和镜像这类可再生的东西不要备。&lt;/li&gt;
&lt;li&gt;rsync 是文件级备份的主力：&lt;code&gt;-a&lt;/code&gt; 保住权限属主，&lt;code&gt;--delete&lt;/code&gt; 用前必须干跑验证，&lt;code&gt;--link-dest&lt;/code&gt; 用硬链接实现低成本的多版本快照。&lt;/li&gt;
&lt;li&gt;数据库不能直接拷数据目录，必须用官方 dump 工具做逻辑导出再纳入文件备份。&lt;/li&gt;
&lt;li&gt;rclone 负责把副本送出机房，云厂商快照负责整机回退，两者与文件级备份是分工不是替代。&lt;/li&gt;
&lt;li&gt;自动化要用 systemd timer 或 cron 落地，配好保留策略（日 7、周 4、月 6 是个好起点）和失败告警。&lt;/li&gt;
&lt;li&gt;每季度至少做一次真实的恢复演练，把过程写成手册。备份这件事，做到这一节，才算真正做完。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>Bash 脚本实战入门</title><link>https://www.anexns.cloudns.org/posts/linux-bash-scripting/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-bash-scripting/</guid><description>把重复操作变成脚本：变量与引号、条件与循环、函数与退出码，再写两个能直接用的运维脚本——批量巡检与日志清理，最后讲清脚本与交互环境的差异。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;开头：同一组命令敲第三遍，就该写脚本了&lt;/h2&gt;
&lt;p&gt;服务器运维里有大量这样的场景：每天登上机器敲同一组命令看服务状态、每周手动删一批旧日志、每次部署都按固定顺序执行十来条命令。第一次敲是熟悉，第二次敲是熟练，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;同一组操作重复到第三次，就值得把它写成脚本&amp;lt;/span&amp;gt;。这不是偷懒，而是运维的基本功：手工操作靠记忆和状态，人一累就漏步骤、敲错参数；脚本把操作固化下来，每次执行都一模一样，出了问题还能回头看脚本本身找原因。&lt;/p&gt;
&lt;p&gt;本篇是 Linux 系列的脚本入门，主线是这样的：先立好脚本的骨架规范，再依次过变量、条件、循环、函数这四块语法地基，然后用这些地基拼出两个能直接拿去用的实战脚本——批量巡检和日志清理，最后讲清脚本运行环境与你平时敲命令的交互环境差在哪、常见报错怎么定位。读完这一篇，你应该能独立写出几十行级别的日常运维脚本，而不是每次都去搜索现成的片段拼凑。&lt;/p&gt;
&lt;h2&gt;一、为什么写脚本：不只是省时间&lt;/h2&gt;
&lt;p&gt;把重复操作脚本化，收益至少有三层，省时间只是最表面的一层。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;收益&lt;/th&gt;
&lt;th&gt;手工操作&lt;/th&gt;
&lt;th&gt;脚本化之后&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;一致性&lt;/td&gt;
&lt;td&gt;每次靠记忆，步骤可能漏、参数可能错&lt;/td&gt;
&lt;td&gt;每次执行完全相同&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;留痕&lt;/td&gt;
&lt;td&gt;敲过什么命令，关掉终端就忘了&lt;/td&gt;
&lt;td&gt;脚本文件本身就是操作记录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;可复现&lt;/td&gt;
&lt;td&gt;换个人、换台机器要重新口述一遍&lt;/td&gt;
&lt;td&gt;拷过去就能跑，结果可对比&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;可调度&lt;/td&gt;
&lt;td&gt;必须人守在终端前&lt;/td&gt;
&lt;td&gt;交给 cron 定时自动执行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;可审查&lt;/td&gt;
&lt;td&gt;出事后无法复盘当时做了什么&lt;/td&gt;
&lt;td&gt;改脚本走 diff，改动一目了然&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;尤其是最后两点：脚本写好之后，绝大多数的归宿是交给定时任务无人值守地跑（定时任务的配置方法见 &lt;a href=&quot;/posts/linux-cron-timers/&quot;&gt;定时任务：cron 与 systemd timer&lt;/a&gt;），而无人值守恰恰是最怕出错的场景——没有人在旁边看着，一条写错的命令可以安安静静地错一整晚。所以本篇会反复强调两件事：脚本要&lt;strong&gt;失败即停&lt;/strong&gt;，不要带着错误继续往下跑；涉及删除等不可逆操作，要&lt;strong&gt;先演练再真删&lt;/strong&gt;。这两条习惯比任何语法技巧都重要。&lt;/p&gt;
&lt;h2&gt;二、脚本骨架：先把规矩立好&lt;/h2&gt;
&lt;h3&gt;2.1 shebang：第一行决定用谁解释&lt;/h3&gt;
&lt;p&gt;每个脚本的第一行都应该是 shebang，它告诉内核用哪个解释器来执行这个文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;写脚本就用 &lt;code&gt;/bin/bash&lt;/code&gt;，不要写 &lt;code&gt;/bin/sh&lt;/code&gt;。在 Debian/Ubuntu 系的系统上，&lt;code&gt;/bin/sh&lt;/code&gt; 指向的是 dash，一个功能精简的 Shell，本篇要用到的 &lt;code&gt;[[ ]]&lt;/code&gt;、数组等 Bash 特性在 dash 里统统不存在。脚本在你手里跑得好好的，换个执行方式就报语法错误，十有八九就是 shebang 写成了 &lt;code&gt;sh&lt;/code&gt; 或者被人用 &lt;code&gt;sh script.sh&lt;/code&gt; 的方式强行调用了——用 &lt;code&gt;sh&lt;/code&gt; 调用会直接无视 shebang，这也是要养成 &lt;code&gt;./script.sh&lt;/code&gt; 方式运行习惯的原因之一。&lt;/p&gt;
&lt;h3&gt;2.2 set 三件套：让脚本失败即停&lt;/h3&gt;
&lt;p&gt;骨架的第二部分，是紧跟在 shebang 后面的一行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;set -euo pipefail
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这一行是三个开关的组合，逐个拆开讲：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;开关&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;没有它会怎样&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-e&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;任一命令返回非零退出码，脚本立即退出&lt;/td&gt;
&lt;td&gt;中间步骤失败了还继续往下跑，错误被掩盖&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-u&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;引用未定义的变量直接报错退出&lt;/td&gt;
&lt;td&gt;变量名打错了展开成空字符串，悄无声息地错下去&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-o pipefail&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;管道里任一命令失败，整个管道算失败&lt;/td&gt;
&lt;td&gt;只看最后一个命令的退出码，前面的失败被吞掉&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;pipefail&lt;/code&gt; 最容易被忽视，举个例子：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;grep &quot;error&quot; /var/log/app.log | wc -l
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果日志文件根本不存在，&lt;code&gt;grep&lt;/code&gt; 会报错退出，但 &lt;code&gt;wc -l&lt;/code&gt; 照样能跑出结果（0 行），整个管道的退出码是 &lt;code&gt;wc&lt;/code&gt; 的 0，脚本以为一切正常。加上 &lt;code&gt;pipefail&lt;/code&gt; 之后，&lt;code&gt;grep&lt;/code&gt; 的失败会如实反映到管道退出码上，配合 &lt;code&gt;-e&lt;/code&gt; 立即停下。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;code&gt;set -e&lt;/code&gt; 有个众所周知的副作用：在 &lt;code&gt;if&lt;/code&gt; 条件、&lt;code&gt;while&lt;/code&gt; 条件、&lt;code&gt;&amp;amp;&amp;amp;&lt;/code&gt;/&lt;code&gt;||&lt;/code&gt; 列表里被&quot;测试&quot;的命令失败不会触发退出，这是设计如此，不是 bug。另外它对函数内部的失败传播也有一些反直觉的细节。现阶段记住一条就够了：关键步骤不要只依赖 &lt;code&gt;set -e&lt;/code&gt;，该显式判断退出码的地方还是要显式判断。
:::&lt;/p&gt;
&lt;h3&gt;2.3 注释与可执行权限&lt;/h3&gt;
&lt;p&gt;注释写&quot;为什么&quot;，不写&quot;是什么&quot;。&lt;code&gt;# 删除日志&lt;/code&gt; 是废话注释，&lt;code&gt;# 日志盘只有 20G，按保留 14 天折算刚好够用&lt;/code&gt; 才是半年后的你真正需要的。代码本身能表达在做什么，只有动机和背景需要写进注释。&lt;/p&gt;
&lt;p&gt;脚本存盘后赋予可执行权限，两种运行方式的区别要分清：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;chmod +x check.sh

./check.sh        # 按 shebang 指定的解释器执行，需要 +x 权限
bash check.sh     # 显式用 bash 执行，不需要 +x，但同样无视 shebang 以外的差异
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;日常自己跑用哪种都行，但写进 cron 或被其他程序调用时，统一用 &lt;code&gt;./script.sh&lt;/code&gt; 或绝对路径调用，让 shebang 生效。&lt;/p&gt;
&lt;h2&gt;三、变量：九成脚本 bug 出在引号上&lt;/h2&gt;
&lt;h3&gt;3.1 赋值与引用&lt;/h3&gt;
&lt;p&gt;Bash 变量赋值有一个对新手极不友好的规矩：&lt;strong&gt;等号两边不能有空格&lt;/strong&gt;。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;NAME=&quot;web-server&quot;     # 对
NAME = &quot;web-server&quot;   # 错：会被理解成运行名为 NAME 的命令
echo &quot;$NAME&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;引用变量时用 &lt;code&gt;$NAME&lt;/code&gt; 或 &lt;code&gt;${NAME}&lt;/code&gt;，后者在变量名后面紧跟其他字符时必须用，比如 &lt;code&gt;${NAME}_01&lt;/code&gt;。变量名全大写只是约定（为了和系统环境变量风格一致），不是语法要求。&lt;/p&gt;
&lt;h3&gt;3.2 引号纪律&lt;/h3&gt;
&lt;p&gt;这是 Bash 脚本最重要的一条纪律：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;变量展开默认要加双引号，不加引号的展开会经历分词和通配符扩展，是脚本 bug 的头号来源&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;FILE=&quot;my log.txt&quot;

rm $FILE        # 错：被拆成两个参数，删的是 my 和 log.txt
rm &quot;$FILE&quot;      # 对：整体作为一个参数
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三种引号的区别一次说清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;写法&lt;/th&gt;
&lt;th&gt;变量展开&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&quot;$VAR&quot;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;展开，且整体算一个参数&lt;/td&gt;
&lt;td&gt;默认就用这个&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&apos;$VAR&apos;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不展开，原样输出 &lt;code&gt;$VAR&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;需要字面量时用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;$VAR&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;展开后还会分词、扩展通配符&lt;/td&gt;
&lt;td&gt;除非明确需要分词，否则别用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;单引号里一切都是字面量，连反斜杠都不转义；双引号里只有 &lt;code&gt;$&lt;/code&gt;、反引号、&lt;code&gt;\&lt;/code&gt; 等少数符号保留特殊含义。记不住细节没关系，记住默认动作是双引号，就避开了绝大多数坑。&lt;/p&gt;
&lt;h3&gt;3.3 位置参数与特殊变量&lt;/h3&gt;
&lt;p&gt;脚本被调用时传入的参数，通过一组特殊变量读取：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;变量&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;$0&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;脚本自身的路径/名字&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;$1&lt;/code&gt;、&lt;code&gt;$2&lt;/code&gt;……&lt;/td&gt;
&lt;td&gt;第 1、第 2 个参数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;$#&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;参数个数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;$@&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;全部参数，每个参数独立&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;$*&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;全部参数，拼成一整个字符串&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;$?&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;上一条命令的退出码&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;$$&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;当前脚本的进程 PID&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;$@&lt;/code&gt; 和 &lt;code&gt;$*&lt;/code&gt; 的区别只在加引号时才显现，也是最容易踩的一处：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;show() {
    echo &quot;用 \$@ 收到 $# 个参数&quot;
}

wrap() {
    show &quot;$@&quot;   # 对：参数逐个原样传递
    show &quot;$*&quot;   # 错：所有参数被拼成一个字符串传过去
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;转发参数一律用 &lt;code&gt;&quot;$@&quot;&lt;/code&gt;，这是没有例外的规矩。&lt;code&gt;$*&lt;/code&gt; 的正确用途基本只剩下把参数拼起来打日志。&lt;/p&gt;
&lt;h3&gt;3.4 环境变量、局部变量与只读&lt;/h3&gt;
&lt;p&gt;用 &lt;code&gt;export&lt;/code&gt; 导出的变量会传给子进程，没导出的只是脚本内部变量。系统层面的 &lt;code&gt;PATH&lt;/code&gt;、&lt;code&gt;HOME&lt;/code&gt; 都是环境变量。还有一个 &lt;code&gt;readonly&lt;/code&gt; 可以把变量锁死防止误改，了解即可，日常脚本用得不多：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;readonly CONF=&quot;/etc/myapp.conf&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;四、条件判断：退出码是一切的基础&lt;/h2&gt;
&lt;h3&gt;4.1 先理解退出码&lt;/h3&gt;
&lt;p&gt;Linux 里每个命令结束时都会返回一个 0 到 255 的整数：&lt;strong&gt;0 表示成功，非 0 表示各种失败&lt;/strong&gt;。条件判断的本质，就是在读这个数字。用 &lt;code&gt;$?&lt;/code&gt; 可以手动读它，但注意 &lt;code&gt;$?&lt;/code&gt; 读一次就被刷新，连续判断时要先存下来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl is-active --quiet nginx
if [ $? -eq 0 ]; then
    echo &quot;nginx 正在运行&quot;
fi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;更常见的写法是直接把命令写进 &lt;code&gt;if&lt;/code&gt;，让 &lt;code&gt;if&lt;/code&gt; 自己去读退出码，上面那段等价于：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;if systemctl is-active --quiet nginx; then
    echo &quot;nginx 正在运行&quot;
fi
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;4.2 test 的三种写法&lt;/h3&gt;
&lt;p&gt;专门做条件测试的是 &lt;code&gt;test&lt;/code&gt; 命令，它有三种形态：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;写法&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;test 表达式&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;最原始，少用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;[ 表达式 ]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;POSIX 通用，括号两边必须有空格&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;[[ 表达式 ]]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Bash 增强版，支持模式匹配和正则，推荐&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;[[ ]]&lt;/code&gt; 里可以用 &lt;code&gt;==&lt;/code&gt; 做通配符模式匹配、用 &lt;code&gt;=~&lt;/code&gt; 做正则匹配，而且内部不会发生分词，所以变量可以不加引号（但加上也无妨）。本篇统一用 &lt;code&gt;[[ ]]&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;4.3 三类判断对照表&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类别&lt;/th&gt;
&lt;th&gt;常用判断&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;字符串&lt;/td&gt;
&lt;td&gt;&lt;code&gt;[[ $A == &quot;start&quot; ]]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;相等&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;字符串&lt;/td&gt;
&lt;td&gt;&lt;code&gt;[[ -z $A ]]&lt;/code&gt; / &lt;code&gt;[[ -n $A ]]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;为空 / 非空&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数字&lt;/td&gt;
&lt;td&gt;&lt;code&gt;[[ $N -eq 10 ]]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;等于（数字比较用 &lt;code&gt;-eq&lt;/code&gt;，不要用 &lt;code&gt;==&lt;/code&gt;）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数字&lt;/td&gt;
&lt;td&gt;&lt;code&gt;-ne&lt;/code&gt; &lt;code&gt;-gt&lt;/code&gt; &lt;code&gt;-ge&lt;/code&gt; &lt;code&gt;-lt&lt;/code&gt; &lt;code&gt;-le&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不等、大于、大于等于、小于、小于等于&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;[[ -f $P ]]&lt;/code&gt; / &lt;code&gt;[[ -d $P ]]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;是普通文件 / 是目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;[[ -e $P ]]&lt;/code&gt; / &lt;code&gt;[[ -x $P ]]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;存在 / 可执行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;[[ $A -nt $B ]]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A 比 B 新&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;数字比较和字符串比较的符号是两套，混用是新手常见错误：&lt;code&gt;[[ 10 == 010 ]]&lt;/code&gt; 按字符串比是不相等，&lt;code&gt;[[ 10 -eq 010 ]]&lt;/code&gt; 按数字比——注意 &lt;code&gt;-eq&lt;/code&gt; 还会把 &lt;code&gt;010&lt;/code&gt; 当八进制解析，结果更出人意料。日常脚本里数字比较老老实实用 &lt;code&gt;-eq&lt;/code&gt; 系列，比较的字符串别带前导零。&lt;/p&gt;
&lt;h3&gt;4.4 if 与 case&lt;/h3&gt;
&lt;p&gt;多分支判断，值少而明确时用 &lt;code&gt;case&lt;/code&gt; 比一串 &lt;code&gt;elif&lt;/code&gt; 清爽得多，服务管理脚本里很常见：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ACTION=&quot;${1:-}&quot;

case &quot;$ACTION&quot; in
    start)
        echo &quot;启动服务&quot;
        ;;
    stop)
        echo &quot;停止服务&quot;
        ;;
    *)
        echo &quot;用法：$0 {start|stop}&quot; &amp;gt;&amp;amp;2
        exit 1
        ;;
esac
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;${1:-}&lt;/code&gt; 这个写法：它表示&quot;如果 &lt;code&gt;$1&lt;/code&gt; 未定义就用空字符串&quot;。在开了 &lt;code&gt;set -u&lt;/code&gt; 的脚本里，直接引用不存在的 &lt;code&gt;$1&lt;/code&gt; 会当场报错退出，用这个默认值写法可以安全地处理&quot;没传参数&quot;的情况，这是 &lt;code&gt;set -u&lt;/code&gt; 配套的基本功。&lt;/p&gt;
&lt;h2&gt;五、循环：遍历与逐行读取&lt;/h2&gt;
&lt;h3&gt;5.1 for 遍历列表&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;for SVC in nginx mysql redis; do
    echo &quot;检查服务：$SVC&quot;
done
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;遍历文件时让通配符来展开，不要去解析 &lt;code&gt;ls&lt;/code&gt; 的输出：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;for F in /var/log/myapp/*.log; do
    echo &quot;处理：$F&quot;
done
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;解析 &lt;code&gt;ls&lt;/code&gt; 输出在文件名带空格时必然翻车，而通配符展开是 Shell 原生机制，每个文件名都是独立的一项，天然安全。&lt;/p&gt;
&lt;h3&gt;5.2 while 逐行读文件&lt;/h3&gt;
&lt;p&gt;逐行处理文件内容（比如一份服务器清单）用 &lt;code&gt;while read&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;while IFS= read -r LINE; do
    [[ -z &quot;$LINE&quot; ]] &amp;amp;&amp;amp; continue
    echo &quot;读取到：$LINE&quot;
done &amp;lt; hosts.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三个细节缺一不可：&lt;code&gt;IFS=&lt;/code&gt; 防止行首行尾空白被吃掉，&lt;code&gt;-r&lt;/code&gt; 防止反斜杠被当转义，输入重定向 &lt;code&gt;&amp;lt; hosts.txt&lt;/code&gt; 让循环在本 Shell 里运行。反例是用管道 &lt;code&gt;cat hosts.txt | while ...&lt;/code&gt;，管道会让循环体跑在子 Shell 里，循环里改的变量出了循环就消失，是经典的隐形坑。&lt;/p&gt;
&lt;p&gt;循环控制就两个词：&lt;code&gt;break&lt;/code&gt; 跳出整个循环，&lt;code&gt;continue&lt;/code&gt; 跳过本轮进入下一轮。&lt;/p&gt;
&lt;h2&gt;六、函数：把重复段落收起来&lt;/h2&gt;
&lt;p&gt;函数的基本形态：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;is_running() {
    local svc=&quot;$1&quot;
    systemctl is-active --quiet &quot;$svc&quot;
}

if is_running nginx; then
    echo &quot;nginx 正常&quot;
fi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三个要点：&lt;/p&gt;
&lt;p&gt;第一，函数没有形参声明，靠 &lt;code&gt;$1&lt;/code&gt;、&lt;code&gt;$2&lt;/code&gt; 读传入的参数，和脚本读参数是同一套机制。第二，&lt;code&gt;local&lt;/code&gt; 声明的变量只在函数内有效，不加 &lt;code&gt;local&lt;/code&gt; 就是全局变量，函数里随手用的计数器污染全局是常见 bug 源，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;函数内的变量一律加 local&amp;lt;/span&amp;gt;。第三，也是最反直觉的一点：&lt;code&gt;return&lt;/code&gt; 只能返回 0 到 255 的数字，它返回的是&quot;状态&quot;而不是&quot;数据&quot;。想让函数产出一个字符串结果，惯例是用 &lt;code&gt;echo&lt;/code&gt; 输出、调用方用命令替换接住：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;today_dir() {
    echo &quot;/data/backup/$(date +%F)&quot;
}

DIR=&quot;$(today_dir)&quot;
echo &quot;备份目录：$DIR&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;七、实战脚本一：批量巡检&lt;/h2&gt;
&lt;p&gt;需求：检查一组关键服务的运行状态，逐个输出结果，最后给一个汇总。把前面几节的东西全用上：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
set -euo pipefail

SERVICES=(nginx mysql redis-server)
FAIL_COUNT=0

check_one() {
    local svc=&quot;$1&quot;
    if systemctl is-active --quiet &quot;$svc&quot;; then
        echo &quot;[OK]   $svc 正在运行&quot;
        return 0
    else
        echo &quot;[FAIL] $svc 未运行&quot;
        return 1
    fi
}

for SVC in &quot;${SERVICES[@]}&quot;; do
    if ! check_one &quot;$SVC&quot;; then
        FAIL_COUNT=$((FAIL_COUNT + 1))
    fi
done

echo &quot;----&quot;
echo &quot;共检查 ${#SERVICES[@]} 个服务，异常 $FAIL_COUNT 个&quot;

if [[ $FAIL_COUNT -gt 0 ]]; then
    exit 1
fi
exit 0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐段拆解：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;SERVICES=(...)&lt;/code&gt; 是 Bash 数组，遍历时写 &lt;code&gt;&quot;${SERVICES[@]}&quot;&lt;/code&gt; 表示逐个元素展开，&lt;code&gt;${#SERVICES[@]}&lt;/code&gt; 是元素个数。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;check_one&lt;/code&gt; 函数内部用 &lt;code&gt;if !&lt;/code&gt; 包裹调用：因为函数是在条件上下文里被调用的，&lt;code&gt;set -e&lt;/code&gt; 不会因为某个服务没运行就把脚本掐断，我们才能把所有服务都检查完再汇总。这正是前面 warning 里说的&quot;&lt;code&gt;set -e&lt;/code&gt; 在条件里不触发&quot;的那条规则的正当用法。&lt;/li&gt;
&lt;li&gt;脚本最后根据异常数决定退出码：有异常就 &lt;code&gt;exit 1&lt;/code&gt;。这一步至关重要——巡检脚本大多被 cron 调用，退出码非零才能触发上层告警（比如 cron 的邮件通知），只打印一行红字却退出 0，等于把报警器拆了。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;八、实战脚本二：日志清理&lt;/h2&gt;
&lt;p&gt;需求：删除指定日志目录下 14 天以前的 &lt;code&gt;.log&lt;/code&gt; 文件。这类脚本最能体现&quot;先演练再真删&quot;的纪律，我们分两步写。&lt;/p&gt;
&lt;p&gt;第一步永远是演练版——只找出来打印，绝不删除：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
set -euo pipefail

LOG_DIR=&quot;/var/log/myapp&quot;
KEEP_DAYS=14

find &quot;$LOG_DIR&quot; -type f -name &quot;*.log&quot; -mtime +&quot;$KEEP_DAYS&quot; -print
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;人工确认打印出来的列表无误——路径对不对、有没有混进不该删的文件、数量是否符合预期——之后才把 &lt;code&gt;-print&lt;/code&gt; 换成删除动作，写成正式版：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
set -euo pipefail

LOG_DIR=&quot;/var/log/myapp&quot;
KEEP_DAYS=14

COUNT=&quot;$(find &quot;$LOG_DIR&quot; -type f -name &quot;*.log&quot; -mtime +&quot;$KEEP_DAYS&quot; | wc -l)&quot;
echo &quot;将清理 $COUNT 个超过 $KEEP_DAYS 天的日志文件&quot;

find &quot;$LOG_DIR&quot; -type f -name &quot;*.log&quot; -mtime +&quot;$KEEP_DAYS&quot; -delete

echo &quot;清理完成，当前磁盘使用情况：&quot;
df -h &quot;$LOG_DIR&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
删除类脚本上线前，必须逐字核查两个东西：一是目录变量的值，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;变量为空时拼出的路径可能退化成对根目录或当前目录动手&amp;lt;/span&amp;gt;，正式脚本应在开头加一句 &lt;code&gt;[[ -d &quot;$LOG_DIR&quot; ]] || exit 1&lt;/code&gt; 的存在性校验；二是 &lt;code&gt;find&lt;/code&gt; 的起点和条件，起点写错一位、条件少写一个，删除范围就会整体偏移。先 &lt;code&gt;-print&lt;/code&gt; 演练、再 &lt;code&gt;-delete&lt;/code&gt; 执行，这一步永远不要省。
:::&lt;/p&gt;
&lt;p&gt;顺手补上那句校验，脚本开头应该是：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[[ -d &quot;$LOG_DIR&quot; ]] || { echo &quot;目录不存在：$LOG_DIR&quot; &amp;gt;&amp;amp;2; exit 1; }
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;另外说明一句：系统级的日志轮转有专门的 &lt;code&gt;logrotate&lt;/code&gt; 在管（日志管理篇里讲过），自己写清理脚本针对的是应用自己吐的、不在 logrotate 管辖内的日志，两者不要混着来。&lt;/p&gt;
&lt;h2&gt;九、调试：脚本不报错但结果不对时怎么办&lt;/h2&gt;
&lt;p&gt;脚本跑通了但结果不对，按这个顺序排查：&lt;/p&gt;
&lt;p&gt;第一招是 &lt;code&gt;bash -x&lt;/code&gt;，把每条命令展开后的实际执行过程打印出来，变量到底变成了什么一清二楚：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;bash -x clean.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;也可以在脚本里局部开启：出问题那一段前后加 &lt;code&gt;set -x&lt;/code&gt; 和 &lt;code&gt;set +x&lt;/code&gt;，只追踪局部，输出不会被淹没。&lt;/p&gt;
&lt;p&gt;第二招是最原始的 echo 大法：在关键节点打印变量值。位置选择有讲究——打印在判断之前看&quot;输入&quot;，打印在判断之后看&quot;结论&quot;，两相对照就知道是数据错了还是逻辑错了。&lt;/p&gt;
&lt;p&gt;第三招是装一个 &lt;code&gt;shellcheck&lt;/code&gt;，它能静态检查出未加引号的变量展开、&lt;code&gt;$*&lt;/code&gt; 误用等一大批经典问题，写完脚本先让它扫一遍，能省掉很多低级错误：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;shellcheck clean.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;十、脚本与交互环境的差异：本地好好的，cron 里就失败&lt;/h2&gt;
&lt;p&gt;这是脚本类故障里最高频的一类：脚本在终端里手动跑完全正常，交给 cron 就失败，或者反过来。根源在于两者的运行环境根本不是一回事。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;差异点&lt;/th&gt;
&lt;th&gt;交互终端&lt;/th&gt;
&lt;th&gt;cron 等调度环境&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;环境变量&lt;/td&gt;
&lt;td&gt;登录时加载了一整套&lt;/td&gt;
&lt;td&gt;只有极少数几个&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;PATH&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;包含 &lt;code&gt;/usr/local/bin&lt;/code&gt; 等完整路径&lt;/td&gt;
&lt;td&gt;通常只有 &lt;code&gt;/usr/bin:/bin&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;别名与函数&lt;/td&gt;
&lt;td&gt;&lt;code&gt;.bashrc&lt;/code&gt; 里的别名、函数都可用&lt;/td&gt;
&lt;td&gt;完全不存在&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;当前目录&lt;/td&gt;
&lt;td&gt;你登录后所在目录&lt;/td&gt;
&lt;td&gt;一般是家目录，未必是脚本所在目录&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;结论很直接：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;脚本里不要依赖别名、不要依赖 .bashrc 的任何东西，关键命令写绝对路径，脚本开头先 cd 到自己所在目录&amp;lt;/span&amp;gt;。需要用到的环境变量，在脚本里显式写死或从配置文件读，不要指望环境里&quot;应该有&quot;。&lt;/p&gt;
&lt;p&gt;交给 cron 之前，用 &lt;code&gt;env -i&lt;/code&gt; 模拟一个干净环境先跑一遍，这是最有效的预检：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;env -i /bin/bash /opt/scripts/check.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;能在这个&quot;什么都没有&quot;的环境里跑通，放到 cron 里基本就稳了。cron 的具体配置、定时表达式和 systemd timer 的取舍，见 &lt;a href=&quot;/posts/linux-cron-timers/&quot;&gt;定时任务：cron 与 systemd timer&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;十一、排障速查&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;现象&lt;/th&gt;
&lt;th&gt;常见原因&lt;/th&gt;
&lt;th&gt;处理&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;变量莫名其妙是空的&lt;/td&gt;
&lt;td&gt;变量名拼错；或在管道子 Shell 里赋值&lt;/td&gt;
&lt;td&gt;开 &lt;code&gt;set -u&lt;/code&gt; 让未定义变量当场报错；改用重定向喂 while&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;报错 &lt;code&gt;syntax error near unexpected token&lt;/code&gt; 或满屏 &lt;code&gt;$&apos;\r&apos;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;文件是 Windows 的 CRLF 换行&lt;/td&gt;
&lt;td&gt;用 &lt;code&gt;dos2unix&lt;/code&gt; 转换，或编辑器改成 LF&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;./xxx.sh: Permission denied&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;没加可执行权限&lt;/td&gt;
&lt;td&gt;&lt;code&gt;chmod +x&lt;/code&gt;，或用 &lt;code&gt;bash xxx.sh&lt;/code&gt; 临时跑&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;报错 &lt;code&gt;bad interpreter: No such file or directory&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;shebang 路径写错，或 CRLF 导致解释器名带 &lt;code&gt;\r&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;检查第一行；先按换行问题排查&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;手动跑正常、cron 里失败&lt;/td&gt;
&lt;td&gt;环境差异：&lt;code&gt;PATH&lt;/code&gt;、别名、当前目录&lt;/td&gt;
&lt;td&gt;按第十节逐项对，&lt;code&gt;env -i&lt;/code&gt; 预检&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;管道前半段失败却没停&lt;/td&gt;
&lt;td&gt;没开 &lt;code&gt;pipefail&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;骨架里补上 &lt;code&gt;set -o pipefail&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;其中 CRLF 那个最阴险：脚本在 Windows 上编辑过再传回服务器，第一行会变成 &lt;code&gt;#!/bin/bash\r&lt;/code&gt;，内核要找的解释器名字里多了个回车，于是报出一个驴唇不对马嘴的&quot;解释器不存在&quot;。看到 &lt;code&gt;bad interpreter&lt;/code&gt; 先查换行，十有八九就是它。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;重复三次的操作就写成脚本，图的不只是快，还有一致、留痕和可调度。&lt;/li&gt;
&lt;li&gt;骨架固定三件：&lt;code&gt;#!/bin/bash&lt;/code&gt;、&lt;code&gt;set -euo pipefail&lt;/code&gt;、注释写动机。&lt;/li&gt;
&lt;li&gt;变量展开默认加双引号，转发参数只用 &lt;code&gt;&quot;$@&quot;&lt;/code&gt;，这两条避开大半低级 bug。&lt;/li&gt;
&lt;li&gt;条件判断的本质是读退出码；&lt;code&gt;[[ ]]&lt;/code&gt; 做测试，数字和字符串用各自的比较符。&lt;/li&gt;
&lt;li&gt;函数的 &lt;code&gt;return&lt;/code&gt; 只回状态码，要产出数据用 &lt;code&gt;echo&lt;/code&gt; 加命令替换；函数内变量一律 &lt;code&gt;local&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;删除类脚本先 &lt;code&gt;-print&lt;/code&gt; 演练、核查变量与范围，再换成真删，这一步没有例外。&lt;/li&gt;
&lt;li&gt;脚本默认要跑在&quot;没有别名、没有完整 PATH&quot;的环境里，交付 cron 前先用 &lt;code&gt;env -i&lt;/code&gt; 预检。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;下一篇进入 Shell 环境与效率工具：把 &lt;code&gt;.bashrc&lt;/code&gt;、常用别名和命令行编辑技巧收拾利索，让每天敲命令的手先快起来。&lt;/p&gt;
</content:encoded></item><item><title>定时任务：cron 与 systemd timer</title><link>https://www.anexns.cloudns.org/posts/linux-cron-timers/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-cron-timers/</guid><description>让服务器自己按点干活：cron 五字段与 crontab 的用法、它与登录环境的三点差异、systemd timer 的补跑优势，以及定时任务没执行的五步排查。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;服务器上有大量工作是「到点就该干」的：凌晨备份数据库、每小时清理日志、每五分钟探一次服务还活着没有、每周生成一份报表。这些事如果靠人记着手动执行，迟早会漏、会忘、会在半夜出事时才发现昨天的备份根本没跑。定时任务系统就是为此而生的：你把「什么时间、执行什么命令」写成规则交给系统，系统按点触发，不知疲倦，也不会请假。&lt;/p&gt;
&lt;p&gt;Linux 上现在并存着两套定时体系：一套是几十年历史的老牌选手 cron，几乎所有发行版都自带，语法简单、全网教程无数；另一套是 systemd 家族的原生组件 systemd timer，它和 systemd 服务共用一套单元文件，能处理「关机错过之后要不要补跑」这类 cron 天生做不到的事。这一篇先把两套体系的区别讲清，再逐个拆 cron 的表达式与 crontab 用法——其中 cron 与登录环境的三点差异是新手翻车的头号原因，必须单独强调——然后给出 systemd timer 的完整写法和两个能直接抄的实战例子，最后是一套「任务没执行」的五步排查流程。读完你应该能独立地给任何脚本配上可靠的定时触发，并知道它没跑的时候去哪儿查。&lt;/p&gt;
&lt;h2&gt;两套体系先分清&lt;/h2&gt;
&lt;p&gt;在动手写规则之前，先建立一个整体认识：cron 和 systemd timer 解决的是同一个问题，但设计哲学不同。&lt;/p&gt;
&lt;p&gt;cron 的思路是「一张大表管所有」：每个用户有自己的 crontab 文件，系统级的任务写在 &lt;code&gt;/etc/crontab&lt;/code&gt; 和 &lt;code&gt;/etc/cron.d/&lt;/code&gt; 目录里，cron 守护进程每分钟醒来扫一遍这些表，到点了就用 &lt;code&gt;/bin/sh&lt;/code&gt; 把命令拉起来执行。它不关心你的任务是一个「服务」还是「一条命令」，也不记录任务之间的依赖关系。&lt;/p&gt;
&lt;p&gt;systemd timer 的思路是「定时器只是服务的触发器」：一个 &lt;code&gt;.timer&lt;/code&gt; 单元负责描述时间规则，到点后它去激活一个同名的 &lt;code&gt;.service&lt;/code&gt; 单元，真正的命令写在 service 里。这样定时任务就和普通服务一样，能写依赖（网络就绪后再跑）、能用 journalctl 看完整日志、能用 systemctl 查看状态和下次触发时间。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;cron&lt;/th&gt;
&lt;th&gt;systemd timer&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;配置形式&lt;/td&gt;
&lt;td&gt;crontab 文本行，一行一个任务&lt;/td&gt;
&lt;td&gt;&lt;code&gt;.timer&lt;/code&gt; + &lt;code&gt;.service&lt;/code&gt; 两个单元文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;时间语法&lt;/td&gt;
&lt;td&gt;五字段表达式（分 时 日 月 周）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;OnCalendar&lt;/code&gt; 日历表达式，可读性更好&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;关机错过&lt;/td&gt;
&lt;td&gt;直接跳过，不补跑&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Persistent=true&lt;/code&gt; 可在开机后补跑&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;执行日志&lt;/td&gt;
&lt;td&gt;默认无处可查，要自己重定向&lt;/td&gt;
&lt;td&gt;自动进 journal，&lt;code&gt;journalctl -u&lt;/code&gt; 可查&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;依赖管理&lt;/td&gt;
&lt;td&gt;没有，全靠脚本自己处理&lt;/td&gt;
&lt;td&gt;可写 &lt;code&gt;After=&lt;/code&gt;、&lt;code&gt;Requires=&lt;/code&gt; 等依赖&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;随机延迟&lt;/td&gt;
&lt;td&gt;不支持（新版本有 &lt;code&gt;RANDOM_DELAY&lt;/code&gt; 等扩展）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;RandomizedDelaySec&lt;/code&gt; 原生支持&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;查看下次执行&lt;/td&gt;
&lt;td&gt;无工具，只能自己算&lt;/td&gt;
&lt;td&gt;&lt;code&gt;systemctl list-timers&lt;/code&gt; 一览无余&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;学习成本&lt;/td&gt;
&lt;td&gt;低，十分钟上手&lt;/td&gt;
&lt;td&gt;中，要先懂 service 单元&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选型结论放在最后讲，这里先记住一句话：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;新写的任务优先考虑 systemd timer，老任务和简单场景继续用 cron 也完全没问题&amp;lt;/span&amp;gt;。两套体系可以同时跑在一台机器上，互不干扰。下面先把 cron 讲透，因为它是绕不开的基本功。&lt;/p&gt;
&lt;h2&gt;cron 表达式：五字段逐个拆&lt;/h2&gt;
&lt;p&gt;一条 cron 规则长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;分  时  日  月  周   要执行的命令
*   *   *   *   *    /path/to/command
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;五个字段从左到右分别是：分钟（0–59）、小时（0–23）、日（1–31）、月（1–12）、星期（0–7，其中 0 和 7 都代表星期日）。每个字段都支持四种写法：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;*&lt;/code&gt;：任意值，即「每一个」。分钟字段写 &lt;code&gt;*&lt;/code&gt; 就是每分钟。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;*/n&lt;/code&gt;：每隔 n 个单位。小时字段写 &lt;code&gt;*/2&lt;/code&gt; 就是每 2 小时（0、2、4……22 点）。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;a-b&lt;/code&gt;：范围。日字段写 &lt;code&gt;1-5&lt;/code&gt; 是每月 1 号到 5 号；星期字段写 &lt;code&gt;1-5&lt;/code&gt; 是周一到周五。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;a,b,c&lt;/code&gt;：列表，列举几个离散值。分钟字段写 &lt;code&gt;0,30&lt;/code&gt; 是每小时的 0 分和 30 分。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;几个字段是「同时满足」的关系，但有一个著名的例外：&lt;strong&gt;日字段和星期字段同时写了具体值时，是「或」的关系&lt;/strong&gt;。比如 &lt;code&gt;0 9 1 * 1&lt;/code&gt; 不是「每月 1 号且是周一才跑」，而是「每月 1 号跑，周一也跑」。这个坑很多人踩过，配之前先想清楚自己到底想要哪种。&lt;/p&gt;
&lt;p&gt;常用例子对照表，建议收藏：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;需求&lt;/th&gt;
&lt;th&gt;表达式&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;每分钟&lt;/td&gt;
&lt;td&gt;&lt;code&gt;* * * * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;慎用，频率太高&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每 5 分钟&lt;/td&gt;
&lt;td&gt;&lt;code&gt;*/5 * * * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;探活、状态采集常用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每小时整点&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 * * * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;分钟写 0&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每 2 小时&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 */2 * * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每天凌晨 3 点&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 3 * * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;备份常用时间&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每天凌晨 3 点半&lt;/td&gt;
&lt;td&gt;&lt;code&gt;30 3 * * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;错开整点高峰&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每周一早上 9 点&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 9 * * 1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;星期字段 1 = 周一&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每周日凌晨&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 0 * * 0&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;0 或 7 都是周日&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每月 1 号凌晨 2 点&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 2 1 * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;月度报表、账单&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;工作日下午 6 点&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 18 * * 1-5&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;范围写法&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每天 9 点和 21 点&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 9,21 * * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列表写法&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;还有一个细节：不要把所有任务都堆在整点。全网的 cron 任务都爱写 &lt;code&gt;0 * * * *&lt;/code&gt;，结果每小时整点服务器就迎来一波小高峰。把分钟错开到 7 分、13 分、37 分这类「不整」的数字，是老运维的习惯，也是对机器温柔一点的做法。&lt;/p&gt;
&lt;h2&gt;crontab 用法：个人任务与系统任务&lt;/h2&gt;
&lt;p&gt;管理个人 crontab 用三个命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;crontab -e   # 编辑当前用户的 crontab（首次会让你选编辑器）
crontab -l   # 查看当前用户的 crontab 内容
crontab -r   # 删除当前用户的整个 crontab
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;crontab -e&lt;/code&gt; 打开的是一个临时文件，保存退出后 cron 会自动加载新内容，不需要重启任何服务。文件顶部通常有注释说明格式，你只管在末尾追加自己的行。一行一个任务，空行和 &lt;code&gt;#&lt;/code&gt; 开头的注释行会被忽略。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;code&gt;crontab -r&lt;/code&gt; 是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不经确认直接删光整个 crontab&amp;lt;/span&amp;gt;的，而且 &lt;code&gt;-r&lt;/code&gt; 和 &lt;code&gt;-e&lt;/code&gt; 在键盘上紧挨着，手滑按错就是一场事故。养成习惯：编辑前先 &lt;code&gt;crontab -l &amp;gt; ~/crontab.bak&lt;/code&gt; 备份一份，真删错了还能用 &lt;code&gt;crontab ~/crontab.bak&lt;/code&gt; 恢复。
:::&lt;/p&gt;
&lt;p&gt;系统级任务有另外两个位置，写法和个人 crontab 有一处关键区别——&lt;strong&gt;多一个用户字段&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# /etc/crontab 或 /etc/cron.d/ 下的文件，格式是：
# 分 时 日 月 周  用户  命令
15 4 * * * root /usr/local/bin/cleanup.sh

# 而个人 crontab 里没有用户字段：
15 4 * * * /usr/local/bin/cleanup.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把系统级的行原样粘进个人 crontab，cron 会把用户名当成命令的一部分去执行，然后报错或静默失败；反过来把个人格式写进 &lt;code&gt;/etc/cron.d/&lt;/code&gt;，则会把命令的第一个词当用户名。两个位置二选一，别混。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;/etc/cron.d/&lt;/code&gt; 目录适合「一个软件一个文件」的组织方式：文件名就是任务名（注意文件名不能带点号等某些字符，否则会被忽略），文件权限要正确，属主为 root。发行版自带的很多任务就放在这里，比如日志轮转。相比之下，直接改 &lt;code&gt;/etc/crontab&lt;/code&gt; 的人越来越少，除非你就是想把全系统的任务集中在一处看。&lt;/p&gt;
&lt;p&gt;另外 &lt;code&gt;/etc/cron.daily/&lt;/code&gt;、&lt;code&gt;/etc/cron.weekly/&lt;/code&gt;、&lt;code&gt;/etc/cron.monthly/&lt;/code&gt; 这几个目录是更粗粒度的老机制：把可执行脚本丢进去，系统每天/每周/每月自动跑一遍，具体时刻由系统配置决定，精度不如 crontab，胜在零配置。临时性的清理脚本可以考虑，精确到点的任务别用它。&lt;/p&gt;
&lt;h2&gt;特殊时间字符串：@daily 与 @reboot&lt;/h2&gt;
&lt;p&gt;cron 还支持几个以 &lt;code&gt;@&lt;/code&gt; 开头的简写，代替五字段：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;简写&lt;/th&gt;
&lt;th&gt;等价表达式&lt;/th&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@hourly&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 * * * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每小时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@daily&lt;/code&gt;（同 &lt;code&gt;@midnight&lt;/code&gt;）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 0 * * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每天零点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@weekly&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 0 * * 0&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每周日零点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@monthly&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 0 1 * *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每月 1 号零点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@yearly&lt;/code&gt;（同 &lt;code&gt;@annually&lt;/code&gt;）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0 0 1 1 *&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每年 1 月 1 号&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@reboot&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;开机时执行一次&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;写法是简写直接打头：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;@daily /usr/local/bin/backup.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;@reboot&lt;/code&gt; 看起来很美——开机自动拉起某个脚本——但要提醒一句：它在不同实现里的可靠性参差不齐，有的 cron 版本对它支持不完整，而且它无法表达「等网络就绪之后」这类条件。开机自启的需求，正经做法是写一个 systemd service 并 enable，依赖和状态都可控；&lt;code&gt;@reboot&lt;/code&gt; 只适合无所谓的临时小事，不要把关键任务托付给它。&lt;/p&gt;
&lt;h2&gt;头号大坑：cron 的环境和登录终端完全不同&lt;/h2&gt;
&lt;p&gt;「脚本我手动跑得好好的，一放进 cron 就失败」——这是定时任务领域排名第一的故障，根源几乎都在环境差异。cron 执行命令时用的不是你登录后的 Shell 环境，而是一个被刻意精简过的环境，主要有三点差异，每一点都能单独让任务翻车。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一，PATH 非常短。&lt;/strong&gt; 登录终端里你的 PATH 通常包含 &lt;code&gt;/usr/local/bin&lt;/code&gt;、家目录下的 bin 等一长串路径，而 cron 给的 PATH 一般只有 &lt;code&gt;/usr/bin:/bin&lt;/code&gt;。后果是：你在脚本里直接写 &lt;code&gt;docker&lt;/code&gt;、&lt;code&gt;python3&lt;/code&gt;、&lt;code&gt;rsync&lt;/code&gt;，手动跑没问题，cron 里可能报 &lt;code&gt;command not found&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二，没有登录环境变量。&lt;/strong&gt; 你 &lt;code&gt;.bashrc&lt;/code&gt;、&lt;code&gt;.profile&lt;/code&gt; 里导出的变量（比如某个 API 的密钥、语言设置、代理地址），cron 环境里统统不存在。脚本依赖这些变量时，行为会和手动执行完全不同，而且报错信息往往很隐晦。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三，工作目录是家目录。&lt;/strong&gt; cron 执行时当前目录是该用户的家目录，不是脚本所在目录。脚本里如果用了相对路径读配置文件、写输出文件，手动在脚本目录里跑一切正常，cron 里就会去家目录找，当然找不到。&lt;/p&gt;
&lt;p&gt;应对方法就三条，写进每一个要上 cron 的脚本里：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
# 1. 命令写绝对路径，或者在脚本开头自己补 PATH
export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

# 2. 需要的环境变量在脚本里显式声明，不要指望登录环境
export LANG=C.UTF-8

# 3. 第一件事先 cd 到脚本所在目录，相对路径才靠谱
cd &quot;$(dirname &quot;$0&quot;)&quot; || exit 1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;还有两个隐蔽的点顺带提一下：cron 默认用 &lt;code&gt;/bin/sh&lt;/code&gt; 执行命令，而 Debian 上 &lt;code&gt;/bin/sh&lt;/code&gt; 是 dash 不是 bash，脚本里如果用了 bash 专属语法（数组、&lt;code&gt;[[ ]]&lt;/code&gt; 等），直接写在 crontab 行里会翻车——解决办法是把逻辑都放进带 &lt;code&gt;#!/bin/bash&lt;/code&gt; 解释器声明的脚本文件，crontab 里只写脚本路径；另外 crontab 行里的 &lt;code&gt;%&lt;/code&gt; 是特殊字符，会被当成换行处理，命令里需要百分号（比如 &lt;code&gt;date +%F&lt;/code&gt;）时要写成 &lt;code&gt;\%&lt;/code&gt;，这也是个经典小坑。&lt;/p&gt;
&lt;h2&gt;输出去哪了：日志与通知&lt;/h2&gt;
&lt;p&gt;cron 本身不保存任务的输出。命令的标准输出和标准错误默认会尝试通过本地邮件发给任务属主（就是 crontab 里的 &lt;code&gt;MAILTO&lt;/code&gt; 变量指定的地址，默认是属主本人）。但绝大多数服务器根本没配本地邮件投递，这些输出就直接消失了——任务失败时你连报错都看不到。&lt;/p&gt;
&lt;p&gt;所以上生产环境的 cron 行，标准做法是把输出重定向到日志文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 追加写入日志，标准输出和错误一起记
0 3 * * * /usr/local/bin/backup.sh &amp;gt;&amp;gt; /var/log/backup.log 2&amp;gt;&amp;amp;1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;&amp;gt;&amp;gt;&lt;/code&gt; 是追加（用 &lt;code&gt;&amp;gt;&lt;/code&gt; 覆盖的话每次只剩最后一次的日志，排障时就没历史可看了），&lt;code&gt;2&amp;gt;&amp;amp;1&lt;/code&gt; 表示把标准错误也合并到同一个文件。日志文件记得纳入日志轮转（logrotate）的范围，别让它无限长大把磁盘吃满，具体做法可以参考本系列的日志管理篇。&lt;/p&gt;
&lt;p&gt;想确认 cron 到底有没有触发过某条任务，可以查系统日志。在 Debian 上，cron 的活动记录在 journal 里：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 看 cron 服务本身的日志（包含每条任务的启动记录）
journalctl -u cron --since today

# 按关键词过滤某个任务
journalctl -u cron | grep backup
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意不同发行版的服务名和日志位置并不一致：Debian/Ubuntu 系服务名是 &lt;code&gt;cron&lt;/code&gt;，日志也可以在 &lt;code&gt;/var/log/cron&lt;/code&gt; 或 syslog 里找到（视 rsyslog 配置而定）；RHEL 系服务名叫 &lt;code&gt;crond&lt;/code&gt;，日志默认在 &lt;code&gt;/var/log/cron&lt;/code&gt;。跨发行版操作时先确认服务名，不要把一边的经验硬套到另一边。至于任务自己产生的业务日志，还是以重定向的那个文件为准——系统日志只记录「几点几分启动了这条命令」，不记录命令内部发生了什么。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;MAILTO&lt;/code&gt; 如果确实配好了邮件系统，可以设成你的邮箱，任务有输出时自动发信。但在今天的环境里，更常见的做法是输出全部进日志、失败告警走监控系统，&lt;code&gt;MAILTO=&quot;&quot;&lt;/code&gt;（设为空）明确关掉发信尝试，省得日志里多一堆投递失败的噪音。&lt;/p&gt;
&lt;h2&gt;systemd timer：补跑是它的杀手锏&lt;/h2&gt;
&lt;p&gt;systemd timer 由两个文件组成：&lt;code&gt;.service&lt;/code&gt; 描述「干什么」，&lt;code&gt;.timer&lt;/code&gt; 描述「什么时候干」。以一个每五分钟探活的任务为例，service 这样写：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# /etc/systemd/system/healthcheck.service
[Unit]
Description=Health check for web service
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/healthcheck.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意它没有 &lt;code&gt;[Install]&lt;/code&gt; 段——因为它不靠 enable 自启，而是被 timer 拉起来。timer 文件与 service 同名、只改后缀：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# /etc/systemd/system/healthcheck.timer
[Unit]
Description=Run healthcheck every 5 minutes

[Timer]
OnBootSec=2min
OnUnitActiveSec=5min
Persistent=true

[Install]
WantedBy=timers.target
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个关键字段：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;OnCalendar&lt;/code&gt;：日历表达式，是最常用的触发方式，语法比 cron 五字段可读得多，比如 &lt;code&gt;OnCalendar=*-*-* 03:00:00&lt;/code&gt; 是每天凌晨 3 点，&lt;code&gt;OnCalendar=Mon *-*-* 09:00:00&lt;/code&gt; 是每周一 9 点，&lt;code&gt;OnCalendar=*-*-01 02:00:00&lt;/code&gt; 是每月 1 号凌晨 2 点。写完可以用 &lt;code&gt;systemd-analyze calendar &quot;*-*-* 03:00:00&quot;&lt;/code&gt; 验证表达式并看下一次触发时间。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;OnBootSec&lt;/code&gt; / &lt;code&gt;OnUnitActiveSec&lt;/code&gt;：相对时间触发，前者是开机后多久，后者是上次激活后隔多久，组合起来就是「开机 2 分钟后跑第一次，之后每 5 分钟一次」。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;Persistent=true&lt;/code&gt;：这是 timer 相对 cron 最大的优势。如果预定触发时刻机器是关着的（或者服务没在跑），&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;cron 会把这次执行直接丢掉&amp;lt;/span&amp;gt;，而开了 Persistent 的 timer 会在下次开机/启动时立刻补跑一次。凌晨 3 点的备份任务，机器 2 点半到 4 点在维护重启，cron 的备份就没了，timer 的备份会在开机后补上——对备份这类「宁可晚、不能无」的任务，这个区别是决定性的。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;RandomizedDelaySec&lt;/code&gt;：在触发时间上叠加一个随机延迟，比如设 &lt;code&gt;10min&lt;/code&gt; 就是准点之后 0–10 分钟内随机启动，适合给一批机器错峰，减轻对端服务的瞬时压力。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;启用和管理：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 改完单元文件先重载
systemctl daemon-reload

# 启用并立即启动这个 timer
systemctl enable --now healthcheck.timer

# 查看所有 timer 及下次/上次触发时间——排障神器
systemctl list-timers

# 只看某个任务
systemctl list-timers healthcheck.timer

# 手动触发一次它关联的 service（测试用）
systemctl start healthcheck.service

# 看这个任务的执行日志
journalctl -u healthcheck.service
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;选型结论：任务需要补跑、需要依赖管理、需要完整日志、或者你想随时一眼看到「下次几点跑、上次跑没跑」，用 systemd timer；任务很简单、机器常年不关机、或者脚本要跨发行版到处搬，用 cron 更省事。两者不是替代关系，同一台机器上完全可以混用。&lt;/p&gt;
&lt;h2&gt;实战二例&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;例子一：每天凌晨 3 点半备份，用 cron。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;先准备好备份脚本 &lt;code&gt;/usr/local/bin/backup.sh&lt;/code&gt;（加可执行权限，脚本内部按前文把 PATH、变量、&lt;code&gt;cd&lt;/code&gt; 都处理好），然后 &lt;code&gt;crontab -e&lt;/code&gt; 加一行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;30 3 * * * /usr/local/bin/backup.sh &amp;gt;&amp;gt; /var/log/backup.log 2&amp;gt;&amp;amp;1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;选 3 点半而不是 3 点整，是为了避开整点扎堆。保存后 &lt;code&gt;crontab -l&lt;/code&gt; 确认内容无误，第二天早上看 &lt;code&gt;/var/log/backup.log&lt;/code&gt; 验证首跑结果。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;例子二：每 5 分钟探活，用 systemd timer。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;就是上一节的 &lt;code&gt;healthcheck.service&lt;/code&gt; + &lt;code&gt;healthcheck.timer&lt;/code&gt; 那一对文件：service 里 &lt;code&gt;ExecStart&lt;/code&gt; 指向探活脚本，timer 里 &lt;code&gt;OnBootSec=2min&lt;/code&gt; 保证开机后很快跑第一次，&lt;code&gt;OnUnitActiveSec=5min&lt;/code&gt; 维持五分钟的节奏，&lt;code&gt;Persistent=true&lt;/code&gt; 保证错过必补。&lt;code&gt;systemctl enable --now healthcheck.timer&lt;/code&gt; 之后，用 &lt;code&gt;systemctl list-timers&lt;/code&gt; 确认它出现在列表里且 NEXT 一列有时间，这事就算配完了。探活脚本内部的逻辑（请求哪个地址、失败几次算故障、怎么告警）不在定时系统的职责范围内，由脚本自己负责。&lt;/p&gt;
&lt;h2&gt;排障五步：任务没执行时按这个顺序查&lt;/h2&gt;
&lt;p&gt;定时任务没跑或者跑失败了，不要乱猜，按下面五步从外到内逐层缩小范围，每一步都能排除一大类原因。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步：确认调度器本身活着。&lt;/strong&gt; cron 任务先查服务状态：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl status cron        # Debian/Ubuntu
# RHEL 系是 systemctl status crond
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;服务没启，后面都不用查了，先把它拉起来并设为开机自启。timer 任务则先看 &lt;code&gt;systemctl list-timers&lt;/code&gt; 里有没有你这条、NEXT 列是不是空的——不在列表里说明 timer 根本没被 enable。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二步：验证时间表达式没写错。&lt;/strong&gt; cron 的五字段手算容易出错，尤其是日与星期的「或」关系、月份天数这类边界。把表达式丢进任意一个 cron 表达式在线校验工具，看它给出的「接下来五次执行时间」是否符合你的预期；timer 的 &lt;code&gt;OnCalendar&lt;/code&gt; 用 &lt;code&gt;systemd-analyze calendar&lt;/code&gt; 就地验证。预期不对，就是表达式的问题，改对再往下走。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三步：手动能跑、cron 不能跑——逐项对环境。&lt;/strong&gt; 这是最常见的一类。把前面讲的三点差异逐项核对：命令是不是都写了绝对路径、脚本依赖的环境变量是不是在脚本里自带、工作目录假设是否成立。有一个屡试不爽的定位办法：在 crontab 里临时加一条把环境 dump 出来的任务，&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;* * * * * env &amp;gt; /tmp/cron-env.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;一分钟后看 &lt;code&gt;/tmp/cron-env.txt&lt;/code&gt;，cron 环境的真实样子一目了然，和你登录终端里 &lt;code&gt;env&lt;/code&gt; 的输出对比，缺什么补什么。查完记得删掉这条临时任务。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第四步：查权限与属主。&lt;/strong&gt; 脚本文件有没有可执行权限（&lt;code&gt;ls -l&lt;/code&gt; 看 x 位）、属主是不是任务所属用户、脚本要读写的目录和文件该用户有没有权限、&lt;code&gt;/etc/cron.d/&lt;/code&gt; 下的文件属主必须是 root 且权限不能过宽（组/其他用户可写会被 cron 拒绝加载）。还有一类隐形权限问题：脚本在 root 的 crontab 里能跑、换成普通用户就失败，往往就是栽在这里。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第五步：在日志里找执行痕迹。&lt;/strong&gt; 先确认「有没有被触发」：&lt;code&gt;journalctl -u cron --since &quot;1 hour ago&quot;&lt;/code&gt;（或对应发行版的日志文件）里找任务的启动记录。完全没有记录，问题在调度层——回头查第一、二步；有启动记录但任务没效果，问题在脚本内部——看你重定向的那个业务日志文件，timer 任务直接 &lt;code&gt;journalctl -u 任务名.service&lt;/code&gt; 看完整输出。把「没触发」和「触发了但失败」分开，是排障不绕弯路的关键。&lt;/p&gt;
&lt;p&gt;:::warning
排障时最忌讳的是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;同时改好几处再等下一轮&amp;lt;/span&amp;gt;：表达式、路径、权限一股脑全改了，就算任务跑起来你也不知道是哪儿的毛病，下次还会再犯。一次只改一个变量，改完手动触发或等一轮验证，确认生效再动下一处。
:::&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇把两套定时体系都过了一遍，最后收束成几条可直接执行的结论：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;cron 胜在简单通用，systemd timer 胜在补跑、依赖和日志；&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;关键任务（尤其备份）优先用带 Persistent 的 timer&amp;lt;/span&amp;gt;，简单任务用 cron 没毛病，两者可以混用。&lt;/li&gt;
&lt;li&gt;cron 五字段里，日与星期同时写具体值是「或」关系；任务别都堆在整点。&lt;/li&gt;
&lt;li&gt;个人 crontab 没有用户字段，&lt;code&gt;/etc/crontab&lt;/code&gt; 和 &lt;code&gt;/etc/cron.d/&lt;/code&gt; 有，两个格式不要混；&lt;code&gt;crontab -r&lt;/code&gt; 删前先备份。&lt;/li&gt;
&lt;li&gt;「手动能跑、cron 不能跑」的病根是环境三差异：PATH 短、无登录变量、工作目录是家目录。脚本里补 PATH、显式声明变量、开头先 &lt;code&gt;cd&lt;/code&gt;，三招解决九成问题。&lt;/li&gt;
&lt;li&gt;cron 任务一律把输出重定向进日志文件并纳入轮转，否则失败了连报错都找不到。&lt;/li&gt;
&lt;li&gt;任务没执行时按五步查：调度器状态 → 表达式校验 → 环境对比 → 权限属主 → 日志找痕迹，先分清「没触发」还是「触发后失败」。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>磁盘与分区管理实战</title><link>https://www.anexns.cloudns.org/posts/linux-disk-management/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-disk-management/</guid><description>磁盘满了先别慌：看清分区与挂载、云盘扩容的完整流程、fstab 写错开不了机的避坑、inode 耗尽这个隐形杀手，以及定位大文件与大目录的标准手法。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;服务器运维里最常见、也最容易把人吓出一身汗的报警，就是磁盘满了：网站打不开、数据库写不进、SSH 登上去敲什么都报错。更麻烦的是，磁盘问题往往不是一种病——可能是真没空间了，可能是云盘扩了容系统却没认，可能是 inode 先耗尽，也可能只是一行 fstab 写错导致下次重启直接进不去系统。&lt;/p&gt;
&lt;p&gt;本篇就把磁盘这件事一次讲透：先学会看清一块盘的家底，再走通云盘扩容和新盘挂载两个最常用的流程，然后专节讲 inode 这个隐形杀手，最后给一套定位空间去向的标准手法和排障清单。全程以 Debian 为例，命令都可以直接复制执行。&lt;/p&gt;
&lt;h2&gt;一、先看清家底：设备、分区、文件系统、挂载点&lt;/h2&gt;
&lt;p&gt;动手之前先理清四个概念，后面所有命令都是围绕它们转的：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;概念&lt;/th&gt;
&lt;th&gt;是什么&lt;/th&gt;
&lt;th&gt;例子&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;设备（块设备）&lt;/td&gt;
&lt;td&gt;物理或虚拟的整块盘&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/dev/vda&lt;/code&gt;、&lt;code&gt;/dev/sdb&lt;/code&gt;、&lt;code&gt;/dev/nvme0n1&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;分区&lt;/td&gt;
&lt;td&gt;把一块盘切出来的区段&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/dev/vda1&lt;/code&gt;、&lt;code&gt;/dev/sdb2&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件系统&lt;/td&gt;
&lt;td&gt;分区上组织数据的格式&lt;/td&gt;
&lt;td&gt;ext4、XFS、vfat&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;挂载点&lt;/td&gt;
&lt;td&gt;文件系统接入目录树的入口&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/&lt;/code&gt;、&lt;code&gt;/data&lt;/code&gt;、&lt;code&gt;/boot/efi&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;关系是一条链：&lt;strong&gt;设备 → 切分区 → 在分区上建文件系统 → 挂载到某个目录&lt;/strong&gt;。日常排查用三个命令，分别回答三个问题：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 盘和分区的结构长什么样
lsblk

# 带文件系统类型和容量一起看
lsblk -f

# 每个挂载点还剩多少空间
df -h

# 现在都挂了哪些文件系统
mount | grep ^/dev
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;lsblk&lt;/code&gt; 看&lt;strong&gt;结构&lt;/strong&gt;：哪块盘、多大、切了几个分区、每个分区挂在哪。扩容前后对比全靠它。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;lsblk -f&lt;/code&gt; 多看两列关键信息：&lt;code&gt;FSTYPE&lt;/code&gt; 是文件系统类型（决定扩容用哪条命令），&lt;code&gt;UUID&lt;/code&gt; 是分区的唯一标识（写 fstab 时要用它）。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;df -h&lt;/code&gt; 看&lt;strong&gt;用量&lt;/strong&gt;：每个挂载点的总容量、已用、可用和使用率。注意它看的是文件系统层面的用量，和 &lt;code&gt;lsblk&lt;/code&gt; 看到的分区大小对不上时，往往就是「分区扩了、文件系统没扩」。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;mount&lt;/code&gt; 看&lt;strong&gt;当前实际挂载状态&lt;/strong&gt;：fstab 写的是「希望怎么挂」，&lt;code&gt;mount&lt;/code&gt; 显示的是「实际挂成了什么样」，两者不一致就是问题所在。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;举个实际例子。一台典型的云服务器执行 &lt;code&gt;lsblk -f&lt;/code&gt;，输出大致是这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;NAME    FSTYPE  SIZE  MOUNTPOINT  UUID
vda             100G
└─vda1  ext4     40G  /           3f8a1c2e-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;读法是：整块盘 &lt;code&gt;vda&lt;/code&gt; 有 100 GB，但它唯一的分区 &lt;code&gt;vda1&lt;/code&gt; 只切了 40 GB，文件系统是 ext4，挂在根目录。这正是云盘扩容最常见的中间状态——盘买大了、分区没跟上，后面第二节讲的就是怎么把这 60 GB 补回来。反过来，如果 &lt;code&gt;lsblk&lt;/code&gt; 里分区已经是 100 GB，而 &lt;code&gt;df -h&lt;/code&gt; 里根目录还是 40 GB，那就是分区扩了、文件系统没扩，差的是最后一条命令。先学会读这张表，扩容排障就成功了一半。&lt;/p&gt;
&lt;p&gt;:::warning
排查空间问题时先分清你在看哪一层：&lt;code&gt;lsblk&lt;/code&gt; 的 SIZE 是分区大小，&lt;code&gt;df -h&lt;/code&gt; 的 Size 是文件系统大小。云盘扩容后两者不一致是正常中间状态，不是故障。
:::&lt;/p&gt;
&lt;h2&gt;二、云盘扩容全流程：三步缺一不可&lt;/h2&gt;
&lt;p&gt;云服务器的盘不够用了，在控制台把云盘从 40 GB 改到 100 GB——这只是改了「设备」这一层的大小。系统里真正能用的空间，要再走两步：&lt;strong&gt;扩分区 → 扩文件系统&lt;/strong&gt;。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;控制台扩容只是第一步，分区和文件系统不跟上，df 看到的永远是旧容量。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;完整流程（以最常见的系统盘 &lt;code&gt;/dev/vda&lt;/code&gt; 第 1 个分区 &lt;code&gt;/dev/vda1&lt;/code&gt;、ext4 文件系统为例）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 第 0 步：先看清现状，确认盘符、分区号和文件系统类型
lsblk -f

# 第 1 步：在云厂商控制台扩容云盘（网页操作，改完不用重启）

# 第 2 步：让内核重新识别容量，然后扩分区
apt install -y cloud-guest-utils
growpart /dev/vda 1

# 第 3 步：扩文件系统（ext4 用 resize2fs）
resize2fs /dev/vda1

# 验证：两条命令看到的都应该是新容量
lsblk
df -h
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;每步的验证点和注意点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;第 2 步之前&lt;/strong&gt;：先用 &lt;code&gt;lsblk&lt;/code&gt; 确认内核有没有认到新容量——整盘那一行的 SIZE 变大，说明控制台扩容已生效；如果整盘大小没变，先重启一次再继续。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;growpart 的参数&lt;/strong&gt;是「设备 分区号」分开写的：&lt;code&gt;growpart /dev/vda 1&lt;/code&gt;，不是写分区名 &lt;code&gt;/dev/vda1&lt;/code&gt;。NVMe 盘同理：&lt;code&gt;growpart /dev/nvme0n1 1&lt;/code&gt;。执行后它会输出 &lt;code&gt;CHANGED&lt;/code&gt; 字样并给出新旧大小；如果输出 &lt;code&gt;NOCHANGE&lt;/code&gt;，说明分区已经占满整盘，问题在文件系统那一步。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;第 3 步选哪条命令，取决于文件系统类型&lt;/strong&gt;，这是扩容最容易错的一处：&lt;/li&gt;
&lt;/ul&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;文件系统&lt;/th&gt;
&lt;th&gt;扩容命令&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;ext4 / ext3 / ext2&lt;/td&gt;
&lt;td&gt;&lt;code&gt;resize2fs /dev/vda1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;支持在线扩容，挂载状态下直接执行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;XFS&lt;/td&gt;
&lt;td&gt;&lt;code&gt;xfs_growfs /&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;参数给&lt;strong&gt;挂载点&lt;/strong&gt;不是设备名；只能扩不能缩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;btrfs&lt;/td&gt;
&lt;td&gt;&lt;code&gt;btrfs filesystem resize max /&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;参数同样给挂载点&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;不用重启的前提&lt;/strong&gt;：云盘是在线扩容（控制台操作时机器不关机）、分区是盘的最后一个分区、文件系统支持在线扩容（ext4 和 XFS 都支持）。满足这三条，全程业务不用停。如果系统盘分区后面还拖着交换分区等其他分区，growpart 会失败，这种布局建议先备份再重做分区，不要硬来。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;根分区是 LVM 的情况多两步&lt;/strong&gt;：有些镜像把根放在逻辑卷上（&lt;code&gt;lsblk&lt;/code&gt; 能看到分区下面还套着一层 &lt;code&gt;mapper&lt;/code&gt; 设备）。这种布局在 growpart 之后要先扩物理卷再扩逻辑卷，最后才扩文件系统：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;# LVM 布局的扩容顺序（设备名按 lsblk 实际输出替换）
growpart /dev/vda 1
pvresize /dev/vda1
lvextend -l +100%FREE /dev/mapper/vg0-root
resize2fs /dev/mapper/vg0-root
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;判断自己是不是 LVM 布局很简单：&lt;code&gt;df -h&lt;/code&gt; 里根目录的设备名是 &lt;code&gt;/dev/mapper/...&lt;/code&gt; 开头的，就是 LVM；是 &lt;code&gt;/dev/vda1&lt;/code&gt; 这种的，就是普通分区，按正文三步走即可。&lt;/p&gt;
&lt;p&gt;:::warning
扩容前先给云盘打个快照再动手。growpart 和 resize2fs 本身很成熟，但&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;任何动分区的操作都没有后悔药&amp;lt;/span&amp;gt;，快照是唯一的退路。
:::&lt;/p&gt;
&lt;h2&gt;三、给服务器加一块新盘：分区、格式化、挂载&lt;/h2&gt;
&lt;p&gt;新购的数据盘挂到机器上后，它只是一块「裸设备」，要走完分区、格式化、挂载三步才能用（整盘不分区直接格式化也可以，个人服务器场景两种都行，本篇按分区的标准做法走）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 确认新盘设备名（假设是 /dev/vdb，以下命令请按实际盘符替换）
lsblk

# 分区：交互式工具，这里用 parted 一条命令建一个占满全盘的主分区
parted /dev/vdb --script mklabel gpt mkpart primary ext4 0% 100%

# 格式化为 ext4
mkfs.ext4 /dev/vdb1

# 建挂载点目录
mkdir -p /data

# 查分区的 UUID，写 fstab 要用
blkid /dev/vdb1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;mkfs&lt;/code&gt; 是不可逆操作：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;执行前务必用 lsblk 再三确认盘符&amp;lt;/span&amp;gt;，把系统盘当新盘格式化的事故，每年都在真实发生。
:::&lt;/p&gt;
&lt;p&gt;然后把挂载写进 &lt;code&gt;/etc/fstab&lt;/code&gt;（下一节逐列拆解），加上查到的 UUID：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  /data  ext4  defaults,nofail  0  2
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;写完不要急着重启，先验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 按 fstab 把所有未挂载的条目挂上，报错会当场暴露
mount -a

# 确认挂载成功、容量正确
df -h /data
mount | grep /data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;纪律是：mount -a 不报错、df 确认无误之后，才允许重启验证。&amp;lt;/span&amp;gt;直接写完 fstab 就重启，等于把排错机会留给最难受的场景——机器起不来、人在控制台外面干瞪眼。&lt;/p&gt;
&lt;h2&gt;四、fstab 逐列拆解：六列都不能乱填&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;/etc/fstab&lt;/code&gt; 每行六列，空格或 Tab 分隔：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;UUID=xxxx  /data  ext4  defaults,nofail  0  2
  ①         ②      ③        ④          ⑤  ⑥
&lt;/code&gt;&lt;/pre&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;列&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;填写要点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;① 设备&lt;/td&gt;
&lt;td&gt;挂哪个文件系统&lt;/td&gt;
&lt;td&gt;用 &lt;code&gt;UUID=&lt;/code&gt; 形式，不要写 &lt;code&gt;/dev/sdb1&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;② 挂载点&lt;/td&gt;
&lt;td&gt;挂到哪个目录&lt;/td&gt;
&lt;td&gt;目录必须事先存在&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;③ 类型&lt;/td&gt;
&lt;td&gt;文件系统类型&lt;/td&gt;
&lt;td&gt;ext4、xfs、vfat、swap 等，写错直接挂载失败&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;④ 选项&lt;/td&gt;
&lt;td&gt;挂载参数，逗号分隔&lt;/td&gt;
&lt;td&gt;常用 &lt;code&gt;defaults&lt;/code&gt;；数据盘建议加 &lt;code&gt;nofail&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⑤ dump&lt;/td&gt;
&lt;td&gt;老式备份工具标记&lt;/td&gt;
&lt;td&gt;现在基本不用，填 &lt;code&gt;0&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⑥ fsck&lt;/td&gt;
&lt;td&gt;开机自检顺序&lt;/td&gt;
&lt;td&gt;根分区填 &lt;code&gt;1&lt;/code&gt;，其他盘填 &lt;code&gt;2&lt;/code&gt;，不需要检查填 &lt;code&gt;0&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;两个关键点单独强调：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;为什么用 UUID 而不用设备名&lt;/strong&gt;：&lt;code&gt;/dev/sdb&lt;/code&gt;、&lt;code&gt;/dev/sdc&lt;/code&gt; 这类名字是按内核识别顺序分配的，加一块盘、换个插口、甚至重启一次，顺序都可能变。用设备名写 fstab，某次重启后就可能把 A 盘挂到 B 盘的目录上，轻则数据错乱，重则起不来机。UUID 是格式化时写进文件系统的唯一标识，不随顺序变化，这才是稳定引用方式。用 &lt;code&gt;blkid&lt;/code&gt; 或 &lt;code&gt;lsblk -f&lt;/code&gt; 查询。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;nofail 是数据盘的保险&lt;/strong&gt;：默认情况下，fstab 里任何一条挂载失败，开机流程都会卡住甚至掉进 emergency mode。给非系统盘加上 &lt;code&gt;nofail&lt;/code&gt;，意思是「这块盘挂不上也别拦着开机」，系统先起来，盘的问题登进去再慢慢修。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;根分区和系统必需的挂载不要加 nofail&amp;lt;/span&amp;gt;，那是掩盖真故障。&lt;/p&gt;
&lt;h2&gt;五、inode：空间没满，文件却写不进的隐形杀手&lt;/h2&gt;
&lt;p&gt;每个文件（包括目录、软链接）在文件系统里都要占一个 inode，用来记录它的元信息。建文件系统时 inode 总数就定死了，&lt;strong&gt;容量和 inode 是两本独立的账&lt;/strong&gt;：字节没用完，inode 先用完，照样建不了新文件。&lt;/p&gt;
&lt;p&gt;典型症状非常有迷惑性：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 报错：No space left on device，但 df -h 显示明明还有几十 GB
df -h
# /dev/vda1   100G   55G   45G   55%   /

# 真相在另一条命令里：IUse% 已经 100%
df -i
# /dev/vda1   6553600  6553580  20  100%  /
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;df -i&lt;/code&gt; 看四列：总 inode 数、已用、可用、使用率。只要 &lt;code&gt;IUse%&lt;/code&gt; 到 100%，任何创建新文件的操作都会报 &lt;code&gt;No space left on device&lt;/code&gt;，错误信息和磁盘真满时一模一样。&lt;/p&gt;
&lt;p&gt;inode 是被什么吃掉的？答案是&lt;strong&gt;海量小文件&lt;/strong&gt;，一个文件一个 inode，文件越小越「不划算」：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;常见来源&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;程序缓存与会话文件&lt;/td&gt;
&lt;td&gt;Web 应用的 cache、PHP session 目录，动辄几十万个小文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;邮件队列&lt;/td&gt;
&lt;td&gt;邮件服务异常时滞留的队列文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;没清理的临时文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/tmp&lt;/code&gt;、&lt;code&gt;/var/tmp&lt;/code&gt; 里长期堆积的碎文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;解压出的源码/依赖&lt;/td&gt;
&lt;td&gt;node_modules、反复解压的压缩包&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;日志被按条切片&lt;/td&gt;
&lt;td&gt;切割粒度过细的日志归档&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;定位手法是按目录统计文件数量逐层下钻：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 统计某个目录下文件的总数，先对大目录有个概念
find /var -xdev -type f | wc -l

# 逐层看哪一层文件最多（对当前目录各子目录分别计数）
du --inodes -d 2 /var 2&amp;gt;/dev/null | sort -n | tail -20
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;找到元凶目录后，先确认里面是什么再处理：过期的缓存和会话可以直接删，业务文件则要从源头治理（让程序定期清理、或把这类目录单独挂一个 inode 密度更高的文件系统）。删的时候注意别用 &lt;code&gt;rm -rf&lt;/code&gt; 对着几十万文件硬删到天荒地老，可以分批：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 分批删除某个目录下的过期小文件（例如 7 天前的会话文件）
find /path/to/dir -type f -mtime +7 -delete
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
新建文件系统时可以用 &lt;code&gt;mkfs.ext4 -i&lt;/code&gt; 调整每个 inode 对应的字节数来提高 inode 密度，但这是格式化参数，对已经在用的文件系统无法事后修改，存量系统只能靠清理和治理解决。
:::&lt;/p&gt;
&lt;h2&gt;六、空间排查标准手法：四件工具逐层下钻&lt;/h2&gt;
&lt;p&gt;磁盘告警响起时，不要凭感觉乱删，按固定套路查，十分钟就能定位：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一件：du 逐层下钻&lt;/strong&gt;，从根目录一层层往大目录里走：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 根目录下各一级目录谁最占地方
du -h --max-depth=1 / 2&amp;gt;/dev/null | sort -hr | head -20

# 锁定大目录后继续往里钻
du -h --max-depth=1 /var 2&amp;gt;/dev/null | sort -hr | head -20
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;加 &lt;code&gt;-x&lt;/code&gt;（&lt;code&gt;du -hx&lt;/code&gt;）可以只统计当前文件系统、不跨挂载点，避免把其他盘也算进来。&lt;code&gt;2&amp;gt;/dev/null&lt;/code&gt; 是屏蔽掉无权限目录的报错刷屏。&lt;/p&gt;
&lt;p&gt;走一遍真实的下钻过程帮助理解：第一层 &lt;code&gt;du&lt;/code&gt; 发现 &lt;code&gt;/var&lt;/code&gt; 占了 60 GB，钻进 &lt;code&gt;/var&lt;/code&gt; 发现 &lt;code&gt;lib&lt;/code&gt; 占 55 GB，再钻进 &lt;code&gt;/var/lib&lt;/code&gt; 发现 &lt;code&gt;docker&lt;/code&gt; 占 50 GB——三层就锁定了大户是 Docker，接下来就不是删文件的问题，而是去清镜像、容器和悬空卷（入口在第七节的清单里）。这个手法的要点是每层只看排序后的前几名、只往最大的那个目录里钻，不要一上来就对全盘做深度统计，又慢又没重点。整套查完通常用不了几分钟，比对着告警猜半天靠谱得多。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二件：ncdu 交互式浏览&lt;/strong&gt;，适合在终端里像逛文件管理器一样找大户：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apt install -y ncdu
ncdu /
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;方向键进出目录、按体积排序，还能在界面里直接删除确认过的垃圾，比反复敲 du 快得多。注意以 root 运行时删文件要格外确认路径。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三件：find 直接找大文件&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 找根分区里大于 500 MB 的文件
find / -xdev -type f -size +500M -exec ls -lh {} \; 2&amp;gt;/dev/null
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第四件：lsof 找「删了却没释放」的文件&lt;/strong&gt;，这是最经典的一个坑：日志文件明明 &lt;code&gt;rm&lt;/code&gt; 掉了，&lt;code&gt;df&lt;/code&gt; 的空间却一点没回来。原因是&lt;strong&gt;文件被删时还有进程开着它&lt;/strong&gt;，目录项没了，但数据块要等进程释放句柄才真正回收：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 列出所有「已删除但仍被占用」的文件，按大小看
lsof +L1 | grep deleted

# 或者
lsof | grep deleted
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出里带 &lt;code&gt;(deleted)&lt;/code&gt; 标记、SIZE 很大的那几行就是元凶，常见于日志轮转配置不对、或手动删了正在写的日志。处理方法不是再删一次，而是让占用它的进程放手：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 知道是哪个服务就重启哪个服务（以 rsyslog 为例）
systemctl restart rsyslog

# 处理完再看，空间应该已经回来
df -h
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要为了释放空间去 kill 不明进程&amp;lt;/span&amp;gt;，先从 lsof 输出确认进程名和它占的是哪个文件，重启对应服务即可；实在找不到归属再考虑其他手段。&lt;/p&gt;
&lt;h2&gt;七、常见空间大户清单：先查这几家&lt;/h2&gt;
&lt;p&gt;按经验，个人服务器的空间基本是被下面几家吃掉的，逐个查、逐个有处理入口：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;大户&lt;/th&gt;
&lt;th&gt;位置&lt;/th&gt;
&lt;th&gt;处理入口&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;系统日志&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/var/log/journal/&lt;/code&gt;、&lt;code&gt;/var/log/&lt;/code&gt; 下的大日志&lt;/td&gt;
&lt;td&gt;给 journald 设上限（如 &lt;code&gt;SystemMaxUse=500M&lt;/code&gt;），&lt;code&gt;journalctl --vacuum-size=500M&lt;/code&gt; 立即回收&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Docker&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/var/lib/docker/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;镜像、停止的容器、悬空卷定期清，详见 &lt;a href=&quot;/posts/docker-commands-troubleshooting/&quot;&gt;Docker 常用命令速查与排障实战&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;APT 缓存&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/var/cache/apt/archives/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;apt clean&lt;/code&gt; 清下载缓存；开启自动清理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;旧内核&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/boot/&lt;/code&gt; 与 &lt;code&gt;/lib/modules/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;apt autoremove&lt;/code&gt; 自动清旧内核，只保留当前和上一个版本&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;应用程序日志&lt;/td&gt;
&lt;td&gt;各服务自己的日志目录&lt;/td&gt;
&lt;td&gt;配 logrotate 切割＋保留天数，别让单个日志无限长&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;备份文件堆积&lt;/td&gt;
&lt;td&gt;手工放的 &lt;code&gt;.bak&lt;/code&gt;、&lt;code&gt;.tar.gz&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;定保留策略，备份尽量落到其他盘或对象存储&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;处理任何一家之前，先用第六节的手法确认它真的是大头，不要凭印象动手。&lt;/p&gt;
&lt;h2&gt;八、排障小节&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. 云盘扩容后，df 容量没变&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;按三步逐段验：&lt;code&gt;lsblk&lt;/code&gt; 看整盘 SIZE 变了没——没变是内核还没认到，重启一次；整盘变了但分区没变，是漏了 &lt;code&gt;growpart&lt;/code&gt;；分区变了但 &lt;code&gt;df&lt;/code&gt; 没变，是漏了扩文件系统那步（ext4 是 &lt;code&gt;resize2fs&lt;/code&gt;，XFS 是 &lt;code&gt;xfs_growfs&lt;/code&gt;，注意别用错命令，用错会直接报错，不用担心扩坏）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. fstab 写错，重启进了 emergency mode&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;屏幕会提示 &lt;code&gt;You are in emergency mode&lt;/code&gt; 并要求输入 root 密码。救法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 输入 root 密码进入维护 shell 后，先把根分区改成可写
mount -o remount,rw /

# 编辑 fstab，把写错的那行改对，或者先在行首加 # 注释掉
nano /etc/fstab

# 改完先验证再重启
mount -a
systemctl reboot
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;进不去维护 shell（没设 root 密码等情况）时，用云厂商的 VNC 控制台配合救援模式或挂载系统盘到另一台机器改 fstab，思路相同：先让系统能起来，错的那行注释掉永远是安全的兜底。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 磁盘突然变成只读挂载&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;症状：文件都在、能读，但任何写入都报 &lt;code&gt;Read-only file system&lt;/code&gt;。这通常不是权限问题，而是&lt;strong&gt;文件系统检测到错误后自我保护、自动以只读方式重新挂载&lt;/strong&gt;，是硬件或文件系统损坏的早期信号：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 确认状态：输出里带 ro 就是只读挂载
mount | grep &apos; / &apos;

# 看内核日志里的文件系统报错
dmesg | grep -i -E &apos;ext4|xfs|error|remount&apos; | tail -20
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;处理顺序：先备份重要数据，再安排停机用 fsck 检查修复（根分区无法在线修复，需要进救援模式执行 &lt;code&gt;fsck -y /dev/vda1&lt;/code&gt;）。如果 dmesg 里同时有大量 I/O error，优先怀疑云盘或宿主机故障，立刻联系厂商并迁移数据，不要反复 fsck 硬撑。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. du 和 df 对不上&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;code&gt;du&lt;/code&gt; 加起来没多少，&lt;code&gt;df&lt;/code&gt; 却显示快满了——九成是第六节说的已删除未释放文件，用 &lt;code&gt;lsof +L1&lt;/code&gt; 一查便知；剩下一种是文件系统本身预留或损坏，按第 3 条的思路查 dmesg。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;磁盘分四层看：设备、分区、文件系统、挂载点，&lt;code&gt;lsblk&lt;/code&gt; 看结构、&lt;code&gt;df -h&lt;/code&gt; 看用量、&lt;code&gt;mount&lt;/code&gt; 看实际状态。&lt;/li&gt;
&lt;li&gt;云盘扩容是三步：控制台扩容量、&lt;code&gt;growpart&lt;/code&gt; 扩分区、按文件系统类型扩文件系统（ext4 用 &lt;code&gt;resize2fs&lt;/code&gt;，XFS 用 &lt;code&gt;xfs_growfs&lt;/code&gt;），每步都有验证点，全程可以不重启。&lt;/li&gt;
&lt;li&gt;新盘挂载写 fstab 用 UUID、数据盘加 &lt;code&gt;nofail&lt;/code&gt;，写完必须 &lt;code&gt;mount -a&lt;/code&gt; 验证无误再重启。&lt;/li&gt;
&lt;li&gt;空间没满却写不进，先查 &lt;code&gt;df -i&lt;/code&gt;：inode 耗尽的元凶永远是海量小文件。&lt;/li&gt;
&lt;li&gt;空间排查走标准套路：&lt;code&gt;du&lt;/code&gt; 逐层下钻、&lt;code&gt;ncdu&lt;/code&gt; 交互浏览、&lt;code&gt;find&lt;/code&gt; 找大文件、&lt;code&gt;lsof +L1&lt;/code&gt; 抓删了没释放的文件。&lt;/li&gt;
&lt;li&gt;日志、Docker、APT 缓存、旧内核是四大常规大户，先确认再清理，别凭感觉乱删。&lt;/li&gt;
&lt;li&gt;fstab 写错和只读挂载都有明确救法，核心原则是先保数据、先让系统起来，再慢慢修。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>如何在Linux自动更新Docker容器</title><link>https://www.anexns.cloudns.org/posts/linux-docker-auto-update/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-docker-auto-update/</guid><description>让 Docker 容器保持最新：Watchtower 全自动更新实战（检查间隔、只更新指定容器、更新通知、生命周期钩子），外加 Compose 脚本半自动方案、版本固定与回滚方法。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;上一篇 &lt;a href=&quot;/posts/linux-docker-compose/&quot;&gt;《如何在Linux部署Docker&amp;amp;Compose》&lt;/a&gt; 讲了怎么把容器跑起来。容器跑起来之后还有个长期问题：镜像更新了怎么及时跟上？安全补丁靠手动一个个 &lt;code&gt;pull&lt;/code&gt; 很容易拖几个月。这篇讲怎么让容器&lt;strong&gt;自动更新&lt;/strong&gt;，主线是 Watchtower（全自动），外加一套 Compose 脚本半自动方案，并把风险和回滚讲清楚——自动更新省事，但用错了也会半夜把服务更挂。&lt;/p&gt;
&lt;h2&gt;先想清楚：哪些容器适合自动更新&lt;/h2&gt;
&lt;p&gt;自动更新的前提是镜像用 &lt;code&gt;latest&lt;/code&gt; 或大版本标签（如 &lt;code&gt;nginx:1&lt;/code&gt;），发布方出了新版就自动替换。这对无状态、发布稳定的服务很合适，但不是所有容器都适合：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;建议&lt;/th&gt;
&lt;th&gt;原因&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;无状态小服务（博客、面板、工具站）&lt;/td&gt;
&lt;td&gt;自动更新&lt;/td&gt;
&lt;td&gt;挂了影响小，新版一般向后兼容&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;反向代理、网关&lt;/td&gt;
&lt;td&gt;自动更新或只通知&lt;/td&gt;
&lt;td&gt;影响面大，建议至少开通知&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据库（PostgreSQL、MySQL、Redis）&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;不要全自动&lt;/strong&gt;&amp;lt;/span&amp;gt;&lt;/td&gt;
&lt;td&gt;大版本升级涉及数据格式，必须人工确认&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;有状态/核心生产服务&lt;/td&gt;
&lt;td&gt;只通知，手动更新&lt;/td&gt;
&lt;td&gt;先看 changelog 再决定&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;还有一条铁律：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;重要服务把镜像版本固定住&lt;/strong&gt;&amp;lt;/span&amp;gt;（如 &lt;code&gt;postgres:16.4&lt;/code&gt;），自动更新只碰那些明确用浮动标签的容器。下面 Watchtower 的「只更新带标签的容器」就是为这个准备的。&lt;/p&gt;
&lt;h2&gt;方案对比&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方案&lt;/th&gt;
&lt;th&gt;自动化程度&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;手动 &lt;code&gt;docker compose pull &amp;amp;&amp;amp; up -d&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;偶尔维护、服务少&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;脚本 + 定时任务&lt;/td&gt;
&lt;td&gt;半自动&lt;/td&gt;
&lt;td&gt;Compose 项目、想自己掌控节奏&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Watchtower&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;全自动&lt;/td&gt;
&lt;td&gt;容器较多、想一劳永逸&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Diun&lt;/td&gt;
&lt;td&gt;只通知不更新&lt;/td&gt;
&lt;td&gt;核心服务，先知道再手动更&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;主线：Watchtower 全自动更新&lt;/h2&gt;
&lt;p&gt;Watchtower 会定时检查你正在运行的容器有没有新镜像，有就拉取新镜像、用原来的参数重建容器，整个过程不用人管。&lt;/p&gt;
&lt;h3&gt;用 Docker Compose 部署（推荐）&lt;/h3&gt;
&lt;p&gt;和上一篇的习惯保持一致，用 Compose 管理：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  watchtower:
    image: nickfedor/watchtower:latest
    container_name: watchtower
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 10800 --cleanup
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
镜像别用错：原版 &lt;code&gt;containrrr/watchtower&lt;/code&gt; 已经停止维护并归档，它内置的 Docker 客户端 API 版本只有 1.25，而 Docker 29 的守护进程最低要求 1.40 以上。用原版镜像装出来的 Watchtower 会在日志里反复报错 &lt;code&gt;client version 1.25 is too old. Minimum supported API version is 1.40&lt;/code&gt;，容器看着在跑，实际上&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;永远不会更新任何东西&lt;/strong&gt;&amp;lt;/span&amp;gt;。现在应当使用持续维护的分支 &lt;code&gt;nickfedor/watchtower&lt;/code&gt;，配置、标签、参数与原版完全兼容，本篇所有示例都以它为准。如果你已经装了原版，换掉镜像重新 &lt;code&gt;up -d&lt;/code&gt; 即可，原有配置不用改。
:::&lt;/p&gt;
&lt;p&gt;两个关键参数：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;--interval 10800&lt;/code&gt;：每 10800 秒（3 小时）检查一次。太频繁没意义还费流量，3 小时是个舒服的节奏。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--cleanup&lt;/code&gt;：更新成功后删掉旧镜像，不然旧镜像会一层层堆满磁盘。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
Watchtower 需要挂载 &lt;code&gt;/var/run/docker.sock&lt;/code&gt;，等于给它开了 Docker 的完整控制权。只在自己的机器上用，镜像只从官方仓库拉，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;别在不可信环境里部署&amp;lt;/span&amp;gt;。
:::&lt;/p&gt;
&lt;h3&gt;只更新指定容器（更安全的做法）&lt;/h3&gt;
&lt;p&gt;默认 Watchtower 会盯上&lt;strong&gt;所有&lt;/strong&gt;容器。更稳妥的做法是加 &lt;code&gt;--label-enable&lt;/code&gt;，只更新那些你亲自打了标签的容器：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    command: --interval 10800 --cleanup --label-enable
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后在想自动更新的服务上加标签（Compose 写法）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  nginx:
    image: nginx:latest
    labels:
      - com.centurylinklabs.watchtower.enable=true
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;没打标签的容器（比如数据库）Watchtower 看都不看，先看通知再手动处理，两边都不耽误。&lt;/p&gt;
&lt;h3&gt;先只监控，不动手&lt;/h3&gt;
&lt;p&gt;第一次用不放心，可以先跑一阵子「只监控」模式：发现新镜像只写日志、不更新。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    command: --interval 10800 --monitor-only
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;观察几天日志，确认它盯的容器没问题，再把 &lt;code&gt;--monitor-only&lt;/code&gt; 去掉转正。&lt;/p&gt;
&lt;h3&gt;更新通知&lt;/h3&gt;
&lt;p&gt;更新是自动的，但你应该&lt;strong&gt;知道&lt;/strong&gt;它更了什么。Watchtower 支持通过 shoutrrr 发通知（Telegram、邮件、企业微信等都行），以 Telegram 为例：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    environment:
      - TZ=Asia/Shanghai
      - WATCHTOWER_NOTIFICATIONS=shoutrrr
      - WATCHTOWER_NOTIFICATION_URL=telegram://&amp;lt;机器人Token&amp;gt;@telegram?chats=&amp;lt;你的ChatID&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;之后每次更新都会收到一条消息：哪个容器、从哪个版本更到了哪个版本，一目了然。&lt;/p&gt;
&lt;h3&gt;更新前后钩子&lt;/h3&gt;
&lt;p&gt;个别容器更新前需要先做点事（比如备份、优雅停机），可以在目标容器上加生命周期标签：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    labels:
      - com.centurylinklabs.watchtower.lifecycle.pre-update=/scripts/backup.sh
      - com.centurylinklabs.watchtower.lifecycle.post-update=/scripts/check.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;脚本要放在容器&lt;strong&gt;内部&lt;/strong&gt;，路径是容器里的路径。pre-update 返回非 0 会中止这次更新，正好用来做「&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;备份失败就不许更新&amp;lt;/span&amp;gt;」的保险。&lt;/p&gt;
&lt;h2&gt;半自动方案：Compose 脚本 + 定时任务&lt;/h2&gt;
&lt;p&gt;如果你的服务全是 Compose 项目，又想保留「更新前我说了算」的感觉，可以用脚本定时拉取重建，自己掌控名单：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
# /opt/scripts/docker-update.sh
cd /opt/myapp || exit 1
docker compose pull
docker compose up -d
docker image prune -f
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;chmod +x /opt/scripts/docker-update.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;挂到 crontab，每天凌晨 4 点执行并留日志：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;0 4 * * * /opt/scripts/docker-update.sh &amp;gt;&amp;gt; /var/log/docker-update.log 2&amp;gt;&amp;amp;1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这个方案的好处是更新范围就是脚本里写的项目，坏处是每个项目要单独维护一份脚本，项目多了不如 Watchtower 省心。&lt;/p&gt;
&lt;p&gt;:::warning
脚本里的 &lt;code&gt;docker image prune -f&lt;/code&gt; 只删没有容器在用的悬空镜像，相对安全；但千万不要写成 &lt;code&gt;docker system prune -a&lt;/code&gt;，那会把停着的容器、没在跑的镜像一起清掉，上一篇已经强调过这个坑。
:::&lt;/p&gt;
&lt;h2&gt;版本固定与回滚&lt;/h2&gt;
&lt;p&gt;自动更新偶尔会翻车：新版改了配置格式、或者本身带 bug。提前做好两件事，翻车了 5 分钟就能退回去：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;1. Compose 文件进 Git。&lt;/strong&gt; 每次改配置都提交，出事能查到上次的配置长什么样。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 知道旧镜像还在不在。&lt;/strong&gt; 开了 &lt;code&gt;--cleanup&lt;/code&gt; 旧镜像会被删掉，回滚要重新拉旧版本，所以关键服务的镜像标签别只写 &lt;code&gt;latest&lt;/code&gt;，写到小版本：&lt;code&gt;myapp:2.3.1&lt;/code&gt;。回滚时改回上一个版本号重新拉取即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 把 compose 里的镜像改回旧版本后
docker compose pull
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果没开 &lt;code&gt;--cleanup&lt;/code&gt;，旧镜像还躺在本机，可以直接给它重新打上标签再用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker images        # 找到旧镜像的 IMAGE ID
docker tag &amp;lt;旧IMAGE_ID&amp;gt; myapp:rollback
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;常见问题排查&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;日志反复报 &lt;code&gt;client version 1.25 is too old&lt;/code&gt;。&lt;/strong&gt; 这是装了原版 &lt;code&gt;containrrr/watchtower&lt;/code&gt; 的典型症状：它的客户端 API 太旧，被新版 Docker 直接拒绝，一个容器都更新不了。把镜像换成维护分支 &lt;code&gt;nickfedor/watchtower&lt;/code&gt; 重新部署即可，配置不用动。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Watchtower 没动静。&lt;/strong&gt; 先看它的日志，它会明确写每个容器检查的结果和跳过原因：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker logs -f watchtower
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;提示权限不足。&lt;/strong&gt; 基本都是 &lt;code&gt;/var/run/docker.sock&lt;/code&gt; 没挂对，或者宿主机 Docker 的 socket 路径不同，检查 Compose 的 volumes。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;更新后容器起不来。&lt;/strong&gt; 先看新容器日志确认是新版的问题，再按上面的回滚步骤退回旧版本，别在故障现场改配置硬撑：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker logs &amp;lt;容器名&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;磁盘越来越满。&lt;/strong&gt; 多半是没开 &lt;code&gt;--cleanup&lt;/code&gt;，旧镜像在堆积。手动清一次悬空镜像即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker image prune -f
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;停用自动更新&lt;/h2&gt;
&lt;p&gt;想停掉很简单，停掉 Watchtower 就行，其他容器不受影响：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose stop watchtower
docker compose rm watchtower
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;无状态小服务交给 Watchtower 全自动，3 小时检查一次、开 &lt;code&gt;--cleanup&lt;/code&gt;、开通知；&lt;/li&gt;
&lt;li&gt;放不下心的先用 &lt;code&gt;--label-enable&lt;/code&gt; 只更新打了标签的容器，或者 &lt;code&gt;--monitor-only&lt;/code&gt; 先观察几天；&lt;/li&gt;
&lt;li&gt;数据库和核心服务固定版本、只通知不自动更；&lt;/li&gt;
&lt;li&gt;Compose 文件进 Git、关键服务版本写到小版本，翻车能立刻回滚。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;自动更新的定位是「把重复劳动交给工具」，不是&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;「把判断也交出去」&amp;lt;/span&amp;gt;。名单分好类、通知开起来、回滚留好路，它就是个很省心的帮手。&lt;/p&gt;
</content:encoded></item><item><title>如何在Linux部署Docker&amp;Compose</title><link>https://www.anexns.cloudns.org/posts/linux-docker-compose/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-docker-compose/</guid><description>从零开始在 Linux 上完整安装 Docker Engine 与 Docker Compose：官方仓库安装、一键脚本、镜像加速、日志限制、Compose 实战、常用命令速查、故障排查与卸载，一篇全部搞定。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;写在前面&lt;/h2&gt;
&lt;p&gt;Docker 是目前最主流的容器引擎：把应用和它的运行环境打包成一个「镜像」，在任何装了 Docker 的机器上都能以「容器」的形式原样跑起来，彻底告别「我这儿能跑、服务器上跑不起来」的经典难题。&lt;/p&gt;
&lt;p&gt;Docker Compose 则是它的编排搭档：用一个 &lt;code&gt;docker-compose.yml&lt;/code&gt; 文件把多个容器（比如网站 + 数据库 + 缓存）的配置一次性写清楚，一条命令全部拉起、一条命令全部停掉，不用再手敲一长串 &lt;code&gt;docker run&lt;/code&gt; 参数。&lt;/p&gt;
&lt;p&gt;这篇文章以 Debian 为主线（Ubuntu 步骤基本一致，文末附 RHEL 系的差异），把从安装、配置、实战到卸载的完整流程走一遍。所有命令都可以直接复制执行，代码块右上角有复制按钮。&lt;/p&gt;
&lt;h3&gt;准备条件&lt;/h3&gt;
&lt;p&gt;开始之前，先确认你的机器满足下面几个条件：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;64 位 Linux 系统：Debian 11/12/13、Ubuntu 20.04/22.04/24.04，或 CentOS/Rocky/AlmaLinux 9 等&lt;/li&gt;
&lt;li&gt;内核版本 3.10 以上（用 &lt;code&gt;uname -r&lt;/code&gt; 查看，现代发行版都满足）&lt;/li&gt;
&lt;li&gt;有 &lt;code&gt;root&lt;/code&gt; 权限，或当前账号可以用 &lt;code&gt;sudo&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;服务器能正常访问外网（要从官方仓库下载软件包）&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;查看自己的系统版本：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cat /etc/os-release
uname -r
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;先卸载旧版本（装过才需要）&lt;/h3&gt;
&lt;p&gt;如果这台机器以前用系统自带源装过老版本的 Docker，先卸干净，避免和新版本冲突。没装过可以直接跳到下一节。&lt;/p&gt;
&lt;p&gt;Debian / Ubuntu：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo apt-get remove -y docker docker-engine docker.io containerd runc
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意：这一步只删程序本体，&lt;code&gt;/var/lib/docker&lt;/code&gt; 里的镜像和容器数据不会被删。全新安装的机器执行它只会提示「未安装」，无副作用，放心执行。&lt;/p&gt;
&lt;h2&gt;方式一：官方仓库安装（推荐）&lt;/h2&gt;
&lt;p&gt;这是官方推荐、也是生产环境最稳妥的装法：把 Docker 官方软件源加进系统，以后升级直接跟着 &lt;code&gt;apt update&lt;/code&gt; 一起走。&lt;/p&gt;
&lt;h3&gt;第 1 步：安装依赖并导入官方 GPG 密钥&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;说明一下每一步在干什么：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;ca-certificates&lt;/code&gt; 和 &lt;code&gt;curl&lt;/code&gt; 是下载 HTTPS 文件的基础工具&lt;/li&gt;
&lt;li&gt;&lt;code&gt;/etc/apt/keyrings&lt;/code&gt; 是现在 Debian/Ubuntu 存放第三方仓库签名密钥的标准目录&lt;/li&gt;
&lt;li&gt;下载下来的 &lt;code&gt;docker.asc&lt;/code&gt; 是 Docker 官方的签名公钥，系统靠它验证软件包是不是官方发布的、有没有被篡改&lt;/li&gt;
&lt;/ul&gt;
&lt;blockquote&gt;
&lt;p&gt;如果你的系统是 Ubuntu，把上面地址里的 &lt;code&gt;debian&lt;/code&gt; 换成 &lt;code&gt;ubuntu&lt;/code&gt; 即可，下同。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h3&gt;第 2 步：添加 Docker 官方软件源&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;echo \
  &quot;deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release &amp;amp;&amp;amp; echo &quot;$VERSION_CODENAME&quot;) stable&quot; | \
  sudo tee /etc/apt/sources.list.d/docker.list &amp;gt; /dev/null
sudo apt-get update
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这条命令做了两件事：自动识别你的 CPU 架构（amd64 / arm64）和系统版本代号（如 bookworm、trixie），拼出一条仓库配置写进 &lt;code&gt;/etc/apt/sources.list.d/docker.list&lt;/code&gt;；然后刷新软件包列表。刷新时能看到多出来一个 download.docker.com 的源，就说明添加成功了。&lt;/p&gt;
&lt;h3&gt;第 3 步：安装 Docker Engine 与 Compose 插件&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这五个包分别是：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;软件包&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker-ce&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Docker 引擎本体（守护进程 dockerd）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker-ce-cli&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker&lt;/code&gt; 命令行客户端&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;containerd.io&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;底层容器运行时，负责真正管理容器生命周期&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker-buildx-plugin&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;新一代镜像构建工具&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker-compose-plugin&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Compose 的插件版，装完就能用 &lt;code&gt;docker compose&lt;/code&gt; 命令&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;也就是说，用这种方式安装，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;Compose 已经一起装好了&lt;/strong&gt;&amp;lt;/span&amp;gt;，不需要再单独装一遍。后文还会介绍独立版 Compose 的装法，适合只想单独升级 Compose 的场景。&lt;/p&gt;
&lt;h3&gt;第 4 步：启动服务并设置开机自启&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl start docker
sudo systemctl enable docker
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;验证服务状态（显示 &lt;code&gt;active (running)&lt;/code&gt; 即正常）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl status docker
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第 5 步：验证安装&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;sudo docker version
sudo docker run hello-world
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;docker run hello-world&lt;/code&gt; 会自动拉取一个官方测试镜像并运行。看到 &lt;code&gt;Hello from Docker!&lt;/code&gt; 就说明引擎、网络、镜像拉取整条链路都通了。&lt;/p&gt;
&lt;h2&gt;方式二：一键脚本安装（快速体验）&lt;/h2&gt;
&lt;p&gt;Docker 官方还提供了一个便捷安装脚本，一行命令自动完成上面所有步骤：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;国内服务器下载慢的话，可以给脚本指定阿里云镜像：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo sh get-docker.sh --mirror Aliyun
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;需要提醒的是：一键脚本适合测试机和快速体验，&lt;strong&gt;生产环境更建议用方式一的仓库安装&lt;/strong&gt;——脚本装了什么版本不完全受你控制，而仓库安装的版本管理、升级和回滚都更清晰。&lt;/p&gt;
&lt;h2&gt;RHEL 系（CentOS / Rocky / AlmaLinux）差异&lt;/h2&gt;
&lt;p&gt;RHEL 系用 &lt;code&gt;dnf&lt;/code&gt; 代替 &lt;code&gt;apt&lt;/code&gt;，其余思路完全一样。简要流程如下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 卸载旧版本
sudo dnf remove -y docker docker-client docker-client-latest docker-common \
  docker-latest docker-latest-logrotate docker-logrotate docker-engine

# 添加官方仓库
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 安装并启动
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker run hello-world
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;让普通用户免 sudo 用 Docker&lt;/h2&gt;
&lt;p&gt;默认情况下只有 &lt;code&gt;root&lt;/code&gt; 和 &lt;code&gt;docker&lt;/code&gt; 用户组的成员能操作 Docker。每次敲命令都加 &lt;code&gt;sudo&lt;/code&gt; 很烦，可以把当前用户加进 &lt;code&gt;docker&lt;/code&gt; 组：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo usermod -aG docker $USER
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;执行后&lt;strong&gt;注销重新登录&lt;/strong&gt;（或重启服务器）才会生效，之后直接 &lt;code&gt;docker ps&lt;/code&gt; 就能用了。&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;安全提醒：&lt;code&gt;docker&lt;/code&gt; 组的&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;权限实际上等同于 root&amp;lt;/span&amp;gt;——组内用户可以把宿主机任意目录挂进容器读写。所以只把可信账号加进这个组，公网服务器尤其要注意。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2&gt;装完必做：daemon.json 基础配置&lt;/h2&gt;
&lt;p&gt;Docker 的全局配置放在 &lt;code&gt;/etc/docker/daemon.json&lt;/code&gt;，没有就新建。下面这份是我自己所有服务器都在用的配置，解决了三个最常见的问题：拉镜像慢、日志撑爆磁盘、改配置没头绪。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json &amp;lt;&amp;lt;-&apos;EOF&apos;
{
  &quot;registry-mirrors&quot;: [
    &quot;https://docker.1ms.run&quot;,
    &quot;https://docker.m.daocloud.io&quot;
  ],
  &quot;log-driver&quot;: &quot;json-file&quot;,
  &quot;log-opts&quot;: {
    &quot;max-size&quot;: &quot;20m&quot;,
    &quot;max-file&quot;: &quot;3&quot;
  },
  &quot;live-restore&quot;: true
}
EOF
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐项说明：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;registry-mirrors&lt;/code&gt;：镜像加速器。国内服务器直连 Docker Hub 经常超时，配上加速地址后拉镜像走国内节点。公共加速器时有失效，如果某个拉不动了，换一个可用的即可，这一行为空也可以删掉&lt;/li&gt;
&lt;li&gt;&lt;code&gt;log-driver&lt;/code&gt; + &lt;code&gt;log-opts&lt;/code&gt;：限制单个容器的日志文件大小。这里设的是每个日志文件最大 20 MB、最多保留 3 个，也就是单个容器最多占约 60 MB 日志。不设这个的话，话痨容器&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;能把系统盘写满&amp;lt;/span&amp;gt;，这是新手最容易踩的坑&lt;/li&gt;
&lt;li&gt;&lt;code&gt;live-restore&lt;/code&gt;：dockerd 升级或重启时，正在运行的容器保持不中断，老版本升级时很有用&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;改完配置后重启 Docker 生效，并检查配置是否被正确加载：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl daemon-reload
sudo systemctl restart docker
docker info | grep -A3 &quot;Registry Mirrors&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;docker info&lt;/code&gt; 里能看到加速器地址、日志驱动等信息，就说明配置生效了。&lt;/p&gt;
&lt;h2&gt;安装 Docker Compose（独立版）&lt;/h2&gt;
&lt;p&gt;前面仓库安装已经自带了 Compose 插件（命令是 &lt;code&gt;docker compose&lt;/code&gt;，中间空格）。下面介绍的是&lt;strong&gt;独立二进制版&lt;/strong&gt;（命令是 &lt;code&gt;docker-compose&lt;/code&gt;，中间连字符），两种装法任选其一即可，区别在文末有对比。&lt;/p&gt;
&lt;h3&gt;第 1 步：查询并下载最新版&lt;/h3&gt;
&lt;p&gt;先用 GitHub 官方接口查一下最新版本号，避免写死版本号很快过期：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;COMPOSE_VERSION=$(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep &apos;&quot;tag_name&quot;&apos; | cut -d&apos;&quot;&apos; -f4)
echo $COMPOSE_VERSION
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;下载对应平台的二进制文件（命令会自动识别系统和架构）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo curl -L &quot;https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-$(uname -s)-$(uname -m)&quot; -o /usr/local/bin/docker-compose
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;国内服务器从 GitHub 下载慢的话，可以多重试几次，或者先在本地下载再传到服务器上，文件本身只有几十 MB。&lt;/p&gt;
&lt;h3&gt;第 2 步：添加执行权限并验证&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;sudo chmod +x /usr/local/bin/docker-compose
docker-compose version
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;能输出类似 &lt;code&gt;Docker Compose version v2.x.x&lt;/code&gt; 就装好了。&lt;/p&gt;
&lt;h3&gt;插件版 vs 独立版，怎么选&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;插件版&lt;/th&gt;
&lt;th&gt;独立版&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;命令形式&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker compose&lt;/code&gt;（空格）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker-compose&lt;/code&gt;（连字符）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;安装方式&lt;/td&gt;
&lt;td&gt;跟着 Engine 仓库一起装&lt;/td&gt;
&lt;td&gt;单独下载二进制&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;升级方式&lt;/td&gt;
&lt;td&gt;随 Docker 一起升级&lt;/td&gt;
&lt;td&gt;手动替换二进制&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合场景&lt;/td&gt;
&lt;td&gt;大多数情况，省心&lt;/td&gt;
&lt;td&gt;只想单独升级 Compose 时&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;功能上两者完全一致，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;新装机器直接用插件版就行&amp;lt;/span&amp;gt;。另外提醒一句：老教程里的 &lt;code&gt;docker-compose&lt;/code&gt; 1.x 是 Python 写的版本，已经在 2023 年停止维护，不要再装了，现在全是 Go 写的 2.x。&lt;/p&gt;
&lt;h2&gt;Compose 快速上手实战&lt;/h2&gt;
&lt;p&gt;光装好不算会用，下面用一个真实的小例子走一遍完整流程：部署一个 Nginx 网站，并配一个 Redis 做缓存，两个服务一条命令一起拉起。&lt;/p&gt;
&lt;h3&gt;第 1 步：准备项目目录&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/demo-app/html
cd ~/demo-app
echo &apos;&amp;lt;h1&amp;gt;Hello from Docker Compose&amp;lt;/h1&amp;gt;&apos; &amp;gt; html/index.html
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第 2 步：编写 docker-compose.yml&lt;/h3&gt;
&lt;p&gt;在 &lt;code&gt;~/demo-app&lt;/code&gt; 目录下新建 &lt;code&gt;docker-compose.yml&lt;/code&gt;，内容如下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  web:
    image: nginx:alpine
    container_name: demo-web
    ports:
      - &quot;8080:80&quot;
    volumes:
      - ./html:/usr/share/nginx/html:ro
    depends_on:
      - cache
    restart: unless-stopped

  cache:
    image: redis:alpine
    container_name: demo-redis
    volumes:
      - redis-data:/data
    restart: unless-stopped

volumes:
  redis-data:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;字段逐个拆解：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;services&lt;/code&gt;：下面定义的每一个顶格名字就是一个服务（容器）&lt;/li&gt;
&lt;li&gt;&lt;code&gt;image&lt;/code&gt;：用哪个镜像，&lt;code&gt;nginx:alpine&lt;/code&gt; 表示官方 Nginx 的 Alpine 精简版，体积小&lt;/li&gt;
&lt;li&gt;&lt;code&gt;container_name&lt;/code&gt;：给容器起个固定名字，不写的话 Compose 会自动生成&lt;/li&gt;
&lt;li&gt;&lt;code&gt;ports&lt;/code&gt;：端口映射，&lt;code&gt;&quot;8080:80&quot;&lt;/code&gt; 表示把宿主机的 8080 转发到容器的 80，格式是「宿主机:容器」&lt;/li&gt;
&lt;li&gt;&lt;code&gt;volumes&lt;/code&gt;：目录挂载。&lt;code&gt;./html:/usr/share/nginx/html:ro&lt;/code&gt; 把当前目录的 html 文件夹只读挂进 Nginx 的网页目录，改网页不用重启容器；&lt;code&gt;redis-data:/data&lt;/code&gt; 则用命名卷保存 Redis 数据，容器删了数据还在&lt;/li&gt;
&lt;li&gt;&lt;code&gt;depends_on&lt;/code&gt;：启动顺序，web 依赖 cache，会先启动 cache 再启动 web（注意它只保证启动先后，不保证服务就绪，生产项目里一般靠应用自己重试连接）&lt;/li&gt;
&lt;li&gt;&lt;code&gt;restart: unless-stopped&lt;/code&gt;：容器异常退出时自动重启，除非你手动停了它&lt;/li&gt;
&lt;li&gt;顶层的 &lt;code&gt;volumes&lt;/code&gt;：声明上面用到的命名卷&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;第 3 步：启动并验证&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 在 docker-compose.yml 所在目录执行，-d 表示后台运行
docker compose up -d

# 查看两个服务的状态
docker compose ps

# 访问测试
curl http://localhost:8080
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;curl&lt;/code&gt; 返回刚才写的 &lt;code&gt;Hello from Docker Compose&lt;/code&gt;，实战就通关了。注意独立版 Compose 的命令是 &lt;code&gt;docker-compose up -d&lt;/code&gt;，其余参数完全一样。&lt;/p&gt;
&lt;h3&gt;第 4 步：日常操作&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker compose logs -f web     # 实时追踪 web 服务的日志
docker compose restart web     # 只重启 web 这一个服务
docker compose pull            # 拉取 compose 文件里所有服务的新镜像
docker compose down            # 停止并删除容器和网络（命名卷数据保留）
docker compose down -v         # 连命名卷一起删（数据会没，慎用）
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Docker 常用命令速查&lt;/h2&gt;
&lt;h3&gt;镜像相关&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker images                  # 列出本地镜像
docker pull nginx:alpine       # 拉取镜像
docker rmi nginx:alpine        # 删除镜像
docker build -t myapp:v1 .     # 用当前目录的 Dockerfile 构建镜像
docker history nginx           # 查看镜像的层级构建历史
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;容器相关&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker ps                      # 正在运行的容器
docker ps -a                   # 所有容器（含已停止的）
docker logs -f &amp;lt;容器名&amp;gt;         # 实时查看日志
docker exec -it &amp;lt;容器名&amp;gt; sh    # 进入容器内部（alpine 镜像用 sh，普通镜像可用 bash）
docker stop &amp;lt;容器名&amp;gt;            # 停止容器
docker start &amp;lt;容器名&amp;gt;           # 启动已停止的容器
docker rm &amp;lt;容器名&amp;gt;              # 删除容器（要先停止，或加 -f 强制）
docker stats                   # 实时查看所有容器的 CPU / 内存占用
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;Compose 常用命令速查&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose up -d&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;按 compose 文件后台启动全部服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose down&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;停止并删除容器与网络&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose ps&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;查看本项目服务状态&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose logs -f&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;追踪全部服务日志&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose exec &amp;lt;服务&amp;gt; sh&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;进入某个服务的容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose pull&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;拉取全部服务的新镜像&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose up -d --build&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;重新构建镜像并启动&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker compose config&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;校验并打印最终生效的配置&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;磁盘清理（务必谨慎）&lt;/h2&gt;
&lt;p&gt;Docker 用久了，废弃镜像和停止的容器会悄悄占满磁盘。官方提供了一组 &lt;code&gt;prune&lt;/code&gt; 清理命令，但它们都是「宁可错杀」的设计，执行前一定看清楚范围：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker system df               # 先看 Docker 到底占了多少磁盘
docker container prune         # 只删已停止的容器（相对安全）
docker image prune             # 只删没有标签的悬空镜像（相对安全）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;下面这两条范围很大，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;不要随手执行&lt;/strong&gt;&amp;lt;/span&amp;gt;，尤其是 &lt;code&gt;-a&lt;/code&gt; 和 &lt;code&gt;--volumes&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# docker system prune -a          # 删除所有未被容器使用的镜像
# docker system prune -a --volumes # 连未使用的卷一起删，数据库数据可能陪葬
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;我个人的习惯是：只定期清停止的容器和悬空镜像，正式镜像和卷一律手动确认后再删。服务器上真实出过事的，往往不是病毒，是手滑的一条清理命令。&lt;/p&gt;
&lt;h2&gt;常见问题排查&lt;/h2&gt;
&lt;h3&gt;报错 Cannot connect to the Docker daemon&lt;/h3&gt;
&lt;p&gt;意思是客户端连不上守护进程，按顺序查：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl status docker        # 服务是不是没启动
sudo systemctl start docker    # 没启动就拉起来
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果是普通用户执行时报这个错，多半是没加进 &lt;code&gt;docker&lt;/code&gt; 组或加了组还没重新登录，回到前面「免 sudo」那节处理。&lt;/p&gt;
&lt;h3&gt;报错 permission denied（docker.sock）&lt;/h3&gt;
&lt;p&gt;同上，本质是当前用户没有访问 &lt;code&gt;/var/run/docker.sock&lt;/code&gt; 的权限，&lt;code&gt;usermod -aG docker $USER&lt;/code&gt; 后重新登录即可，不要图省事去 &lt;code&gt;chmod 666&lt;/code&gt; 这个文件，那等于&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把 root 权限对所有人敞开&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h3&gt;拉取镜像超时或特别慢&lt;/h3&gt;
&lt;p&gt;先确认 &lt;code&gt;daemon.json&lt;/code&gt; 里的镜像加速器已配置且 Docker 已重启；再用 &lt;code&gt;docker info&lt;/code&gt; 确认加速器真的加载进去了。都正常还慢，就是当前加速器节点的问题，换一个可用的地址，或者给服务器挂代理后再拉。&lt;/p&gt;
&lt;h3&gt;容器起来了但访问不了&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker compose ps              # 容器是不是 Up 状态，有没有反复重启
docker compose logs &amp;lt;服务名&amp;gt;    # 看容器内部报什么错
ss -tlnp | grep 8080           # 宿主机端口到底有没有在监听、被谁占用
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;端口映射写错和端口被其他程序占用，是这两个问题里最常见的。&lt;/p&gt;
&lt;h3&gt;查看 Docker 服务本身的日志&lt;/h3&gt;
&lt;p&gt;容器日志解决不了问题时，看守护进程自己的日志：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo journalctl -u docker -f
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;升级与卸载&lt;/h2&gt;
&lt;p&gt;仓库安装的升级很简单，跟着系统一起升：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;彻底卸载（先停服务，再卸软件包）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl stop docker docker.socket containerd
sudo apt-get purge -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo apt-get autoremove -y
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;独立版 Compose 的卸载就是删文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo rm /usr/local/bin/docker-compose
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意：卸载软件包&lt;strong&gt;不会&lt;/strong&gt;自动删除 &lt;code&gt;/var/lib/docker&lt;/code&gt;（镜像、容器、卷都在这里）和 &lt;code&gt;/etc/docker/daemon.json&lt;/code&gt;。重装时它们会被继续沿用；确认数据都不要了，才手动删目录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 危险操作：执行后所有镜像、容器、数据卷全部消失，不可恢复
sudo rm -rf /var/lib/docker /var/lib/containerd
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;总结&lt;/h2&gt;
&lt;p&gt;回顾一下整条路线：用官方仓库装好 Engine 和 Compose 插件 → 启动服务并验证 hello-world → 普通用户加组免 sudo → 写好 daemon.json（加速器 + 日志限制）→ 用一个双服务的小项目把 Compose 的核心字段和日常命令练一遍。有了这套底子，后面不管是部署网站、数据库还是各种自托管服务，都只是往 Compose 文件里加服务而已。&lt;/p&gt;
&lt;p&gt;参考资料：Docker 官方文档（docs.docker.com）中 Engine 与 Compose 的安装章节，建议收藏，版本更新时以官方文档为准。&lt;/p&gt;
</content:encoded></item><item><title>文件传输与同步：scp 与 rsync</title><link>https://www.anexns.cloudns.org/posts/linux-file-transfer-rsync/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-file-transfer-rsync/</guid><description>服务器之间搬数据的正确姿势：scp 的日常用法、rsync 的增量同步与关键选项、路径末尾斜杠的经典坑，以及一次整站迁移的完整命令组。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;服务器之间搬数据，是运维里最日常也最容易翻车的活：临时传个配置文件，很多人随手就 scp 了；到了整站迁移、几十 GB 数据跨机房搬运，还用老办法全量硬传，传一半断线只能从头再来；更有人 rsync 命令方向写反，把生产数据覆盖成了空目录。这一篇把三件工具一次讲透：scp 负责简单直传，sftp 负责交互式挑文件，rsync 负责增量同步和大规模迁移。主线是先分清工具定位，再把 scp 的日常用法过一遍，然后重点拆 rsync 的核心概念、关键选项、两个经典大坑，最后用一次完整的整站迁移把所有知识点串起来。&lt;/p&gt;
&lt;p&gt;先给一句结论定调：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;小文件、一次性传输用 scp；需要反复同步、断点续传、大数据量迁移，一律用 rsync。&amp;lt;/span&amp;gt;选错工具，轻则浪费时间流量，重则数据出事。&lt;/p&gt;
&lt;h2&gt;一、工具定位：先分清三件工具各管什么&lt;/h2&gt;
&lt;p&gt;scp、sftp、rsync 都走 SSH 通道，加密和认证方式一致，区别在工作模式：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;工具&lt;/th&gt;
&lt;th&gt;工作模式&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;th&gt;不适合&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;scp&lt;/td&gt;
&lt;td&gt;整文件直传，不比较差异&lt;/td&gt;
&lt;td&gt;临时传一两个文件、脚本里简单调用&lt;/td&gt;
&lt;td&gt;大目录、反复同步、断线重传&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;sftp&lt;/td&gt;
&lt;td&gt;交互式会话，像 FTP 一样浏览远端目录&lt;/td&gt;
&lt;td&gt;不确定远端有什么、要挑着传、手动管理远端文件&lt;/td&gt;
&lt;td&gt;自动化脚本、大批量同步&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;rsync&lt;/td&gt;
&lt;td&gt;增量同步，只传有差异的部分&lt;/td&gt;
&lt;td&gt;目录镜像、定时备份、整站迁移、断点续传&lt;/td&gt;
&lt;td&gt;只传单个小文件（杀鸡用牛刀，但也没坏处）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;补充两点容易混淆的事实：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;新版 OpenSSH（9.0 起）的 scp 默认已经改用 SFTP 协议实现，命令用法不变，老脚本不用改；但它依然是「整文件传输」的语义，不会做增量比较。&lt;/li&gt;
&lt;li&gt;sftp 除了交互模式，也支持 &lt;code&gt;sftp user@host:/path/file /local/dir&lt;/code&gt; 这种一把梭的非交互用法，还能用 &lt;code&gt;-b&lt;/code&gt; 读批处理文件执行一串命令，适合半自动场景。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;还有个常见疑问：为什么不用 FTP 或 HTTP 传？FTP 明文传输、还要额外开服务和端口，在服务器之间搬数据毫无优势；HTTP 适合分发不适合同步。这三件工具都复用现成的 SSH 服务，装好系统就有，不用再多开任何端口。&lt;/p&gt;
&lt;h2&gt;二、scp 全套：日常直传够用了&lt;/h2&gt;
&lt;p&gt;scp 的语法和 cp 几乎一样，区别只是源或目标里可以带 &lt;code&gt;用户@主机:&lt;/code&gt; 前缀，表示那是远端路径。&lt;/p&gt;
&lt;h3&gt;上传与下载&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 上传单个文件到远端家目录
scp /etc/nginx/nginx.conf root@192.168.1.20:~

# 上传到远端指定目录
scp ./app.tar.gz deploy@192.168.1.20:/opt/packages/

# 从远端下载文件到当前目录
scp root@192.168.1.20:/var/log/app.log ./

# 从远端下载并改名保存
scp root@192.168.1.20:/root/backup.sql ./backup-2026-11-15.sql
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;传目录：加 -r&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 整个目录递归上传
scp -r ./dist deploy@192.168.1.20:/var/www/html/

# 整个目录下载回来
scp -r root@192.168.1.20:/etc/nginx ./nginx-backup
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;指定端口：大写 P，别写错&lt;/h3&gt;
&lt;p&gt;这是 scp 最著名的坑：ssh 指定端口用小写 &lt;code&gt;-p&lt;/code&gt;，scp 指定端口用大写 &lt;code&gt;-P&lt;/code&gt;。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# ssh 是小写 p
ssh -p 2222 user@192.168.1.20

# scp 是大写 P
scp -P 2222 ./file.tar.gz user@192.168.1.20:/tmp/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;写错会直接报错或连错端口，排查时先看这里。顺带一提，sftp 指定端口同样用大写 &lt;code&gt;-P&lt;/code&gt;，而 ssh 本身的登录、转发全是小写 &lt;code&gt;-p&lt;/code&gt;。记住一条就够：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;scp 和 sftp 的端口参数是大写 -P，只有 ssh 本身是小写 -p。&amp;lt;/span&amp;gt;记混了就现场 &lt;code&gt;man scp&lt;/code&gt; 确认，别凭记忆硬敲生产命令。&lt;/p&gt;
&lt;h3&gt;其他常用选项&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;选项&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-l 速率&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;限速，单位 Kbit/s&lt;/td&gt;
&lt;td&gt;&lt;code&gt;-l 8000&lt;/code&gt; 约等于 1 MB/s，怕跑满带宽影响业务时用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-C&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;传输时压缩&lt;/td&gt;
&lt;td&gt;传文本、日志类文件有效；传已压缩文件无意义&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-i 密钥文件&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;指定私钥&lt;/td&gt;
&lt;td&gt;多密钥环境必备&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-p&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;保留原文件的修改时间与权限&lt;/td&gt;
&lt;td&gt;注意这里小写 p 是 preserve，不是端口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-q&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;安静模式，不显示进度&lt;/td&gt;
&lt;td&gt;脚本里常用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-3&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;两台远端之间互传时经本机中转&lt;/td&gt;
&lt;td&gt;源和目标都是远端主机时才需要&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;scp 的进度条会实时显示百分比、速度和预计剩余时间，这点比老版本友好。但要清醒：scp 传到 99% 断线，这个文件就是废的，只能重传。这正是它不适合大文件和弱网络环境的原因。&lt;/p&gt;
&lt;h2&gt;三、sftp 交互模式：先看看远端有什么&lt;/h2&gt;
&lt;p&gt;不知道远端目录结构、只想挑几个文件时，sftp 的交互模式最顺手：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sftp -P 2222 deploy@192.168.1.20
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;进入后是独立的命令环境，本地和远端各有一套命令（远端命令前不加 l，本地命令加 l 前缀）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sftp&amp;gt; ls /var/log          # 看远端目录
sftp&amp;gt; lls                  # 看本地目录
sftp&amp;gt; cd /var/log          # 切换远端目录
sftp&amp;gt; lcd ~/downloads      # 切换本地目录
sftp&amp;gt; get app.log          # 下载
sftp&amp;gt; get -r logs-2026     # 下载整个目录
sftp&amp;gt; put deploy.sh        # 上传
sftp&amp;gt; put -r ./static      # 上传整个目录
sftp&amp;gt; exit
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;日常用得不多，但救急时很好用：比如登不进对方的 Shell（只给了 SFTP 账号），照样能传文件、建目录（&lt;code&gt;mkdir&lt;/code&gt;）、删文件（&lt;code&gt;rm&lt;/code&gt;）。&lt;/p&gt;
&lt;h2&gt;四、rsync 核心概念：它凭什么只传差异&lt;/h2&gt;
&lt;p&gt;rsync 之所以是同步工具的事实标准，靠的是它的增量传输算法。同步一个目录时，rsync 会先比较源和目标两边的文件列表，默认用「文件大小 + 修改时间」快速判断哪些文件变了；对内容有变化的文件，它用滚动校验算法把文件切块比对，只把真正不同的数据块发过网络。&lt;/p&gt;
&lt;p&gt;这带来两个直接结果：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;第一次是全量，之后每次只传增量。&lt;/strong&gt; 一个 50 GB 的站点目录，每天只有几百 MB 变化，第二次同步就只传这几百 MB。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;中断了可以接着来。&lt;/strong&gt; 配合 &lt;code&gt;--partial&lt;/code&gt;，传了一半的大文件下次从断点继续，而不是从零开始。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;rsync 有两种工作模式：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;模式&lt;/th&gt;
&lt;th&gt;写法&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;本地模式&lt;/td&gt;
&lt;td&gt;&lt;code&gt;rsync -a SRC DEST&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;两边都是本机路径，本质是带增量判断的智能 cp&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;经 SSH 模式&lt;/td&gt;
&lt;td&gt;&lt;code&gt;rsync -a SRC user@host:DEST&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;最常用，复用 SSH 的认证与加密，不用额外部署服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;rsync 守护进程模式&lt;/td&gt;
&lt;td&gt;&lt;code&gt;rsync -a rsync://host/模块&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;需要在服务端单独跑 rsyncd，常用于公共镜像源；自建小规模同步没必要&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;经 SSH 模式下，指定非标准端口用 &lt;code&gt;-e&lt;/code&gt; 把 SSH 命令整个传进去：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 经 SSH 同步，目标机 SSH 端口是 2222
rsync -av -e &quot;ssh -p 2222&quot; ./data/ deploy@192.168.1.20:/srv/data/

# 用指定密钥
rsync -av -e &quot;ssh -i ~/.ssh/id_ed25519 -p 2222&quot; ./data/ deploy@192.168.1.20:/srv/data/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意路径里只要出现 &lt;code&gt;主机:&lt;/code&gt;，rsync 就知道走远端；本地路径写错成带冒号的样子会被误判，路径里有冒号时要用 &lt;code&gt;./&lt;/code&gt; 前缀或绝对路径避开。&lt;/p&gt;
&lt;h2&gt;五、关键选项逐个讲&lt;/h2&gt;
&lt;p&gt;rsync 选项几百个，日常真正离不开的就十来个。先看最经典的组合：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;rsync -avz --progress --partial SRC DEST
&lt;/code&gt;&lt;/pre&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;选项&lt;/th&gt;
&lt;th&gt;全称&lt;/th&gt;
&lt;th&gt;作用与要点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-a&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;archive&lt;/td&gt;
&lt;td&gt;归档模式，一个字母打包了递归、保留符号链接、权限、属主属组、时间戳等一串选项。同步目录默认就带它，几乎是必选项&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-v&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;verbose&lt;/td&gt;
&lt;td&gt;显示正在传的文件清单。想安静就去掉，脚本里常配 &lt;code&gt;--info=progress2&lt;/code&gt; 看总进度&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-z&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;compress&lt;/td&gt;
&lt;td&gt;传输中压缩。只对可压缩内容（代码、文本、日志）有意义；传视频、镜像、压缩包时开启反而白耗 CPU 拖慢速度&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--progress&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;显示每个文件的传输进度&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--partial&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;保留未传完的文件，下次续传。大文件、跨公网同步必备；也可用组合写法 &lt;code&gt;-P&lt;/code&gt;，它等于 &lt;code&gt;--partial --progress&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--bwlimit=速率&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;限速，单位 KB/s。&lt;code&gt;--bwlimit=5000&lt;/code&gt; 约 5 MB/s，业务时段同步大目录时防止打满带宽&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--exclude&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;排除文件或目录，可多次使用，如 &lt;code&gt;--exclude=&apos;*.log&apos; --exclude=&apos;.git/&apos;&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--dry-run&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;空跑演练，只打印会做什么，不实际改动任何文件。危险操作前的标准动作，也常写作 &lt;code&gt;-n&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--checksum&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;用文件内容校验和判断差异，而不是大小+时间。更可靠但更慢，迁移收尾校验时用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--delete&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;删除目标端多出来的文件，让目标成为源的镜像。危险，专节讲&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--timeout=秒&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;网络无数据超时断开，避免弱网下无限挂起&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-H&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;preserve hard links&lt;/td&gt;
&lt;td&gt;保留硬链接关系，备份系统目录时需要，普通同步不用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--numeric-ids&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;不按用户名映射 UID/GID，直接按数字 ID 对齐，跨机器同步时按需使用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;再强调一下 &lt;code&gt;-z&lt;/code&gt; 的适用边界：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;对已经压缩过的文件（.gz、.zip、.jpg、视频、Docker 镜像层）再开 -z，纯属浪费 CPU，速度只会更慢。&amp;lt;/span&amp;gt;判断标准很简单：这批文件用 gzip 还能不能明显变小，能就开，不能就关。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;--exclude&lt;/code&gt; 的模式匹配有几个细节值得记住：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 排除所有 .log 文件、缓存目录和 .git
rsync -av \
  --exclude=&apos;*.log&apos; \
  --exclude=&apos;cache/&apos; \
  --exclude=&apos;.git/&apos; \
  ./app/ deploy@192.168.1.20:/srv/app/
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;模式以 &lt;code&gt;/&lt;/code&gt; 开头表示从源根目录锚定匹配，如 &lt;code&gt;--exclude=&apos;/tmp&apos;&lt;/code&gt; 只排除源根下的 tmp，不排除子目录里的 tmp。&lt;/li&gt;
&lt;li&gt;模式以 &lt;code&gt;/&lt;/code&gt; 结尾表示只匹配目录。&lt;/li&gt;
&lt;li&gt;排除规则多了可以写进文件，用 &lt;code&gt;--exclude-from=&apos;exclude.txt&apos;&lt;/code&gt; 引入，一行一条，迁移和备份脚本里更易维护。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;六、--delete 红线专节：方向写反就是事故&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;--delete&lt;/code&gt; 的语义是：让目标端和源端一模一样，源端没有的文件，目标端也删掉。它是做镜像备份的核心选项，也是 rsync 全部选项里最危险的一个。&lt;/p&gt;
&lt;p&gt;危险不在选项本身，而在方向。rsync 命令的顺序是「源在前、目标在后」，手一抖写反，配合 &lt;code&gt;--delete&lt;/code&gt;，就等于拿空目录去「同步」有数据的那一端：&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;带 --delete 的命令，执行前必须先加 --dry-run 演练一遍，确认输出里要删除的文件全是预期之内的，再去掉 --dry-run 正式跑。&amp;lt;/span&amp;gt;尤其是第一次对一对目录使用 --delete 时，dry-run 的输出要逐行看完。把这一步做成肌肉记忆，能挡掉绝大多数同步事故。
:::&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 第一步：演练，看清楚会传什么、删什么
rsync -av --delete --dry-run ./site/ deploy@192.168.1.20:/srv/site/

# 第二步：确认无误后去掉 --dry-run 正式执行
rsync -av --delete ./site/ deploy@192.168.1.20:/srv/site/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;另外两个和 &lt;code&gt;--delete&lt;/code&gt; 相关的保护措施，知道即可：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;--max-delete=N&lt;/code&gt;：单次最多删 N 个文件，超过就中止。给定时同步任务加上，能在源端异常（比如挂载没跟上、源目录变空）时兜底。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--delete&lt;/code&gt; 的位置也有讲究：默认删除发生在传输过程中，还有 &lt;code&gt;--delete-before&lt;/code&gt;（先删后传）和 &lt;code&gt;--delete-after&lt;/code&gt;（先传后删）。磁盘空间紧张时用 before，一般场景默认即可，不必纠结。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;还有一个真实场景要提醒：如果源目录是挂载点，挂载失败时源目录看起来是个空目录，此时带 &lt;code&gt;--delete&lt;/code&gt; 的定时任务跑起来，会把备份端清空。防御办法除了 &lt;code&gt;--max-delete&lt;/code&gt;，还可以在脚本里先检查源目录的标志文件存在再执行同步。这类防御在备份篇里也有呼应：本站的&lt;a href=&quot;/posts/linux-backup-strategy/&quot;&gt;《Linux 备份策略》&lt;/a&gt;专门讲了备份任务的安全设计，建议对照着看。&lt;/p&gt;
&lt;h2&gt;七、路径末尾斜杠：rsync 最经典的坑&lt;/h2&gt;
&lt;p&gt;rsync 对源路径末尾的斜杠极其敏感，带不带斜杠，语义完全不同：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 不带斜杠：把 data 这个目录本身传过去
rsync -av /srv/data /backup/
# 结果：/backup/data/...

# 带斜杠：把 data 目录里面的内容传过去
rsync -av /srv/data/ /backup/
# 结果：/backup/...（文件直接铺在 backup 下）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;对照表看得更清楚：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;写法&lt;/th&gt;
&lt;th&gt;同步对象&lt;/th&gt;
&lt;th&gt;目标结果&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;rsync -av /srv/data /backup/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;data 目录本身&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/backup/data/文件…&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;rsync -av /srv/data/ /backup/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;data 目录的内容&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/backup/文件…&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;注意：这个区别只作用于&lt;strong&gt;源路径&lt;/strong&gt;，目标路径末尾的斜杠带不带都一样。另外 scp 没有这个讲究，scp 的 &lt;code&gt;-r&lt;/code&gt; 永远是把目录本身拷过去。很多人就是从 scp 的习惯平移过来，在 rsync 上栽了跟头：同步完发现目标端多套了一层目录，或者反过来，文件铺错了层级。&lt;/p&gt;
&lt;p&gt;怎么记？&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;带斜杠＝倒出目录里的东西，不带斜杠＝连盒子一起搬。&amp;lt;/span&amp;gt;迁移和镜像场景里，绝大多数时候你想要的是「内容对内容」，也就是源路径带斜杠。敲命令前停一秒，确认这一对路径的层级关系，能省掉大量返工。&lt;/p&gt;
&lt;h2&gt;八、整站迁移实战：两步走完一次跨机房搬家&lt;/h2&gt;
&lt;p&gt;把前面的知识点组装起来，完成一次真实的整站迁移。场景：把旧服务器上的网站目录 &lt;code&gt;/var/www/site&lt;/code&gt;（含上传文件、静态资源）和一份数据库导出文件，迁移到新服务器，SSH 端口 2222，要求停机时间尽量短。&lt;/p&gt;
&lt;h3&gt;第一步：不停机先做全量预同步&lt;/h3&gt;
&lt;p&gt;业务还在跑，先把大头数据搬过去。这一步慢没关系，不影响线上：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 在新服务器上执行，从旧服务器拉取（推荐拉模式，方便在目标端控制节奏）
rsync -avzP --bwlimit=20000 \
  -e &quot;ssh -p 2222&quot; \
  root@old.example.com:/var/www/site/ /var/www/site/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;说明：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;目标目录末尾的形态要和源保持一致层级，这里源带斜杠、目标也以目录形式承接内容。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;-P&lt;/code&gt; 同时开启断点续传和进度显示，几十 GB 传几个小时，中途断了重跑同一条命令即可，已完成的文件会自动跳过。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--bwlimit&lt;/code&gt; 按实际带宽留有余量，避免预同步把业务带宽吃光。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;第二步：停服务，做增量收尾&lt;/h3&gt;
&lt;p&gt;选业务低峰期，停掉旧服务器上的 Web 服务和写入型任务（保证数据不再变化），再跑一遍同一条命令。这次只有第一步之后变化的增量文件要传，通常几分钟就结束：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 旧服务器上先停服务（以 Nginx + PHP-FPM 为例）
systemctl stop nginx php8.2-fpm

# 新服务器上再跑一遍增量同步
rsync -avzP \
  -e &quot;ssh -p 2222&quot; \
  root@old.example.com:/var/www/site/ /var/www/site/
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第三步：校验，别凭感觉宣布迁移完成&lt;/h3&gt;
&lt;p&gt;同步命令没报错，不等于数据完整。用两种方式交叉验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 方式一：带 --checksum 做一次校验型 dry-run
# 输出为空（没有待传文件）说明两边内容一致
rsync -avc --dry-run \
  -e &quot;ssh -p 2222&quot; \
  root@old.example.com:/var/www/site/ /var/www/site/

# 方式二：对比两边文件总数和总大小
find /var/www/site -type f | wc -l          # 新机执行
ssh -p 2222 root@old.example.com &quot;find /var/www/site -type f | wc -l&quot;
du -sh /var/www/site                        # 两边各执行一次对比
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--checksum&lt;/code&gt; 会逐个文件算校验和，慢，但这是收尾校验该有的严谨；日常增量同步靠大小+时间判断就够了，不要每次都开。两边文件数、总大小、校验 dry-run 三项都对得上，再启动新服务器的服务、切 DNS，这次迁移才算落地。切换后旧服务器先别急着下线，保留几天做回滚兜底，这是迁移的基本纪律。更完整的异地备份与保留策略，可以看&lt;a href=&quot;/posts/linux-backup-strategy/&quot;&gt;《Linux 备份策略》&lt;/a&gt;那篇。&lt;/p&gt;
&lt;p&gt;数据库文件不在 rsync 的职责内：用数据库自己的导出导入或主从复制迁移，rsync 只负责搬导出的文件本身，千万不要在数据库运行中直接 rsync 它的原始数据目录，拷出来的文件大概率是不一致的损坏状态。&lt;/p&gt;
&lt;h2&gt;九、权限与属主：-a 保留了什么，又保留不了什么&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;-a&lt;/code&gt; 会保留权限位、时间戳、符号链接，以及——在以 root 身份运行时——文件属主和属组。这里有个跨机器的固有问题：rsync 默认按&lt;strong&gt;用户名&lt;/strong&gt;映射属主，两台机器上同名用户的 UID 可能不一样；没有同名用户时，属主就会落到某个数字 UID 上，看起来「乱了」。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;表现&lt;/th&gt;
&lt;th&gt;处理&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;两边都用 root 同步，用户体系一致&lt;/td&gt;
&lt;td&gt;属主属组原样保留&lt;/td&gt;
&lt;td&gt;无需处理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;两边同名用户 UID 不同&lt;/td&gt;
&lt;td&gt;文件属主按名字对齐，UID 随目标机&lt;/td&gt;
&lt;td&gt;一般可接受；介意就加 &lt;code&gt;--numeric-ids&lt;/code&gt; 按数字对齐&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;用普通用户同步&lt;/td&gt;
&lt;td&gt;无法 chown 到别人，属主变成该普通用户自己&lt;/td&gt;
&lt;td&gt;属主敏感的数据（网站文件、服务数据）用 root 同步&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;同步到 Windows/NTFS 或 FAT 文件系统&lt;/td&gt;
&lt;td&gt;权限位、属主无处安放，会告警或丢失&lt;/td&gt;
&lt;td&gt;这类目标只适合存压缩包，不适合直接同步目录树&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一条经验：凡是服务要按特定属主运行的数据（比如 Web 目录属于 www-data、数据库目录属于 mysql），迁移后启动服务前，先在新机上核对一遍属主和权限，&lt;code&gt;ls -ln&lt;/code&gt; 看数字 ID 最直观。属主不对，服务轻则报错重则起不来，这是迁移后第一类要排查的问题。&lt;/p&gt;
&lt;h2&gt;十、排障小节&lt;/h2&gt;
&lt;h3&gt;传一半断了&lt;/h3&gt;
&lt;p&gt;先看是不是网络抖动或目标磁盘满（&lt;code&gt;df -h&lt;/code&gt; 先查）。重新执行同一条 rsync 命令即可：已传完的文件靠大小+时间判断自动跳过，传了一半的大文件有 &lt;code&gt;--partial&lt;/code&gt; 保留的残件会接着传。如果当时没加 &lt;code&gt;--partial&lt;/code&gt;，那个大文件只能重传——所以跨公网、大文件场景，&lt;code&gt;-P&lt;/code&gt; 应该成为默认写法。scp 断了没得商量，从头再来。&lt;/p&gt;
&lt;h3&gt;速度莫名其妙地慢&lt;/h3&gt;
&lt;p&gt;按这个顺序排查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;是不是对压缩过的文件开了 &lt;code&gt;-z&lt;/code&gt;&lt;/strong&gt;：镜像、视频、压缩包占大头时关掉 &lt;code&gt;-z&lt;/code&gt; 再试，这是最常见的原因。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;SSH 加密的 CPU 瓶颈&lt;/strong&gt;：低配机器上加密吞吐可能跑不满带宽，&lt;code&gt;top&lt;/code&gt; 看 rsync 和 ssh 进程是不是吃满一个核。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;小文件太多&lt;/strong&gt;：几十万个小文件时，瓶颈在文件枚举和逐个建连的开销，不在带宽。可以先打包成 tar 传过去再解包，或者接受这个速度。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;磁盘本身慢&lt;/strong&gt;：两端任一端磁盘 IO 不行都会拖住全局，用 &lt;code&gt;iostat -x 1&lt;/code&gt;（sysstat 包）看利用率。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;权限拒绝（Permission denied）&lt;/h3&gt;
&lt;p&gt;分两类看：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;SSH 层面的拒绝&lt;/strong&gt;：密钥不对、端口写错（回看第二节大写 P 的坑）、目标机 sshd 配置限制。先单独 &lt;code&gt;ssh&lt;/code&gt; 登录验证通了，再跑 rsync。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;文件层面的拒绝&lt;/strong&gt;：目标目录属主不对，同步账号没写权限；或者源端有些文件普通用户读不了。用 root 同步能绕开大部分，但要想清楚这批数据到底该归谁，别图省事把权限体系搞乱。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;同步完发现多了一层目录或文件铺错层&lt;/h3&gt;
&lt;p&gt;不用问，第七节的斜杠坑。删掉错误层级（删之前先确认哪份是对的），修正命令重跑。这也是为什么正式同步前先 &lt;code&gt;--dry-run&lt;/code&gt; 看一眼文件路径列表——路径层级对不对，dry-run 输出里一目了然。&lt;/p&gt;
&lt;h3&gt;两边明明一样，每次却全量重传&lt;/h3&gt;
&lt;p&gt;多半是时间戳对不齐：源端文件时间比目标端新（比如源端刚被 touch 过），或者两边时钟差太多，导致快速判断总认为文件变了。加 &lt;code&gt;--checksum&lt;/code&gt; 跑一次校验确认内容确实一致，之后检查两台机器的时间同步状态（NTP 是否正常），并确认用了 &lt;code&gt;-a&lt;/code&gt; 保留时间戳。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;选工具先看场景：scp 管一次性直传，sftp 管交互挑选，rsync 管一切增量同步与迁移。&lt;/li&gt;
&lt;li&gt;scp 的端口是大写 &lt;code&gt;-P&lt;/code&gt;，和 ssh 的小写 &lt;code&gt;-p&lt;/code&gt; 不是一回事，写错先查这里。&lt;/li&gt;
&lt;li&gt;rsync 的日常组合是 &lt;code&gt;-av&lt;/code&gt; 打底，大文件跨公网加 &lt;code&gt;-P&lt;/code&gt; 断点续传，可压缩内容才开 &lt;code&gt;-z&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--delete&lt;/code&gt; 是镜像同步的灵魂，也是事故之源：执行前必须先 &lt;code&gt;--dry-run&lt;/code&gt;，并确认源、目标方向没写反。&lt;/li&gt;
&lt;li&gt;源路径末尾的斜杠决定传「目录本身」还是「目录内容」，敲命令前停一秒确认层级。&lt;/li&gt;
&lt;li&gt;整站迁移的标准姿势是两步走：不停机全量预同步，停服务后增量收尾，最后用 &lt;code&gt;--checksum&lt;/code&gt; 的 dry-run 加文件数对比做校验。&lt;/li&gt;
&lt;li&gt;跨机器同步注意属主映射：同名用户 UID 不一致时按名字对齐，属主敏感的数据用 root 同步并在事后核对。&lt;/li&gt;
&lt;li&gt;出了问题先分层：SSH 通不通、磁盘满不满、选项用对没——顺序排下来，大多数故障都能当场定位。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>防火墙实战：UFW 与 nftables</title><link>https://www.anexns.cloudns.org/posts/linux-firewall-ufw-nftables/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-firewall-ufw-nftables/</guid><description>服务器只对外开该开的门：防火墙的默认拒绝思路、UFW 快速上手、nftables 的规则结构入门，再讲清云防火墙与系统防火墙的分工，以及 Docker 改写转发规则这个经典大坑。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;服务器买回来、系统装好、SSH 也加固了（还没做的先看&lt;a href=&quot;/posts/linux-ssh-hardening/&quot;&gt;《SSH 安全加固》&lt;/a&gt;），下一步就是把「门」管起来。一台默认装好的 Debian，系统本身可能没开几个端口，但只要你陆续装上 Docker、数据库、面板、各种服务，暴露在公网上的入口会越来越多。防火墙干的就是一件事：&lt;strong&gt;明确哪些流量能进来、哪些不能&lt;/strong&gt;，而不是靠「应该没人扫到我」赌运气。&lt;/p&gt;
&lt;p&gt;本篇主线：先讲清思路（默认拒绝＋白名单），再看三层防线怎么分工，然后两条工具路线二选一——图省事用 UFW，想打基础学 nftables，最后单独讲 Docker 绕过 UFW 这个坑了无数人的经典问题。&lt;/p&gt;
&lt;h2&gt;一、思路先行：默认拒绝，白名单放行&lt;/h2&gt;
&lt;p&gt;防火墙的策略只有两种基本形态：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;策略&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;结果&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;默认允许，黑名单拦截&lt;/td&gt;
&lt;td&gt;什么都能进，只挡名单上的&lt;/td&gt;
&lt;td&gt;名单永远列不全，等于没挡&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;默认拒绝，白名单放行&lt;/td&gt;
&lt;td&gt;什么都不能进，只放名单上的&lt;/td&gt;
&lt;td&gt;新服务默认进不来，需要时再开&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;结论不用犹豫：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;入站一律默认拒绝，只逐个放行真正需要对外的端口。&amp;lt;/span&amp;gt;这样哪怕某个服务你忘了它在监听、或者软件自己偷偷开了个管理端口，外面也连不进来。代价只是每次上新服务时多敲一条放行命令，这笔账非常划算。&lt;/p&gt;
&lt;p&gt;先分清两个方向：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;入站（incoming）&lt;/strong&gt;：别人主动连你的服务器，这是防护重点，默认拒绝。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;出站（outgoing）&lt;/strong&gt;：你的服务器主动连外网（系统更新、拉镜像、调 API 都靠它），个人服务器一般默认允许；只有对安全要求极高的场景才连出站一起管。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;动手加规则之前，先看清自己现在开了什么门。Debian 上一条命令列出所有正在监听的 TCP/UDP 端口和对应进程：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ss -tlnp
ss -ulnp
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐行对一遍：每个监听端口你都认识吗？该对外的（SSH、80、443）留下；只该本机用的（数据库、内部服务）记下来，后面要么让它只绑 &lt;code&gt;127.0.0.1&lt;/code&gt;，要么用防火墙挡住。再配合从外面验证一次——在自己电脑上对服务器做一次端口扫描，结果应该和你的预期完全一致：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;nmap -Pn &amp;lt;服务器IP&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
先自查再上规则。很多人防火墙配了一大堆，实际暴露面里却躺着一个自己都忘了的服务。防火墙是第二道保险，第一道是「不该监听的别监听」。
:::&lt;/p&gt;
&lt;h2&gt;二、三层防线：云安全组、系统防火墙、应用绑定&lt;/h2&gt;
&lt;p&gt;一台云服务器的入站流量，实际会经过三道关卡，它们不是互相替代，而是各管一段：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;层级&lt;/th&gt;
&lt;th&gt;是什么&lt;/th&gt;
&lt;th&gt;管什么&lt;/th&gt;
&lt;th&gt;典型翻车点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;云厂商安全组&lt;/td&gt;
&lt;td&gt;机房网络层的虚拟防火墙（各家云控制台里配）&lt;/td&gt;
&lt;td&gt;流量还没到服务器网卡就先筛一遍&lt;/td&gt;
&lt;td&gt;控制台里没放行，系统里配得再对也不通&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;系统防火墙&lt;/td&gt;
&lt;td&gt;服务器操作系统内的 UFW / nftables&lt;/td&gt;
&lt;td&gt;到了网卡之后的精细控制：来源 IP、端口组合、限速&lt;/td&gt;
&lt;td&gt;规则顺序写错、和 Docker 的规则互相打架&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;应用自身绑定&lt;/td&gt;
&lt;td&gt;服务监听地址，如只绑 &lt;code&gt;127.0.0.1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;从源头上决定这个服务对不对外&lt;/td&gt;
&lt;td&gt;数据库绑了 &lt;code&gt;0.0.0.0&lt;/code&gt; 又没人管，等于裸奔&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;为什么不能只靠一层？只靠云安全组，规则散落在各家控制台里，迁移服务器时全丢，而且粒度通常只到端口和来源 IP；只靠系统防火墙，规则跟着系统走没问题，但万一系统防火墙被误关或配置丢失，就是全裸状态；应用绑定最干脆，但不是每个软件都支持、也容易漏配。三层的意义是任何一层出问题，还有另外两层兜底。&lt;/p&gt;
&lt;p&gt;尤其是数据库这类服务，正确姿势是应用层只绑 &lt;code&gt;127.0.0.1&lt;/code&gt;（或干脆走 Unix socket），云安全组和系统防火墙里&lt;strong&gt;根本不给它开端口&lt;/strong&gt;——三层一致，不给侥幸留空子。&lt;/p&gt;
&lt;h2&gt;三、UFW 实战：五分钟管住一台服务器&lt;/h2&gt;
&lt;p&gt;UFW（Uncomplicated Firewall）是 Debian/Ubuntu 系最常用的防火墙前端，语法接近人话，适合绝大多数个人服务器。注意：它是&lt;strong&gt;前端&lt;/strong&gt;，底层最终还是生成 nftables/iptables 规则，所以后面会说不要再拿另一套工具同时管。&lt;/p&gt;
&lt;h3&gt;安装与初始策略&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;apt update &amp;amp;&amp;amp; apt install -y ufw
ufw default deny incoming
ufw default allow outgoing
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;放行端口&lt;/h3&gt;
&lt;p&gt;先放行 SSH——&lt;strong&gt;顺序千万别反&lt;/strong&gt;，见下方警告。假设你的 SSH 端口已经按加固篇改成了 &lt;code&gt;3526&lt;/code&gt;（没改的用默认 &lt;code&gt;22&lt;/code&gt;，下文同理替换）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ufw allow 3526/tcp          # SSH
ufw allow 80/tcp            # HTTP（跳转 HTTPS 也要它）
ufw allow 443/tcp           # HTTPS
ufw allow 443/udp           # 如果跑了 HTTP/3 或基于 UDP 的服务再加这条
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;也可以用服务名放行，效果相同：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ufw allow &apos;WWW Full&apos;
ufw app list                # 查看所有可用的应用预设
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;限定来源 IP：管理端口只给自己开&lt;/h3&gt;
&lt;p&gt;面板、数据库管理口这类敏感入口，最佳做法不是「开着但靠密码」，而是只允许你自己的 IP 连。比如只允许 &lt;code&gt;203.0.113.10&lt;/code&gt; 访问服务器的某个管理端口 &lt;code&gt;8443&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ufw allow from 203.0.113.10 to any port 8443 proto tcp
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;家里宽带 IP 会变的话，可以放行一整个段，或者干脆让管理服务只绑 &lt;code&gt;127.0.0.1&lt;/code&gt; 再走 SSH 隧道访问——后者更稳，防火墙里连这条规则都不用留。&lt;/p&gt;
&lt;h3&gt;查看与删除规则&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;ufw status                  # 简览
ufw status numbered         # 带编号的详细列表
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;删除规则有两种方式，编号删除最直观：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ufw delete 3                # 删除编号为 3 的规则（编号以 status numbered 为准）
ufw delete allow 8080/tcp   # 或按规则内容删除
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;启用&lt;/h3&gt;
&lt;p&gt;确认 SSH 放行规则已经加上之后，才执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ufw enable
ufw status verbose
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
**启用 UFW 之前，必须先放行你当前正在用的 SSH 端口。**一旦忘了放行就 enable，当前连接断开的瞬间你就会被锁在自己服务器外面，只能去云厂商控制台用 VNC/救援模式补救。正确顺序永远是：先 &lt;code&gt;ufw allow &amp;lt;SSH端口&amp;gt;&lt;/code&gt;，再 &lt;code&gt;ufw enable&lt;/code&gt;。
:::&lt;/p&gt;
&lt;p&gt;UFW 的规则重启后依然有效（它有自己的服务负责开机加载），不用额外做持久化。&lt;/p&gt;
&lt;h2&gt;四、nftables 入门：看懂规则长什么样&lt;/h2&gt;
&lt;p&gt;如果你想把基础打牢，或者服务器上已经不用 UFW 了，nftables 是现在的正统——Debian 10 起它就是默认框架，iptables 实际上也已经是它的一层兼容外壳。nftables 的配置集中在一个文件 &lt;code&gt;/etc/nftables.conf&lt;/code&gt; 里，结构是三层：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;table（表）&lt;/strong&gt;：一个规则的命名空间，按地址族分，如 &lt;code&gt;inet&lt;/code&gt;（IPv4＋IPv6 一起管，最常用）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;chain（链）&lt;/strong&gt;：挂在某个钩子（hook）上的规则序列，比如 &lt;code&gt;input&lt;/code&gt; 链处理入站流量，链上要声明默认策略 &lt;code&gt;policy drop&lt;/code&gt; 或 &lt;code&gt;policy accept&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;rule（规则）&lt;/strong&gt;：链里的一条条匹配条件＋动作（&lt;code&gt;accept&lt;/code&gt; / &lt;code&gt;drop&lt;/code&gt;）。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;一份可直接用的最小配置（SSH 端口同样以 &lt;code&gt;3526&lt;/code&gt; 为例，按你的实际端口改）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/usr/sbin/nft -f

flush ruleset

table inet filter {
    chain input {
        type filter hook input priority 0; policy drop;

        # 已建立的连接和本机回环，永远放行
        ct state established,related accept
        iif &quot;lo&quot; accept

        # 基础网络功能：ICMP（ping、路径 MTU 发现都要它）
        ip protocol icmp accept
        ip6 nexthdr icmpv6 accept

        # 对外服务白名单
        tcp dport 3526 accept
        tcp dport { 80, 443 } accept
        udp dport 443 accept
    }

    chain forward {
        type filter hook forward priority 0; policy drop;
    }

    chain output {
        type filter hook output priority 0; policy accept;
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐段看关键点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;flush ruleset&lt;/code&gt;：每次加载先清空旧规则，保证文件内容就是最终状态，不叠加残留。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;policy drop&lt;/code&gt;：input 链的默认策略是丢弃——这就是「默认拒绝」的落点，没写明放行的流量到链尾自动被丢掉。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;ct state established,related accept&lt;/code&gt;：放行「已建立连接的回包」。没有这条，你 SSH 连进来之后的回数据、服务器对外请求拿到的响应都会被自己的防火墙拦掉，这是新手配置最常见的断网原因。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;iif &quot;lo&quot; accept&lt;/code&gt;：本机回环接口全放行，大量本机服务间通信走它，不能拦。&lt;/li&gt;
&lt;li&gt;ICMP 不要一刀切全禁：禁掉之后 ping 不通只是小事，路径 MTU 发现失效会导致某些 HTTPS 连接莫名卡住。个人服务器直接放行即可。&lt;/li&gt;
&lt;li&gt;端口集合写法 &lt;code&gt;{ 80, 443 }&lt;/code&gt; 是 nftables 的便利语法，一条规则管多个端口。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;加载与验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;nft -c -f /etc/nftables.conf   # 只做语法检查，先验再上
nft -f /etc/nftables.conf      # 正式加载
nft list ruleset               # 查看当前生效的全部规则
systemctl enable nftables      # 开机自动加载 /etc/nftables.conf
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Debian 的 nftables 服务默认就是读取 &lt;code&gt;/etc/nftables.conf&lt;/code&gt;，&lt;code&gt;systemctl enable nftables&lt;/code&gt; 之后重启不丢失。&lt;/p&gt;
&lt;p&gt;:::warning
改 nftables 配置时，同样先保证 SSH 放行写在文件里再加载。更稳妥的做法是先开一个保底：执行 &lt;code&gt;nft -f&lt;/code&gt; 前另开一个已经连着的 SSH 会话别关，新规则出问题时老会话往往还能用；或者先用云控制台的 VNC 登录着再操作。
:::&lt;/p&gt;
&lt;h2&gt;五、选型：UFW 和 nftables 用哪个&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;UFW&lt;/th&gt;
&lt;th&gt;nftables 原生&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;上手难度&lt;/td&gt;
&lt;td&gt;低，命令接近人话&lt;/td&gt;
&lt;td&gt;中，要理解 table/chain 结构&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;配置形态&lt;/td&gt;
&lt;td&gt;一条条命令追加&lt;/td&gt;
&lt;td&gt;一个声明式配置文件，整体可版本管理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;规则可读性&lt;/td&gt;
&lt;td&gt;&lt;code&gt;status&lt;/code&gt; 输出够用&lt;/td&gt;
&lt;td&gt;&lt;code&gt;nft list ruleset&lt;/code&gt; 全貌一目了然&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合场景&lt;/td&gt;
&lt;td&gt;单机、规则不多、图省事&lt;/td&gt;
&lt;td&gt;规则复杂、想把配置纳入 Git 管理、排斥额外抽象&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;底层&lt;/td&gt;
&lt;td&gt;生成 nftables/iptables 规则&lt;/td&gt;
&lt;td&gt;内核原生框架&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选哪个都行，但有一条硬规矩：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要同时用两套工具管理同一套规则。&amp;lt;/span&amp;gt;UFW 启用后，它会在开机时加载自己生成的规则集；你再手写 &lt;code&gt;/etc/nftables.conf&lt;/code&gt; 去 &lt;code&gt;flush ruleset&lt;/code&gt;，就会把 UFW 的规则一起冲掉，反过来 UFW 重载也会覆盖你的手写规则——表现就是「规则时灵时不灵」，排查起来极其折磨。&lt;strong&gt;一台机器选定一套，全程只用它。&lt;/strong&gt;&lt;/p&gt;
&lt;h2&gt;六、Docker 大坑：发布端口绕过 UFW&lt;/h2&gt;
&lt;p&gt;这是本篇最重要的部分，无数人栽在这里：你在 UFW 里明明没有放行 &lt;code&gt;8080&lt;/code&gt;，可 Docker 容器发布了 &lt;code&gt;8080:80&lt;/code&gt; 之后，全世界都能直接访问这个端口，UFW 形同虚设。&lt;/p&gt;
&lt;h3&gt;现象与原理&lt;/h3&gt;
&lt;p&gt;复现很简单：起一个映射了端口的容器（映射的详细语法见&lt;a href=&quot;/posts/docker-network/&quot;&gt;《Docker 网络详解》&lt;/a&gt;），然后从外网直连该端口——通的，完全不受 UFW 入站规则约束。&lt;/p&gt;
&lt;p&gt;原理一句话：Docker 在启动时往内核的转发路径里写了自己的规则（传统上是 iptables 的 &lt;code&gt;DOCKER&lt;/code&gt; 链和 NAT 规则），而容器流量走的是 &lt;strong&gt;forward（转发）路径&lt;/strong&gt;，UFW 的入站规则主要挂在 &lt;strong&gt;input（本机入站）路径&lt;/strong&gt;上——流量根本不经过 UFW 的那道门，自然拦不住。&lt;/p&gt;
&lt;h3&gt;三种解法（按推荐顺序）&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;解法一（首选）：端口只绑 &lt;code&gt;127.0.0.1&lt;/code&gt;，前面套反向代理。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;发布端口时把绑定地址写死为本机：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ports:
  - &quot;127.0.0.1:8080:80&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这样容器端口只在本机可达，外界连不进来；对外服务统一由宿主机上的 Nginx/Caddy 反向代理转发，反代的 80/443 是你本来就放行的。绝大多数 Web 类服务都应该这么部署，这是最干净、和防火墙零冲突的方案。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;解法二：用 &lt;code&gt;DOCKER-USER&lt;/code&gt; 链补规则。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Docker 官方预留了 &lt;code&gt;DOCKER-USER&lt;/code&gt; 链，转发流量会先过它，你可以在这里加拦截，比如禁止外部直连所有容器发布端口、只放行本机和内网：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;iptables -I DOCKER-USER -i eth0 ! -s 127.0.0.1 -j DROP
iptables -L DOCKER-USER -n --line-numbers
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意网卡名换成你的公网网卡（&lt;code&gt;ip route&lt;/code&gt; 看默认路由那块），并且这条规则重启或 Docker 重启后可能丢失，需要自己写进启动脚本做持久化，属于「能用但要操心」的方案。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;解法三：ufw-docker 类第三方工具。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;社区有 &lt;code&gt;ufw-docker&lt;/code&gt; 脚本（chaifeng/ufw-docker），它帮你把针对 Docker 的拦截规则正确地注入，并提供 &lt;code&gt;ufw-docker allow &amp;lt;容器&amp;gt; &amp;lt;端口&amp;gt;&lt;/code&gt; 这样的语法，相当于给 UFW 打了个 Docker 补丁。省事，但引入了第三方脚本依赖，更新 UFW/Docker 时要留意兼容性。&lt;/p&gt;
&lt;p&gt;优先级很明确：能用解法一就别用后两种。需要容器端口直接对外的少数场景（如游戏服务器、非 HTTP 协议服务），再考虑解法二或三，或者干脆只在云安全组那层做来源限制、多层配合。&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;装了 Docker 的机器，绝对不能凭「UFW 没放行」就断定某个端口没暴露。&amp;lt;/span&amp;gt;判断暴露面的唯一可靠办法是动手实测：从外网对服务器的常用端口逐个扫一遍（&lt;code&gt;nmap&lt;/code&gt;），或者直接拿手机流量访问 &lt;code&gt;http://&amp;lt;服务器IP&amp;gt;:&amp;lt;端口&amp;gt;&lt;/code&gt; 试。测出来的结果和你的预期不一致，就说明有规则在你不知道的地方放行了流量。
:::&lt;/p&gt;
&lt;h2&gt;七、排障小节&lt;/h2&gt;
&lt;h3&gt;规则加了却不生效&lt;/h3&gt;
&lt;p&gt;按这个顺序查，基本能定位：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;云安全组开了吗？&lt;/strong&gt; 系统防火墙放行了，但云厂商控制台的安全组没放行，流量在网卡之前就被丢了——这是最常见的原因，先去控制台确认。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;规则顺序对吗？&lt;/strong&gt; nftables 里规则自上而下匹配，命中即停；UFW 同理。&lt;code&gt;ufw status numbered&lt;/code&gt; / &lt;code&gt;nft list ruleset&lt;/code&gt; 把顺序拉出来看，是不是有一条宽泛的 drop 排在了放行前面。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;协议和地址族对吗？&lt;/strong&gt; 只放了 &lt;code&gt;tcp&lt;/code&gt; 却跑的是 UDP 服务、只放了 IPv4 却从 IPv6 连进来，都会表现为「明明放行了却不通」。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;服务本身在监听吗？&lt;/strong&gt; 回到源头 &lt;code&gt;ss -tlnp&lt;/code&gt;，防火墙放行了一个根本没人监听的端口，自然连不上。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;把自己关在门外&lt;/h3&gt;
&lt;p&gt;启用防火墙时漏放 SSH、或者改规则时误删了 SSH 放行，SSH 新连接进不去。补救路径：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;用云厂商控制台的 &lt;strong&gt;VNC / 网页终端&lt;/strong&gt;登录（它不走 SSH，相当于站在机房里接显示器）。&lt;/li&gt;
&lt;li&gt;进去后先临时关掉防火墙保平安：&lt;code&gt;ufw disable&lt;/code&gt;，或 nftables 用 &lt;code&gt;nft flush ruleset&lt;/code&gt; 清空。&lt;/li&gt;
&lt;li&gt;把 SSH 放行规则补回去，&lt;code&gt;ss -tlnp&lt;/code&gt; 确认 SSH 实际监听端口和规则里写的一致，再重新启用防火墙。&lt;/li&gt;
&lt;li&gt;如果这台机器连控制台救援都没有，那就只剩工单联系厂商一条路了——所以&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;改防火墙规则之前，务必先确认自己有 SSH 之外的第二条登录通道&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;重启后规则丢失&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;UFW&lt;/strong&gt;：规则自带持久化，重启丢失一般是 ufw 服务没启用，&lt;code&gt;systemctl enable --now ufw&lt;/code&gt; 后再 &lt;code&gt;ufw status&lt;/code&gt; 确认。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;nftables&lt;/strong&gt;：只用 &lt;code&gt;nft add rule ...&lt;/code&gt; 在命令行临时加的规则，重启必丢；写进 &lt;code&gt;/etc/nftables.conf&lt;/code&gt; 并 &lt;code&gt;systemctl enable nftables&lt;/code&gt; 才会开机加载。临时规则验证有效后，记得回写到配置文件里。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Docker 的 &lt;code&gt;DOCKER-USER&lt;/code&gt; 链规则&lt;/strong&gt;：同理，手动加的 iptables 规则重启不保留，需要脚本在 Docker 启动后重新注入。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;规则明明在，却还是被扫到端口&lt;/h3&gt;
&lt;p&gt;大概率就是第六节的 Docker 问题，或者服务自己绑了别的网卡。用 &lt;code&gt;ss -tlnp&lt;/code&gt; 看监听地址，再从外网实测复核，不要只盯着防火墙规则列表自我安慰。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;防火墙的正确姿势是&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;默认拒绝入站、白名单逐个放行&amp;lt;/span&amp;gt;，动手前先用 &lt;code&gt;ss -tlnp&lt;/code&gt; 摸清自己的暴露面。&lt;/li&gt;
&lt;li&gt;云安全组、系统防火墙、应用只绑 &lt;code&gt;127.0.0.1&lt;/code&gt; 是三层不同的防线，叠起来才稳，别只靠一层。&lt;/li&gt;
&lt;li&gt;UFW 图省事、nftables 打基础，二选一即可，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;切忌两套工具同时管同一套规则&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;li&gt;启用或修改防火墙前，先放行 SSH、先确认有控制台救援通道，防自锁是第一课。&lt;/li&gt;
&lt;li&gt;Docker 发布端口会绕过 UFW 的入站规则：首选解法是端口只绑 &lt;code&gt;127.0.0.1&lt;/code&gt; 加反向代理，其次是 &lt;code&gt;DOCKER-USER&lt;/code&gt; 链，最后才考虑第三方工具；判断端口是否暴露，永远以从外网实测为准。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>内核参数与系统调优</title><link>https://www.anexns.cloudns.org/posts/linux-kernel-tuning/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-kernel-tuning/</guid><description>sysctl 常用项逐个讲清、文件句柄上限的三层配置、Swap 的创建与 swappiness，再立一条铁律：任何调优先备份、可回滚，小步验证再上量。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h1&gt;内核参数与系统调优&lt;/h1&gt;
&lt;p&gt;服务器跑了一段时间，总会有人告诉你：「把这几个内核参数改了，性能立马起飞。」然后甩给你一整页 &lt;code&gt;sysctl&lt;/code&gt; 配置，从 TCP 缓冲区到文件句柄上限，几十项一股脑全上。照着抄完，机器可能确实没出事，也可能在某个深夜因为一个不合适的参数悄悄埋雷。内核参数是 Linux 运维里最容易被神化、也最容易被滥用的一块：它确实能解决真问题，但前提是你手里先有瓶颈的证据，而不是先有参数的冲动。&lt;/p&gt;
&lt;p&gt;这篇的主线很明确：先立调优的纪律，再讲清 &lt;code&gt;sysctl&lt;/code&gt; 的机制，然后把最常被提及的几个参数逐个拆开——它管什么、什么场景才需要动、动到什么程度算合理；接着是文件句柄的三层限制体系，这是生产环境报错「Too many open files」时真正的排查主战场；再讲 Swap 的创建与 &lt;code&gt;swappiness&lt;/code&gt; 的真实含义；最后用 BBR 收尾，并给出一套改后验证与排障的方法。读完你应该能做到：看到任何一份「一键优化参数包」时，先问一句——它解决的是我的哪个瓶颈？&lt;/p&gt;
&lt;p&gt;如果你还没建立起「先定位瓶颈」的习惯，建议先看本系列的 &lt;a href=&quot;/posts/linux-performance-troubleshooting/&quot;&gt;Linux 性能排障&lt;/a&gt; 那篇，里面讲了 CPU、内存、磁盘、网络四条线的定位方法。这篇是它的续篇：排障负责找到证据，调优负责在证据之上动刀。&lt;/p&gt;
&lt;h2&gt;一、调优的纪律先行&lt;/h2&gt;
&lt;p&gt;在敲下任何一条 &lt;code&gt;sysctl&lt;/code&gt; 命令之前，先把四条纪律钉死。它们看起来像老生常谈，但生产事故复盘里，绝大多数「调优翻车」都不是参数本身错了，而是流程错了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一，先有瓶颈证据，再动参数。&lt;/strong&gt; 参数是药，不是饭。&lt;code&gt;net.core.somaxconn&lt;/code&gt; 调大，只对「连接队列溢出导致请求被丢弃」这一种病有效；如果你的服务慢是因为磁盘 IO 打满，把 TCP 参数翻十倍也毫无作用。正确的顺序永远是：监控或排障发现异常指标 → 确认瓶颈点 → 找到对应参数 → 小步调整 → 对比指标变化。没有第一步，后面全是玄学。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二，一次只改一项。&lt;/strong&gt; 同时改五项参数，指标变好了你不知道是哪项的功劳，变坏了你也不知道是哪项的锅。一次一项、改完观察，是唯一能把因果关系理清楚的办法。嫌慢？出一次事故回滚全量配置的时间，比逐项调整多得多。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三，改前备份原值。&lt;/strong&gt; 每个参数调整之前，先把当前值记录下来。方法很简单：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 改之前，先把要动的几个参数现值存档
sysctl net.core.somaxconn net.ipv4.tcp_max_syn_backlog vm.swappiness fs.file-max | tee ~/sysctl-before-$(date +%F).txt

# 也可以直接备份整份现行配置目录
sudo cp -a /etc/sysctl.conf ~/sysctl.conf.bak 2&amp;gt;/dev/null
sudo cp -a /etc/sysctl.d ~/sysctl.d.bak
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;备份的意义不是仪式感，而是让回滚变成「把数字写回去」这种十秒钟的操作，而不是对着搜索引擎回忆默认值。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第四，不要整包照抄网上的参数集。&lt;/strong&gt; 这是最重要的一条，单独用提示框强调：&lt;/p&gt;
&lt;p&gt;:::warning
网上流传的「Linux 一键优化参数包」往往是针对特定场景（高并发代理、大流量下载站、游戏服务器）调出来的，场景和你的机器对不上时，参数轻则无效，重则有害：比如把 TCP 缓冲区上限拉到几百 MB，在内存小的机器上高并发时可能直接把内存吃干。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;整包照抄等于把别人机器的药方吃进自己肚子里&amp;lt;/span&amp;gt;，出问题时你甚至不知道该怀疑哪一项。
:::&lt;/p&gt;
&lt;p&gt;记住本篇的第一句核心结论：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;调优的目标是消除已证实的瓶颈，不是把参数调到看起来很厉害&amp;lt;/span&amp;gt;。没有证据的参数调整，本质上是在给未来的排障增加干扰项。&lt;/p&gt;
&lt;h2&gt;二、sysctl 机制：参数到底从哪来、往哪写&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;sysctl&lt;/code&gt; 是内核暴露给用户空间的配置接口，绝大多数内核参数都映射为 &lt;code&gt;/proc/sys/&lt;/code&gt; 下的一个个文件。比如 &lt;code&gt;vm.swappiness&lt;/code&gt; 对应的就是 &lt;code&gt;/proc/sys/vm/swappiness&lt;/code&gt;，你 &lt;code&gt;cat&lt;/code&gt; 它能看到当前值，往里写数字就能改——&lt;code&gt;sysctl&lt;/code&gt; 命令只是帮你把这件事做得顺手一点。&lt;/p&gt;
&lt;p&gt;日常操作分两个层次，一定要分清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;操作&lt;/th&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;效果&lt;/th&gt;
&lt;th&gt;重启后&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;运行时修改&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sysctl -w vm.swappiness=10&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;立即生效&lt;/td&gt;
&lt;td&gt;失效，恢复配置文件的值&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;持久化修改&lt;/td&gt;
&lt;td&gt;写进 &lt;code&gt;/etc/sysctl.conf&lt;/code&gt; 或 &lt;code&gt;/etc/sysctl.d/*.conf&lt;/code&gt; 后加载&lt;/td&gt;
&lt;td&gt;加载后生效&lt;/td&gt;
&lt;td&gt;保留&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;查看单个参数&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sysctl vm.swappiness&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只读&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;查看全部参数&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sysctl -a&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只读，输出很长&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;持久化配置的推荐姿势是：不要直接改 &lt;code&gt;/etc/sysctl.conf&lt;/code&gt; 主文件，而是到 &lt;code&gt;/etc/sysctl.d/&lt;/code&gt; 目录下新建一个属于你自己的文件，比如 &lt;code&gt;99-tuning.conf&lt;/code&gt;。这样系统自带的配置和你手工加的配置泾渭分明，将来排查时一眼就知道哪些是原装的、哪些是后加的。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 新建自己的参数文件
sudo tee /etc/sysctl.d/99-tuning.conf &amp;gt; /dev/null &amp;lt;&amp;lt;&apos;EOF&apos;
# 2026-11-15 调整：降低换出倾向，原因见运维记录
vm.swappiness = 10
EOF

# 加载全部配置文件使之生效
sudo sysctl --system
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里有两个容易混淆的点，必须讲透：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;sysctl -p&lt;/code&gt; 与 &lt;code&gt;sysctl --system&lt;/code&gt; 的区别。&lt;/strong&gt; &lt;code&gt;sysctl -p&lt;/code&gt; 默认只加载 &lt;code&gt;/etc/sysctl.conf&lt;/code&gt; 这一个文件（也可以 &lt;code&gt;-p 文件名&lt;/code&gt; 指定单个文件）；&lt;code&gt;sysctl --system&lt;/code&gt; 则会按顺序加载所有配置来源，包括 &lt;code&gt;/etc/sysctl.d/&lt;/code&gt;、&lt;code&gt;/run/sysctl.d/&lt;/code&gt;、&lt;code&gt;/usr/lib/sysctl.d/&lt;/code&gt; 等目录下的全部 &lt;code&gt;.conf&lt;/code&gt; 文件。你把参数写进了 &lt;code&gt;/etc/sysctl.d/99-tuning.conf&lt;/code&gt;，却只执行 &lt;code&gt;sysctl -p&lt;/code&gt;，参数当然不会生效——这是新手最常见的「我明明改了」的来源之一。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;加载顺序与覆盖关系。&lt;/strong&gt; 多个文件里出现同一个参数时，&lt;strong&gt;后加载的覆盖先加载的&lt;/strong&gt;。&lt;code&gt;--system&lt;/code&gt; 的加载顺序大致是：先 &lt;code&gt;/usr/lib/sysctl.d/&lt;/code&gt;（发行版预置），再 &lt;code&gt;/run/sysctl.d/&lt;/code&gt;（运行时生成），最后 &lt;code&gt;/etc/sysctl.d/&lt;/code&gt;（管理员配置）；同一目录内按文件名字典序排列，&lt;code&gt;99-&lt;/code&gt; 开头的文件排在 &lt;code&gt;10-&lt;/code&gt; 开头之后，所以管理员习惯用 &lt;code&gt;99-&lt;/code&gt; 前缀来确保自己的配置最后生效、优先级最高。理解这条规则，第九节里「参数不生效」的排障就有了主线。&lt;/p&gt;
&lt;p&gt;还有一个细节：某些参数是按网络命名空间隔离的（&lt;code&gt;net.*&lt;/code&gt; 下的不少参数），在容器里改的不影响宿主机，反之亦然。本篇讨论的都是宿主机层面的全局调整。&lt;/p&gt;
&lt;h2&gt;三、常用参数逐个讲&lt;/h2&gt;
&lt;p&gt;下面这几个是被提及频率最高的 sysctl 参数。讲法统一：先说它管什么，再说&lt;strong&gt;什么场景才需要动&lt;/strong&gt;，最后说判断方法。这里刻意不给「万能推荐值」——脱离场景的值没有意义，这正是第一节纪律的落地。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;管什么&lt;/th&gt;
&lt;th&gt;典型默认值（因内核版本而异）&lt;/th&gt;
&lt;th&gt;什么时候才需要动&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;vm.swappiness&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;内存回收时倾向于换出匿名页还是丢弃页缓存&lt;/td&gt;
&lt;td&gt;60&lt;/td&gt;
&lt;td&gt;内存够用但进程仍被换出、或数据库类服务想减少 Swap 抖动时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;fs.file-max&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;全系统可同时打开的文件句柄总数上限&lt;/td&gt;
&lt;td&gt;通常已很大（与内存相关）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;cat /proc/sys/fs/file-nr&lt;/code&gt; 显示已用量逼近上限时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;net.core.somaxconn&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;监听套接字已完成连接队列的长度上限&lt;/td&gt;
&lt;td&gt;4096（新内核）&lt;/td&gt;
&lt;td&gt;高并发服务出现连接被丢弃、队列溢出计数增长时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;net.ipv4.tcp_max_syn_backlog&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;半连接（SYN）队列长度&lt;/td&gt;
&lt;td&gt;与内存相关&lt;/td&gt;
&lt;td&gt;遭遇大量 SYN 或突发连接、半连接队列溢出时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;net.core.rmem_max&lt;/code&gt; / &lt;code&gt;wmem_max&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;套接字接收/发送缓冲区可调上限&lt;/td&gt;
&lt;td&gt;常见为 212992 起步&lt;/td&gt;
&lt;td&gt;大带宽高延迟链路传大流量、确认窗口成为瓶颈时&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;vm.swappiness&lt;/h3&gt;
&lt;p&gt;它控制内存紧张时内核回收内存的倾向：值越高，越倾向于把不常访问的进程内存页换出到 Swap；值越低，越倾向于丢弃文件页缓存、保住进程内存。取值范围 0–100（新内核可到 200）。要纠正一个流传很广的误解：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;swappiness 不是「内存用到百分之多少才开始用 Swap」的开关&amp;lt;/span&amp;gt;，它只是一个倾向权重。把 swappiness 设为 0 也不等于禁用 Swap，只是内核会尽量避免换出。详细的 Swap 讨论放在第六节。&lt;/p&gt;
&lt;h3&gt;fs.file-max&lt;/h3&gt;
&lt;p&gt;全系统层面的句柄总上限。现代发行版的默认值通常已经非常大（按内存自动计算），绝大多数机器一辈子不需要动它。判断方法不是猜，而是看实际用量：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# file-nr 三个数字依次是：已分配句柄数、未用已分配数、系统上限
cat /proc/sys/fs/file-nr
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第一个数字持续逼近第三个数字，才说明这层需要抬高。反之，如果只是单个进程报句柄不够，那是第五节的用户级/服务级限制问题，改 &lt;code&gt;file-max&lt;/code&gt; 没用。&lt;/p&gt;
&lt;h3&gt;net.core.somaxconn 与 tcp_max_syn_backlog&lt;/h3&gt;
&lt;p&gt;这两个管的是连接建立阶段的两个队列。客户端发 SYN 进来，半连接先在 &lt;code&gt;tcp_max_syn_backlog&lt;/code&gt; 队列里排队；三次握手完成后，连接移到 &lt;code&gt;somaxconn&lt;/code&gt; 决定的监听队列，等应用 &lt;code&gt;accept()&lt;/code&gt; 取走。队列满了，新连接就被丢弃或超时，客户端表现就是「偶尔连不上、重试又好了」。&lt;/p&gt;
&lt;p&gt;判断要不要动的证据在 &lt;code&gt;netstat -s&lt;/code&gt; 里：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 看监听队列溢出与 SYN 队列丢弃的累计计数，隔一段时间看两次，涨了才是问题
netstat -s | grep -i -E &quot;overflow|drop|SYN&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意应用自身的监听 backlog 参数（比如 Nginx 的 &lt;code&gt;listen ... backlog=&lt;/code&gt;、程序里 &lt;code&gt;listen(fd, N)&lt;/code&gt; 的 N）与 &lt;code&gt;somaxconn&lt;/code&gt; 是取小关系：应用写了 128，内核给 4096 也没用，实际队列就是 128。两边要一起对齐，只改内核侧是经典的白忙活。&lt;/p&gt;
&lt;h3&gt;net.core.rmem_max / wmem_max&lt;/h3&gt;
&lt;p&gt;这组参数决定套接字缓冲区的可调天花板，配合 &lt;code&gt;net.ipv4.tcp_rmem&lt;/code&gt; / &lt;code&gt;tcp_wmem&lt;/code&gt; 的自动调优范围一起看。它只在一种场景下成为瓶颈：&lt;strong&gt;大带宽 × 高延迟&lt;/strong&gt;的链路上跑大流量传输（比如跨洲传大文件），TCP 窗口被缓冲区上限卡住、带宽吃不满。普通 VPS 上的 Web 服务流量形态完全不是这样，盲目把缓冲区上限拉到几十上百 MB，只会给高并发时的内存占用埋雷。判断方法：先算带宽时延积（带宽 × RTT），再看现有上限是否低于这个值，低了才有调整的理由。&lt;/p&gt;
&lt;h2&gt;四、ip_forward：一条要单独拎出来的红线&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;net.ipv4.ip_forward&lt;/code&gt; 值得单独成节，因为它是少数几个「开了就改变机器安全角色」的参数。&lt;/p&gt;
&lt;p&gt;它的作用是允许内核把从一个网口收到的数据包转发到另一个网口——也就是让这台机器充当路由器。普通服务器只需要处理「发给自己」和「自己发出」的包，不需要转发任何东西，所以它&lt;strong&gt;默认应该是 0（关闭）&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;什么场景才需要开？只有当这台机器真的要做转发者时：做网关、做 NAT 出口、跑需要转发流量的代理或隧道服务、宿主机上跑虚拟机/容器并由宿主机做路由（Docker 等容器运行时在特定网络模式下会自行开启它，那是受控场景）。除此之外，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;在普通服务器上手贱打开 ip_forward，等于把机器变成一台来者不拒的中转站&amp;lt;/span&amp;gt;，一旦防火墙规则再没配好，就可能被外人拿去转发流量、绕过访问控制，背锅的是你的 IP。&lt;/p&gt;
&lt;p&gt;检查与处置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 查看当前状态（IPv4 与 IPv6 各一份）
sysctl net.ipv4.ip_forward net.ipv6.conf.all.forwarding

# 如果确认本机不需要转发，关掉并持久化
sudo sysctl -w net.ipv4.ip_forward=0
echo &apos;net.ipv4.ip_forward = 0&apos; | sudo tee /etc/sysctl.d/98-no-forward.conf
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果你在检查时发现它莫名是 1，先别急着关——回忆一下这台机器上是否跑了容器、虚拟机或隧道服务，它们可能正依赖转发。先确认依赖关系再动手，这本身也是第一节「先有证据」的纪律。&lt;/p&gt;
&lt;h2&gt;五、文件句柄三层限制：Too many open files 的真正主战场&lt;/h2&gt;
&lt;p&gt;「Too many open files」是 Linux 服务最常见的报错之一，而它的根源几乎从来不在一个地方。句柄限制是一个三层体系，任何一层卡住都会报这个错，排障的关键是逐层确认到底卡在哪层。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;层级&lt;/th&gt;
&lt;th&gt;配置位置&lt;/th&gt;
&lt;th&gt;查看方式&lt;/th&gt;
&lt;th&gt;作用范围&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;系统级&lt;/td&gt;
&lt;td&gt;&lt;code&gt;fs.file-max&lt;/code&gt;（sysctl）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sysctl fs.file-max&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;全机所有进程的句柄总和&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;用户级&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/etc/security/limits.conf&lt;/code&gt;、&lt;code&gt;/etc/security/limits.d/*.conf&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;登录会话里 &lt;code&gt;ulimit -n&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;某个用户的所有会话进程&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;服务级&lt;/td&gt;
&lt;td&gt;systemd 单元的 &lt;code&gt;LimitNOFILE=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;systemctl show 服务名 -p LimitNOFILE&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;单个 systemd 服务&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;系统级：fs.file-max&lt;/h3&gt;
&lt;p&gt;如第三节所说，这层默认值通常极大，一般不是瓶颈。用 &lt;code&gt;/proc/sys/fs/file-nr&lt;/code&gt; 确认已用量即可，不要无证据乱抬。&lt;/p&gt;
&lt;h3&gt;用户级：limits.conf 与 pam_limits&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;ulimit -n&lt;/code&gt; 看到的当前 Shell 的软上限，其来源是 &lt;code&gt;/etc/security/limits.conf&lt;/code&gt; 及 &lt;code&gt;limits.d&lt;/code&gt; 下的文件，由 PAM 的 &lt;code&gt;pam_limits&lt;/code&gt; 模块在登录时注入。典型配置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# /etc/security/limits.d/99-nofile.conf
# 格式：对象 类型 项目 值；* 表示所有用户，soft 是软上限，hard 是硬上限
* soft nofile 65535
* hard nofile 65535
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三个必须知道的坑：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;改完必须重新登录才生效&lt;/strong&gt;，对已经在跑的进程毫无影响；&lt;/li&gt;
&lt;li&gt;这套机制只对&lt;strong&gt;经 PAM 登录的会话&lt;/strong&gt;生效，systemd 拉起来的服务根本不读 limits.conf——这是无数人「改了 limits 句柄还是不够」的真正原因，服务要看下一层；&lt;/li&gt;
&lt;li&gt;软上限可以由用户自己在会话内用 &lt;code&gt;ulimit -n&lt;/code&gt; 往上调，但不能超过硬上限。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;服务级：systemd 的 LimitNOFILE&lt;/h3&gt;
&lt;p&gt;通过 systemd 管理的服务，句柄上限由单元文件里的 &lt;code&gt;LimitNOFILE=&lt;/code&gt; 决定，与 limits.conf 无关。查看与修改：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 查看某服务当前生效的句柄上限
systemctl show nginx -p LimitNOFILE

# 推荐用 drop-in 覆盖，不要直接改发行版自带的单元文件
sudo systemctl edit nginx
# 在打开的编辑区写入：
# [Service]
# LimitNOFILE=65535

sudo systemctl restart nginx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改完用进程的真实数据验证，不要只看配置文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 直接读进程的 limits，这才是它实际拿到的上限
cat /proc/$(pgrep -o nginx)/limits | grep &quot;open files&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;逐层定位法&lt;/h3&gt;
&lt;p&gt;遇到「Too many open files」时按这个顺序走：先看报错进程 &lt;code&gt;/proc/&amp;lt;PID&amp;gt;/limits&lt;/code&gt; 里 Max open files 是多少（这是它实际的上限），再看它当前已经打开了多少（&lt;code&gt;ls /proc/&amp;lt;PID&amp;gt;/fd | wc -l&lt;/code&gt;）——如果用量远没到上限却报错，检查系统级 &lt;code&gt;file-nr&lt;/code&gt;；如果用量就是顶着上限，先怀疑句柄泄漏（程序打开文件/连接不关闭），把上限调大只是续命，根源得回代码里查。先分清「上限太低」和「泄漏撑爆」，再决定动哪层。&lt;/p&gt;
&lt;h2&gt;六、Swap：要不要、怎么建、swappiness 到底是什么意思&lt;/h2&gt;
&lt;h3&gt;要不要 Swap&lt;/h3&gt;
&lt;p&gt;结论先行：&lt;strong&gt;建议保留一块不大的 Swap&lt;/strong&gt;。理由不是「内存不够时拿它顶」，而是它给系统提供了一个缓冲层：内存出现瞬时尖峰时，内核可以把最冷的页换出去，避免直接触发 OOM Killer 把进程杀掉。对内存不大的 VPS 来说，一块等于内存大小或固定 1–2 GB 的 Swap，是成本极低的保险。反过来，日常如果发现 Swap 被持续大量使用、机器明显变卡，那说明物理内存真的不够了，该做的是加内存或减负载，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把 Swap 当内存用只会让机器慢到不可用&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h3&gt;用文件创建 Swap 全流程&lt;/h3&gt;
&lt;p&gt;分区形式的 Swap 在云服务器上不方便调整，文件形式是主流做法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 创建一个 2G 的空文件（fallocate 是预分配，快）
sudo fallocate -l 2G /swapfile

# 2. 权限必须收紧：只有 root 可读写，否则有安全问题
sudo chmod 600 /swapfile

# 3. 格式化为交换区
sudo mkswap /swapfile

# 4. 立即启用
sudo swapon /swapfile

# 5. 写入 fstab 实现开机自动挂载
echo &apos;/swapfile none swap sw 0 0&apos; | sudo tee -a /etc/fstab

# 6. 验证：应该能看到 /swapfile 这一行和总容量
swapon --show
free -h
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;fallocate&lt;/code&gt; 在某些文件系统（如 Btrfs 的特定情形）上生成的 swap 文件可能无法启用，报错时改用 &lt;code&gt;dd if=/dev/zero of=/swapfile bs=1M count=2048&lt;/code&gt; 实打实写零生成。另外改动 &lt;code&gt;/etc/fstab&lt;/code&gt; 前先备份，写错一行可能导致开机挂载失败进不去系统，改完务必先用 &lt;code&gt;sudo mount -a&lt;/code&gt; 验证语法再重启。
:::&lt;/p&gt;
&lt;p&gt;调整大小也很简单：&lt;code&gt;swapoff /swapfile&lt;/code&gt; 停用 → 重新生成目标大小的文件 → &lt;code&gt;mkswap&lt;/code&gt; → &lt;code&gt;swapon&lt;/code&gt; → fstab 里路径没变就不用改。全程不用重启。&lt;/p&gt;
&lt;h3&gt;swappiness 的含义纠偏&lt;/h3&gt;
&lt;p&gt;回到第三节埋的伏笔。&lt;code&gt;vm.swappiness&lt;/code&gt; 的真实含义是：在内存回收时，内核在「换出进程匿名页」和「丢弃文件页缓存」之间的倾向权重。它是一个相对比例，不是百分比触发线——不存在「swappiness=60 就是内存用到 60% 开始换出」这回事，内存充裕时内核基本不回收，谈不上倾向。&lt;/p&gt;
&lt;p&gt;实践中的取向判断：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;桌面或通用服务器：保持默认 60 完全没问题，不用动；&lt;/li&gt;
&lt;li&gt;跑数据库、缓存类服务，希望进程内存尽量不被换出（换出一次就可能造成延迟毛刺）：可以降到 10 甚至更低，减少无谓换出；&lt;/li&gt;
&lt;li&gt;内存非常紧张的小机器：适当调高让冷页早点让位，也是一种活法，但这是内存不足的缓解手段，不是优化。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;改法照旧遵守纪律：先 &lt;code&gt;sysctl vm.swappiness&lt;/code&gt; 记原值，再 &lt;code&gt;-w&lt;/code&gt; 临时改观察，确认有效再写进 &lt;code&gt;/etc/sysctl.d/&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;七、BBR：拥塞控制算法，一段讲清&lt;/h2&gt;
&lt;p&gt;TCP 拥塞控制决定「网速该以多快的节奏发包」。Linux 默认多年的 Cubic 在高延迟、有少量丢包的链路上表现保守；BBR 是 Google 提出的另一套算法，按测得的带宽和 RTT 来建模发包，在跨国、跨运营商这类链路上通常能把吞吐跑得更满、延迟更稳。服务器在国内、用户也在国内同城时，两者差距往往感知不到；VPS 在海外、用户跨境访问时，BBR 的收益才明显——是否值得开，取决于你的流量形态，而不是跟风。&lt;/p&gt;
&lt;p&gt;查看与开启：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 查看当前可用的拥塞控制算法与正在使用的
sysctl net.ipv4.tcp_available_congestion_control
sysctl net.ipv4.tcp_congestion_control

# 若可用列表里有 bbr，写入配置并持久化
sudo tee /etc/sysctl.d/99-bbr.conf &amp;gt; /dev/null &amp;lt;&amp;lt;&apos;EOF&apos;
net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr
EOF
sudo sysctl --system

# 验证
sysctl net.ipv4.tcp_congestion_control
lsmod | grep bbr
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意两个前提：一是内核版本要带 BBR 模块（主流发行版近年的内核都已包含，可用列表里没有就是不支持，不要硬上）；二是 BBR 官方搭档是 &lt;code&gt;fq&lt;/code&gt; 队列调度，两个参数要成对出现。如果你的内核较老、模块不存在，这段就到此为止——为一个拥塞算法去换内核，风险收益完全不成比例。想把 BBR 一次看透——v1 的模型与四状态机、v2 与 v3 逐代改了什么、以及 BBRv3 为何至今没有进入主线内核——见深度长文 &lt;a href=&quot;/posts/linux-bbr-deep-dive/&quot;&gt;BBR 深度长文：从 v1 的带宽建模到 BBRv3 的十年演进&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;八、改完之后：验证与回滚&lt;/h2&gt;
&lt;p&gt;参数改完不等于调优完成，没有验证的修改只是「改了」。验证的方法论只有一句话：&lt;strong&gt;用和改之前完全相同的口径，对比同一组指标&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;具体动作：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;改前留基线&lt;/strong&gt;：调整前先把关键指标记一遍——比如改连接队列前，记下 &lt;code&gt;netstat -s&lt;/code&gt; 里队列溢出的计数；改 swappiness 前，记下 &lt;code&gt;free -h&lt;/code&gt; 的 Swap 使用量与 &lt;code&gt;vmstat 1&lt;/code&gt; 观察到的 si/so（换入换出速率）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;设观察期&lt;/strong&gt;：改完至少观察一个业务高峰周期。很多参数问题不在低峰期暴露，只看改完五分钟没报错就宣布胜利，是给自己埋雷。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;对比而非感觉&lt;/strong&gt;：「好像快了」不算数，计数涨没涨、延迟分位变没变、错误率动没动，数字说话。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;回滚就是写回备份值&lt;/strong&gt;：观察发现指标恶化或无变化，直接把第一节备份的原值写回去并重新加载，然后把这次调整从配置文件里撤掉。无变化的参数也要撤——留着只会增加后来者的理解成本。&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;# 回滚示例：把 swappiness 写回原值并同步持久化文件
sudo sysctl -w vm.swappiness=60
sudo sed -i &apos;s/^vm.swappiness.*/vm.swappiness = 60/&apos; /etc/sysctl.d/99-tuning.conf
sudo sysctl --system
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;建议养成一个小习惯：每次改参数，在配置文件里以注释写清日期、原值、改动原因。这份注释就是未来的你排障时的第一手资料，价值不亚于任何监控。&lt;/p&gt;
&lt;h2&gt;九、排障：参数不生效与改出问题&lt;/h2&gt;
&lt;h3&gt;参数不生效的三种常见原因&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;其一，被后加载的文件覆盖。&lt;/strong&gt; 你在 &lt;code&gt;/etc/sysctl.d/60-xxx.conf&lt;/code&gt; 里写了值，另一个 &lt;code&gt;99-&lt;/code&gt; 开头的文件里有同名参数，加载顺序在你后面，你的就被盖掉了。排查：&lt;code&gt;grep -r &quot;参数名&quot; /etc/sysctl.d/ /etc/sysctl.conf /usr/lib/sysctl.d/&lt;/code&gt; 把所有出处列出来，对照加载顺序看谁最后生效。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;其二，加载命令用错。&lt;/strong&gt; 只执行了 &lt;code&gt;sysctl -p&lt;/code&gt;（只读主文件），而你的参数写在 &lt;code&gt;sysctl.d&lt;/code&gt; 里，自然不生效。用 &lt;code&gt;sysctl --system&lt;/code&gt; 全量加载，或 &lt;code&gt;sysctl -p /etc/sysctl.d/99-tuning.conf&lt;/code&gt; 指定文件。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;其三，服务级限制盖过系统级。&lt;/strong&gt; 系统层面 &lt;code&gt;file-max&lt;/code&gt; 和 ulimit 都调好了，服务还是报句柄不够——因为 systemd 单元里的 &lt;code&gt;LimitNOFILE&lt;/code&gt; 独立生效，回第五节用 &lt;code&gt;/proc/&amp;lt;PID&amp;gt;/limits&lt;/code&gt; 看进程实际值，一锤定音。&lt;/p&gt;
&lt;h3&gt;改出问题：重点是改之前留后路&lt;/h3&gt;
&lt;p&gt;网络类参数是翻车重灾区：队列、缓冲区、连接跟踪类参数改得离谱，轻则连接异常，重则直接断联——而你往往正是通过网络连着这台机器的。防断联的纪律有三条：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;改网络参数前，先确认自己有第二条路&lt;/strong&gt;：云厂商的 VNC/控制台登录、带外管理、或者至少一个已经开着的备用 SSH 会话别关；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;善用临时生效试错&lt;/strong&gt;：先用 &lt;code&gt;sysctl -w&lt;/code&gt; 只改运行时值，不写持久化文件。这样即使改出问题，重启即可回到原样，持久化是验证通过后的最后一步；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要在业务高峰期调整网络与内存核心参数&amp;lt;/span&amp;gt;&lt;/strong&gt;，低峰期动手，观察期覆盖下一个高峰，这是用时间换安全的标准打法。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;如果是改完参数服务起不来，先看日志里服务实际读到的限制值（&lt;code&gt;/proc/&amp;lt;PID&amp;gt;/limits&lt;/code&gt;、服务自身的启动日志），再对照本节三种原因逐项排除，不要一上来就把所有参数全量回滚——全量回滚会抹掉证据，下次还会踩同一个坑。逐项排除、单项回滚，依然是第一节那套纪律。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;把这一篇的要点收成几条可执行的心法：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;调优的前提是瓶颈证据，没有证据的参数调整一律视为给排障添乱；一次只改一项，改前必备份原值，网上参数包不整包照抄；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;sysctl -w&lt;/code&gt; 只管运行时，持久化写 &lt;code&gt;/etc/sysctl.d/99-*.conf&lt;/code&gt;；&lt;code&gt;sysctl -p&lt;/code&gt; 只加载单个文件，&lt;code&gt;--system&lt;/code&gt; 才是全量加载，后加载覆盖先加载；&lt;/li&gt;
&lt;li&gt;常用参数各有明确的适用场景：swappiness 是倾向权重不是触发百分比，somaxconn 要和应用 backlog 对齐，TCP 缓冲区只对大带宽高延迟链路有意义；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;ip_forward&lt;/code&gt; 在非转发用途的机器上必须保持关闭；&lt;/li&gt;
&lt;li&gt;「Too many open files」按系统级、用户级、服务级三层逐层定位，以 &lt;code&gt;/proc/&amp;lt;PID&amp;gt;/limits&lt;/code&gt; 的实际值为准；&lt;/li&gt;
&lt;li&gt;Swap 建议小量保留作保险，用文件创建最灵活；BBR 只在跨境等高延迟链路上有明显意义，且要与 &lt;code&gt;fq&lt;/code&gt; 成对配置；&lt;/li&gt;
&lt;li&gt;改完必须同口径对比指标、留足观察期，无效或恶化就按备份回滚。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;参数是最后一公里的手段，不是第一反应。先排障、再定位、有证据、才动手——这条顺序守住了，内核调优就从玄学变回了工程。&lt;/p&gt;
</content:encoded></item><item><title>Linux 日志管理：journald 与日志轮转</title><link>https://www.anexns.cloudns.org/posts/linux-log-management/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-log-management/</guid><description>日志既要留得住、又不能把磁盘吃光：journald 的查询全套与容量限制、/var/log 里的关键日志地图、logrotate 轮转配置，以及磁盘被日志撑爆时的应急处理顺序。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;服务器出问题时，第一个要看的就是日志：服务为什么起不来、SSH 为什么登录失败、半夜那次重启到底发生了什么，答案全在日志里。但日志还有另一副面孔——它只进不出、越攒越多，某天凌晨把根分区撑满，然后数据库写不进去、服务接连崩掉，你爬起来一看，元凶是一个几个 GB 的日志文件。所以日志管理的核心就两件事：查的时候要能快速查到，存的时候要给它封顶。&lt;/p&gt;
&lt;p&gt;这篇以 Debian 为主线，先给你一张关键日志地图，再讲 journald 的查询工具 journalctl 全套用法和容量限额配置，然后拆解 logrotate 的轮转机制，最后是磁盘被日志撑爆时的应急处理顺序和三个实战排查套路。上一篇 &lt;a href=&quot;/posts/linux-systemd-services/&quot;&gt;《systemd 服务管理》&lt;/a&gt; 讲过怎么用 systemctl 管服务，这一篇正好接着讲怎么看这些服务的日志。&lt;/p&gt;
&lt;h2&gt;先认识日志的两副面孔&lt;/h2&gt;
&lt;p&gt;日志的价值不用多说，重点说说它的风险。Linux 上的日志默认只增不减：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;systemd 的日志数据库 journal 会随着服务输出持续增长，不设上限时默认最多能吃掉磁盘的 10%（上限 4 GB）——100 GB 的盘还好，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;20 GB 的小盘 VPS，光 journal 就能占掉 2 GB，再加上几个不轮转的应用日志，根分区爆掉只是时间问题&amp;lt;/span&amp;gt;；&lt;/li&gt;
&lt;li&gt;传统文本日志放在 &lt;code&gt;/var/log&lt;/code&gt; 下，靠 logrotate 定期切割，但如果某个应用的日志没被任何轮转规则覆盖，它就能无限长大；&lt;/li&gt;
&lt;li&gt;日志爆盘的后果不是「看不了日志」这么简单：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;磁盘 100% 时数据库无法写入、程序无法创建临时文件，往往是全站服务一起挂掉&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;所以本篇的主线就是三步：&lt;strong&gt;会查&lt;/strong&gt;（journalctl 查询全套）、&lt;strong&gt;会限&lt;/strong&gt;（journald 限额 + logrotate 轮转）、&lt;strong&gt;会救&lt;/strong&gt;（爆盘应急）。&lt;/p&gt;
&lt;h2&gt;关键日志地图：日志都在哪、看什么&lt;/h2&gt;
&lt;p&gt;Debian 上日志分两大体系：systemd 的 journal（二进制数据库，用 journalctl 查）和 &lt;code&gt;/var/log&lt;/code&gt; 下的传统文本日志（直接用文本工具看）。先记住这张地图，排障时不至于满世界找文件：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;日志&lt;/th&gt;
&lt;th&gt;位置 / 查法&lt;/th&gt;
&lt;th&gt;主要看什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;系统与服务日志（journal）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;journalctl&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;所有 systemd 服务的输出、启动过程、系统事件，总入口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;认证日志&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/var/log/auth.log&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;SSH 登录成功与失败、sudo 提权、用户切换&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;系统综合日志&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/var/log/syslog&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;各守护进程的杂项消息，journal 的文本版补充&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;内核日志&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/var/log/kern.log&lt;/code&gt; 或 &lt;code&gt;journalctl -k&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;内核消息、驱动、硬件错误、OOM 击杀记录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;软件包日志&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/var/log/dpkg.log&lt;/code&gt;、&lt;code&gt;/var/log/apt/history.log&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;装了什么、卸了什么、什么时候升级的&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;应用日志&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/var/log/nginx/&lt;/code&gt;、&lt;code&gt;/var/log/mysql/&lt;/code&gt; 等&lt;/td&gt;
&lt;td&gt;应用自己写的日志，位置随应用而定&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Docker 容器日志&lt;/td&gt;
&lt;td&gt;&lt;code&gt;docker logs&lt;/code&gt;，实体在 &lt;code&gt;/var/lib/docker/containers/&amp;lt;容器ID&amp;gt;/&lt;/code&gt; 下的 &lt;code&gt;-json.log&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;容器标准输出，管理方法完全不同&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;最后两行提醒一句：应用日志的位置没有统一标准，装完一个服务先确认它的日志在哪、有没有被轮转覆盖；Docker 容器日志不归 journald 和 logrotate 管（默认的 json-file 驱动有自己的轮转参数），具体看 &lt;a href=&quot;/posts/docker-logging/&quot;&gt;《Docker 日志管理》&lt;/a&gt; 那篇，这篇只讲系统侧。&lt;/p&gt;
&lt;h2&gt;journalctl 查询全套&lt;/h2&gt;
&lt;p&gt;journalctl 是 journal 的查询工具，参数很多，但日常排障其实就靠下面这几组组合。先说一个前提：普通用户只能看自己相关的日志，&lt;strong&gt;查全量日志要用 root 或把用户加进 &lt;code&gt;systemd-journal&lt;/code&gt; 组&lt;/strong&gt;，否则你会看到日志莫名其妙不全。&lt;/p&gt;
&lt;h3&gt;按服务查：-u&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 看某个服务的全部日志
journalctl -u nginx

# 只看这个服务、且实时跟踪新日志（排障最常用组合）
journalctl -u nginx -f

# 同时看两个服务（比如反代 + 后端联调）
journalctl -u nginx -u myapp -f
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;服务起不来时，&lt;code&gt;systemctl status&lt;/code&gt; 只给最后几行，真正的原因往往在 &lt;code&gt;journalctl -u 服务名&lt;/code&gt; 里翻。这也是上一篇 systemd 里说的排障第一站。&lt;/p&gt;
&lt;h3&gt;按时间查：--since / --until&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 最近 1 小时的日志
journalctl --since &quot;1 hour ago&quot;

# 今天的日志
journalctl --since today

# 指定时间段：某次故障窗口内的全部日志
journalctl --since &quot;2026-11-15 08:00&quot; --until &quot;2026-11-15 09:30&quot;

# 和 -u 组合：看 nginx 今天凌晨那段时间
journalctl -u nginx --since &quot;2026-11-15 00:00&quot; --until &quot;2026-11-15 01:00&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;时间支持 &lt;code&gt;today&lt;/code&gt;、&lt;code&gt;yesterday&lt;/code&gt;、&lt;code&gt;&quot;2 days ago&quot;&lt;/code&gt; 这类相对写法，也支持 &lt;code&gt;YYYY-MM-DD HH:MM:SS&lt;/code&gt; 绝对时间。排障的标准动作就是：先确定故障发生的大致时间，再用 &lt;code&gt;--since/--until&lt;/code&gt; 把窗口切出来。&lt;/p&gt;
&lt;h3&gt;按级别查：-p&lt;/h3&gt;
&lt;p&gt;日志级别从高到低是 0–7：&lt;code&gt;emerg&lt;/code&gt;（系统不可用）、&lt;code&gt;alert&lt;/code&gt;、&lt;code&gt;crit&lt;/code&gt;、&lt;code&gt;err&lt;/code&gt;、&lt;code&gt;warning&lt;/code&gt;、&lt;code&gt;notice&lt;/code&gt;、&lt;code&gt;info&lt;/code&gt;、&lt;code&gt;debug&lt;/code&gt;。&lt;code&gt;-p&lt;/code&gt; 查的是「这个级别及更严重的」：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 只看错误及以上（日常巡检最有用的一条）
journalctl -p err

# 看 warning 到 err 这个区间
journalctl -p warning..err

# 某服务今天的全部错误
journalctl -u myapp -p err --since today
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;按启动次查：-b&lt;/h3&gt;
&lt;p&gt;每次开机在 journal 里是一个 boot，排查「重启之后发生了什么」和「上次关机前为什么挂了」全靠它：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 本次启动以来的日志
journalctl -b

# 上一次启动的日志（系统崩溃后重启，先看这里的结尾）
journalctl -b -1

# 上一次启动的最后 100 行
journalctl -b -1 -n 100

# 列出所有还留着的启动记录
journalctl --list-boots
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意：&lt;code&gt;-b -1&lt;/code&gt; 能查到前提是日志跨重启保存了，也就是下面要说的持久化存储开着；没开的话每次重启日志清零，&lt;code&gt;--list-boots&lt;/code&gt; 就只有当前这一次。&lt;/p&gt;
&lt;h3&gt;实时跟踪与常用辅助参数&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 实时跟踪（相当于 tail -f 整个系统日志）
journalctl -f

# 只看最后 50 行，不进入分页器（写脚本时必加 --no-pager）
journalctl -n 50 --no-pager

# 只看内核消息（等价于 dmesg 的历史版）
journalctl -k

# 按关键词过滤（不区分大小写需自己注意，--grep 支持正则）
journalctl --since today --grep &quot;Failed&quot;

# 看 journal 当前占了多少磁盘
journalctl --disk-usage
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;输出格式与导出：-o&lt;/h3&gt;
&lt;p&gt;默认输出是给人看的短格式（时间 + 主机名 + 进程名 + 消息）。需要看完整字段（比如日志的优先级数值、来源单元、启动 ID）时换详细格式；需要把日志交给脚本或其他工具处理时，用 JSON 格式：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 详细格式：每条日志的全部字段，适合深挖来源
journalctl -u myapp -o verbose -n 5

# JSON 格式：一行一条，适合喂给 jq 等工具二次加工
journalctl -u myapp -o json --no-pager | jq -r .MESSAGE

# 导出某个时间段的日志留档（发给别人协查、或归档备份）
journalctl --since &quot;2026-11-15 08:00&quot; --until &quot;2026-11-15 09:00&quot; --no-pager &amp;gt; /tmp/incident.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;另外提醒：&lt;code&gt;-x&lt;/code&gt; 参数会在日志后面附上系统自带的解释文本（对常见错误有说明），新手期可以加上看，熟练之后嫌啰嗦可以去掉。&lt;/p&gt;
&lt;h3&gt;常用组合速查&lt;/h3&gt;
&lt;p&gt;把上面几组参数拼起来，就是日常排障最顺手的几条命令，建议记熟：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;服务起不来，看它最近的完整日志&lt;/td&gt;
&lt;td&gt;&lt;code&gt;journalctl -u 服务名 -n 100 --no-pager&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;边操作边看日志滚动&lt;/td&gt;
&lt;td&gt;&lt;code&gt;journalctl -u 服务名 -f&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;查某个故障时间窗的全部日志&lt;/td&gt;
&lt;td&gt;&lt;code&gt;journalctl --since &quot;时间&quot; --until &quot;时间&quot;&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每日巡检只看错误&lt;/td&gt;
&lt;td&gt;&lt;code&gt;journalctl -p err --since today&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;系统崩溃重启后看上次的结尾&lt;/td&gt;
&lt;td&gt;&lt;code&gt;journalctl -b -1 -n 100&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;怀疑内存不足杀了进程&lt;/td&gt;
&lt;td&gt;`journalctl -k&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;给 journald 封顶：容量与保留时间&lt;/h2&gt;
&lt;p&gt;journald 的行为由 &lt;code&gt;/etc/systemd/journald.conf&lt;/code&gt; 控制（也可以在 &lt;code&gt;/etc/systemd/journald.conf.d/&lt;/code&gt; 下放片段文件覆盖）。先看现状，再改配置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 当前占用
journalctl --disk-usage

# 手动立刻压缩到 200 MB 以内（应急用，下面还会提到）
journalctl --vacuum-size=200M

# 按时间清理：只保留最近 7 天
journalctl --vacuum-time=7d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--vacuum-*&lt;/code&gt; 是手动一次性清理，治本要改配置文件。打开 &lt;code&gt;/etc/systemd/journald.conf&lt;/code&gt;，&lt;code&gt;[Journal]&lt;/code&gt; 段里重点改这几项：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Journal]
Storage=persistent
SystemMaxUse=500M
SystemKeepFree=1G
MaxRetentionSec=14day
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐项讲：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;配置项&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;建议&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Storage&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;存储模式：&lt;code&gt;persistent&lt;/code&gt; 存 &lt;code&gt;/var/log/journal&lt;/code&gt;（跨重启保留）、&lt;code&gt;volatile&lt;/code&gt; 只存内存（重启清零）、&lt;code&gt;auto&lt;/code&gt; 是有目录就持久化&lt;/td&gt;
&lt;td&gt;服务器一律 &lt;code&gt;persistent&lt;/code&gt;，否则重启后查不到案发记录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SystemMaxUse&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;journal 在磁盘上最多占多少&lt;/td&gt;
&lt;td&gt;小盘机器设 200M–500M，大盘可 1G–2G&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SystemKeepFree&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;至少给磁盘留多少空闲，日志和空闲冲突时优先保空闲&lt;/td&gt;
&lt;td&gt;至少留 1G，别让日志把盘挤到 0&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;MaxRetentionSec&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;日志最长保留多久，超期删除（和容量上限谁先触发谁生效）&lt;/td&gt;
&lt;td&gt;一般 14day–30day，按排障习惯定&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SystemMaxFileSize&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;单个 journal 文件的最大体积（单个文件默认上限约为 SystemMaxUse 的 1/8，一般不用单独改）&lt;/td&gt;
&lt;td&gt;保持默认即可&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;RuntimeMaxUse&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;内存中（&lt;code&gt;/run/log/journal&lt;/code&gt;）的上限，volatile 部分用&lt;/td&gt;
&lt;td&gt;保持默认即可&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;改完重启 journald 生效，再验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl restart systemd-journald
journalctl --disk-usage
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;配置文件的写法还有个省事技巧：与其直接改主文件 &lt;code&gt;/etc/systemd/journald.conf&lt;/code&gt;（升级时可能被包管理器提示覆盖），不如在 &lt;code&gt;/etc/systemd/journald.conf.d/&lt;/code&gt; 下新建一个片段文件（比如 &lt;code&gt;limits.conf&lt;/code&gt;），只写要改的那几行，效果相同且主次分明。想确认最终合并后的生效配置，不用靠猜：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 查看 journald.conf 主文件 + 所有片段合并后的结果
systemd-analyze cat-config systemd/journald.conf
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;Storage=persistent&lt;/code&gt; 还依赖 &lt;code&gt;/var/log/journal&lt;/code&gt; 目录存在。如果改完发现重启后日志还是没了，多半是这个目录缺失，补上再重启服务：&lt;code&gt;sudo mkdir -p /var/log/journal &amp;amp;&amp;amp; sudo systemctl restart systemd-journald&lt;/code&gt;。另外别把 &lt;code&gt;SystemMaxUse&lt;/code&gt; 设得比整个 journal 目录所在分区的合理份额还大——限额只是 journal 的自我约束，应用日志、Docker 日志都不归它管，磁盘总账还得靠后面的巡检。
:::&lt;/p&gt;
&lt;p&gt;为什么说小盘机器必改：Debian 默认 &lt;code&gt;Storage=auto&lt;/code&gt;、容量按磁盘 10% 自动算。一台 20 GB 盘的 VPS，journal 上限就是约 2 GB，还不算其他日志。手动把 &lt;code&gt;SystemMaxUse&lt;/code&gt; 压到 500M、保留期压到 14 天，省出的空间够系统喘气，出问题时两周内的记录也足够定位了。&lt;/p&gt;
&lt;h2&gt;传统文本日志与 rsyslog 的关系&lt;/h2&gt;
&lt;p&gt;简单交代一句背景：Debian 除了 journal，还装着 rsyslog——journald 把日志转发一份给 rsyslog，由它按规则写成 &lt;code&gt;/var/log/syslog&lt;/code&gt;、&lt;code&gt;auth.log&lt;/code&gt;、&lt;code&gt;kern.log&lt;/code&gt; 这些文本文件。分流规则在 &lt;code&gt;/etc/rsyslog.conf&lt;/code&gt; 和 &lt;code&gt;/etc/rsyslog.d/&lt;/code&gt; 里，核心就是按「来源 + 级别」决定写哪个文件：认证相关的进 auth.log、内核的进 kern.log、其余大部分进 syslog，所以你会发现 syslog 里和 journalctl 看到的内容高度重叠——它们本来就是同一批日志。&lt;/p&gt;
&lt;p&gt;两套是同一批日志的两种存法：journal 胜在查询能力（按服务、时间、级别、启动次过滤），文本日志胜在直观（grep、tail 直接上，老工具链和很多监控脚本也都认文本文件）。日常排障优先 journalctl，文本日志作为补充和备份口径即可，不用纠结关掉哪套——但要注意，&lt;strong&gt;双份存储意味着双份占盘&lt;/strong&gt;，这也是上面要给 journald 限额的原因之一。rsyslog 自己写出的这批文本文件归谁管？归 logrotate，就是下一节的主角。&lt;/p&gt;
&lt;h2&gt;logrotate：文本日志的轮转&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;/var/log&lt;/code&gt; 下的文本日志靠 logrotate 管理：定期把旧日志改名归档（轮转）、压缩、只保留最近几份、超期的删掉。它的结构分两层：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;/etc/logrotate.conf&lt;/code&gt;：全局配置（默认周期、保留份数、压缩开关），Debian 默认大致是每周轮转、保留 4 份、压缩开启；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;/etc/logrotate.d/&lt;/code&gt;：每个应用一份自己的规则文件（rsyslog、nginx、apt 等都在这里），rsyslog 那份管的就是 syslog、auth.log、kern.log 这一批。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;拿一份真实风格的应用日志配置逐行拆解——假设有个自研应用把日志写到 &lt;code&gt;/var/log/myapp/app.log&lt;/code&gt;，给它建 &lt;code&gt;/etc/logrotate.d/myapp&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/var/log/myapp/*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
    dateext
    su root root
}
&lt;/code&gt;&lt;/pre&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;配置行&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/var/log/myapp/*.log&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;这份规则管哪些文件（支持通配符，可以多文件共用一份规则）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;daily&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;轮转周期：daily / weekly / monthly，也可以 &lt;code&gt;size 100M&lt;/code&gt; 按大小触发（两者写一起时 size 优先判断）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;rotate 14&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;保留 14 份归档，更老的直接删除；配合 daily 就是留两周&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;compress&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;归档后用 gzip 压缩，日志是纯文本，压缩比通常很好&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;delaycompress&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;最近一份归档先不压缩，推迟到下次轮转——方便你直接 tail 昨天的日志不用解压&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;missingok&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;日志文件不存在时不报错（应用还没跑过时很常见）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;notifempty&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;文件是空的就不轮转，避免生成一堆空归档&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;copytruncate&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;复制一份归档后，把原文件内容清空（见下面与 create 的区别）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;dateext&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;归档文件名带日期后缀（如 &lt;code&gt;app.log-20261115.gz&lt;/code&gt;）而不是序号，找某天的日志更直观&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;su root root&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;以指定用户身份做轮转，目录权限不是 root 时需要，避免权限报错&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;copytruncate 与 create 的区别（最容易踩的坑）&lt;/h3&gt;
&lt;p&gt;轮转的本质动作是「把当前日志挪走，让应用往一个新文件里写」，实现有两种流派：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;create 模式（默认）&lt;/th&gt;
&lt;th&gt;copytruncate 模式&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;动作&lt;/td&gt;
&lt;td&gt;把旧文件改名归档，再新建一个空文件&lt;/td&gt;
&lt;td&gt;把内容复制一份作归档，再把原文件截断清零&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;对应用的要求&lt;/td&gt;
&lt;td&gt;应用必须能「重新打开日志文件」，通常靠 postrotate 脚本发信号通知，如给 nginx 发 &lt;code&gt;USR1&lt;/code&gt;、或 &lt;code&gt;systemctl reload&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;应用什么都不用管，文件还是那个文件（inode 不变）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;坑&lt;/td&gt;
&lt;td&gt;应用没重开文件的话，会继续往已被改名的旧文件里写，新文件一直是空的，日志「消失」在归档里&lt;/td&gt;
&lt;td&gt;复制和截断之间写入的那几行会丢；大文件复制本身也耗 IO&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合&lt;/td&gt;
&lt;td&gt;有标准重开机制的服务（nginx、rsyslog 等，官方规则都写好了）&lt;/td&gt;
&lt;td&gt;改不了、叫不动的自研程序、老程序&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;create 模式的标准写法长这样（以给应用发重开信号为例）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/var/log/myapp/*.log {
    weekly
    rotate 8
    compress
    missingok
    notifempty
    create 0640 myapp myapp
    sharedscripts
    postrotate
        systemctl reload myapp &amp;gt;/dev/null 2&amp;gt;&amp;amp;1 || true
    endscript
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;create 0640 myapp myapp&lt;/code&gt; 是新建空文件时顺带设好权限和属主，不然新文件是 root 的、应用可能写不进去；&lt;code&gt;sharedscripts&lt;/code&gt; 表示通配符匹配到多个文件时 postrotate 只执行一次（不加的话每个文件轮转都触发一次 reload）；&lt;code&gt;postrotate ... endscript&lt;/code&gt; 之间就是通知应用重开日志的命令。&lt;/p&gt;
&lt;h3&gt;谁在跑 logrotate、怎么验证规则&lt;/h3&gt;
&lt;p&gt;Debian 上 logrotate 由 systemd 的 &lt;code&gt;logrotate.timer&lt;/code&gt; 每天触发一次（老系统是 &lt;code&gt;/etc/cron.daily/logrotate&lt;/code&gt;，本质都是每天跑一遍 &lt;code&gt;logrotate /etc/logrotate.conf&lt;/code&gt;）。它每次运行时会先读全局配置，再把 &lt;code&gt;/etc/logrotate.d/&lt;/code&gt; 下的规则逐份套用，最后把「每个文件上次轮转的时间」写回状态文件 &lt;code&gt;/var/lib/logrotate/status&lt;/code&gt;——周期判断（daily/weekly 到没到点）全靠这个状态文件，所以规则文件改了内容，当天不一定立刻生效，要等下一次触发且周期已到。&lt;/p&gt;
&lt;p&gt;再强调一次全局与单应用规则的关系：&lt;code&gt;/etc/logrotate.conf&lt;/code&gt; 里的设置是默认值，&lt;code&gt;/etc/logrotate.d/&lt;/code&gt; 里某份规则写了同名选项就以那份为准。比如全局是 weekly + rotate 4，某个应用规则里写 daily + rotate 14，那个应用就按自己的来，其余没写的项（如 compress）继续继承全局——写自定义规则时只需要写和默认不同的部分，不必每份都抄全套。&lt;/p&gt;
&lt;p&gt;新写或改完一份规则，&lt;strong&gt;不要等明天验证&lt;/strong&gt;，用 debug 模式立刻试运行——它只打印将要执行的动作，不真动文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 试运行某一份规则（-d 是 debug，只看不动手）
sudo logrotate -d /etc/logrotate.d/myapp

# 手动强制轮转一次（真执行，验证归档效果）
sudo logrotate -f /etc/logrotate.d/myapp

# 看 logrotate 的状态记录（每个文件上次轮转时间）
cat /var/lib/logrotate/status
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;让应用日志省心：写文件，还是交给 journal&lt;/h2&gt;
&lt;p&gt;自研应用或脚本上线时，日志往哪打，决定了后面几年的运维省不省心。三种常见做法对比一下：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;做法&lt;/th&gt;
&lt;th&gt;怎么管&lt;/th&gt;
&lt;th&gt;适合&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;应用输出到标准输出/标准错误，进程由 systemd 托管&lt;/td&gt;
&lt;td&gt;自动进 journal，查询用 &lt;code&gt;journalctl -u&lt;/code&gt;，限额跟着 journald 走，一行轮转配置都不用写&lt;/td&gt;
&lt;td&gt;自己写的服务、脚本，&lt;strong&gt;首选&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;应用自己写日志文件&lt;/td&gt;
&lt;td&gt;必须给它配一份 logrotate 规则（上一节的写法），还要操心权限和文件句柄&lt;/td&gt;
&lt;td&gt;有特殊格式要求、或框架自带日志文件的应用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;应用通过 syslog 协议发给 rsyslog&lt;/td&gt;
&lt;td&gt;在 &lt;code&gt;/etc/rsyslog.d/&lt;/code&gt; 里加一条按程序名分流的规则，轮转跟 rsyslog 那批走&lt;/td&gt;
&lt;td&gt;老牌守护进程的传统做法&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;结论很简单：能托管给 systemd 的就别自己写文件。很多人的应用日志爆盘，根源就是应用自己写文件、又没人给它配轮转——而交给 journal 的话，容量有 journald 封顶，查询有 journalctl 全套工具，等于免费获得一整套日志管理。写脚本同理：定时任务的输出别到处重定向到野文件，用 systemd 服务或 timer 托管，日志自然进 journal。&lt;/p&gt;
&lt;h2&gt;应急：磁盘被日志撑满了怎么办&lt;/h2&gt;
&lt;p&gt;半夜告警说磁盘 100%，十有八九是日志（也可能是别的大文件，处理思路相通）。顺序别乱，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;先定位、再释放、最后补上限&amp;lt;/span&amp;gt;，千万别上来就无差别删 &lt;code&gt;/var/log&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一步：定位是谁吃满了。&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 哪个分区满了
df -h

# /var/log 下面谁最大
sudo du -h -d 1 /var/log | sort -h

# 全盘找大文件（只看根分区、500 MB 以上）
sudo find / -xdev -type f -size +500M -exec ls -lh {} \;

# journal 占了多少
journalctl --disk-usage
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第二步：判断能不能动、怎么动。&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;已经轮转归档的老日志（&lt;code&gt;.gz&lt;/code&gt;、带日期或序号后缀的）可以直接删，这是最安全的释放来源；&lt;/li&gt;
&lt;li&gt;journal 太大就用它自己的清理命令，别去手删 &lt;code&gt;/var/log/journal&lt;/code&gt; 里的文件：&lt;code&gt;sudo journalctl --vacuum-size=200M&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;正在被进程写着的当前日志文件，不要用 &lt;code&gt;rm&lt;/code&gt; 删&lt;/strong&gt;：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;进程还握着这个文件的句柄，rm 只是删掉目录项，磁盘空间要等进程关闭文件（通常是重启服务）才真正释放，你会陷入「文件删了、空间没回来、日志还找不着」的三输局面&amp;lt;/span&amp;gt;。正确做法是清空内容、保留文件本身：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;# 清空一个正在写的日志（文件还在、句柄不受影响、空间立刻释放）
sudo truncate -s 0 /var/log/myapp/app.log
# 等价写法
sudo sh -c &apos;&amp;gt; /var/log/myapp/app.log&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;如果已经手快 rm 了正在写的日志、空间没回来：那是文件被进程占着还没释放（「已删除但仍被占用」），用 &lt;code&gt;sudo lsof +L1&lt;/code&gt; 能找到这类文件，重启对应服务即可释放。这类空间账目问题在磁盘管理篇里也有提及，见 &lt;a href=&quot;/posts/linux-disk-management/&quot;&gt;《Linux 磁盘管理》&lt;/a&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;第三步：补上限，防复发。&lt;/strong&gt; 应急只是把盘腾出来，不补配置下个月还爆：给 journald 加限额（前面一节）、给肇事应用补 logrotate 规则、应用本身日志级别太啰嗦的调回 info。处理完 &lt;code&gt;df -h&lt;/code&gt; 再确认一次水位，并顺手查一眼是不是日志里在刷屏报错——日志暴涨往往是某个错误在死循环打日志，根子在故障不在日志。&lt;/p&gt;
&lt;p&gt;举个完整的例子串一下整个流程：一台小盘 VPS 凌晨报磁盘 100%，&lt;code&gt;df -h&lt;/code&gt; 确认是根分区；&lt;code&gt;du&lt;/code&gt; 一路查下去，发现 &lt;code&gt;/var/log/journal&lt;/code&gt; 占了 1.8 GB（这台机器从没给 journald 设过限额），还有一个自研应用的 &lt;code&gt;app.log&lt;/code&gt; 涨到 3 GB 且没有任何轮转规则。处理顺序是：先 &lt;code&gt;journalctl --vacuum-size=200M&lt;/code&gt; 把 journal 压回去，腾出第一批空间让服务恢复写入；再 &lt;code&gt;truncate -s 0&lt;/code&gt; 清空 app.log（应用还在跑，不能 rm）；服务全部恢复后，补上 journald 的 &lt;code&gt;SystemMaxUse=500M&lt;/code&gt; 并重启 journald，再给 app.log 写一份 logrotate 规则并用 &lt;code&gt;-d&lt;/code&gt; 验证。整个过程没有重启任何服务——这正是「先定位、再释放、最后补上限」这个顺序的意义：每一步都在恢复可用性，而不是制造新的停机。&lt;/p&gt;
&lt;h2&gt;从日志里挖信息：三个常用套路&lt;/h2&gt;
&lt;p&gt;日志留下来就是为了查，这三个是服务器上最高频的挖法。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;套路一：谁在爆破我的 SSH。&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 今天失败登录有多少次
sudo journalctl -u ssh --since today | grep -c &quot;Failed password&quot;

# 失败来源 IP 排行（auth.log 版同样适用）
sudo grep &quot;Failed password&quot; /var/log/auth.log | grep -oE &quot;from [0-9.]+&quot; | sort | uniq -c | sort -nr | head

# 反过来确认：有没有登录成功的陌生记录
sudo grep &quot;Accepted&quot; /var/log/auth.log | tail
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;失败成百上千次但没有 Accepted，是互联网常态，交给 Fail2ban 处理即可；&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;真正要警惕的是爆破之后紧跟着一条 Accepted——那说明口令可能已经被撞中了，要立刻改密码、查 authorized_keys&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;套路二：进程是被 OOM 杀掉的吗。&lt;/strong&gt; 服务莫名消失、日志里没有退出记录，先查内核有没有杀过它：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo journalctl -k --since yesterday | grep -i &quot;out of memory&quot;
# 或
sudo dmesg -T | grep -i &quot;killed process&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;看到 &lt;code&gt;Out of memory: Killed process 1234 (java)&lt;/code&gt; 这类行就破案了：不是程序崩溃，是内存不够被内核挑中处决，接下来该查内存为什么不够，而不是重启了事。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;套路三：磁盘或文件系统在报错。&lt;/strong&gt; 系统卡顿、文件读写异常时查内核日志里的存储错误：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo journalctl -k -p err --since today
sudo journalctl -k | grep -iE &quot;I/O error|EXT4-fs error&quot; | tail
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;出现 &lt;code&gt;I/O error&lt;/code&gt;、&lt;code&gt;EXT4-fs error&lt;/code&gt; 就不是软件层面能修的了，多半是云盘或硬件出问题，先备份数据再联系服务商，别反复重启碰运气。&lt;/p&gt;
&lt;h2&gt;排障小节&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. journalctl 查不到重启之前的日志。&lt;/strong&gt; 十有八九是持久化没开：&lt;code&gt;Storage&lt;/code&gt; 还是 auto/volatile，或者 &lt;code&gt;/var/log/journal&lt;/code&gt; 目录不存在，日志只存在内存里，重启即失。处理：按前面一节设 &lt;code&gt;Storage=persistent&lt;/code&gt;、确认目录存在、重启 systemd-journald。还有一种情况是权限：普通用户不在 &lt;code&gt;systemd-journal&lt;/code&gt; 或 &lt;code&gt;adm&lt;/code&gt; 组时只能看到部分日志，用 &lt;code&gt;sudo journalctl&lt;/code&gt; 对比一下就知道是不是权限问题。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. logrotate 配了却不执行。&lt;/strong&gt; 按这个顺序查：先 &lt;code&gt;systemctl status logrotate.timer&lt;/code&gt; 确认定时器在跑（再看 &lt;code&gt;systemctl list-timers | grep logrotate&lt;/code&gt; 的下次触发时间）；再 &lt;code&gt;sudo logrotate -d /etc/logrotate.conf&lt;/code&gt; 看 debug 输出，配置语法错误、目录权限不对（缺 &lt;code&gt;su&lt;/code&gt;）都会在这里现形；最后看 &lt;code&gt;/var/lib/logrotate/status&lt;/code&gt; 里该文件的上次轮转时间——状态文件损坏或时间没到周期，也会表现为「不轮转」。另外注意周期判断依据是状态文件里记录的时间，不是文件的修改时间，你手动 touch 文件是骗不过它的，想立刻验证就用 &lt;code&gt;-f&lt;/code&gt; 强制。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 日志时间对不上。&lt;/strong&gt; journalctl 显示的是服务器本地时区，应用日志可能写的是 UTC，相差 8 小时这种「对不上」多半是时区口径不同而不是日志错了。先 &lt;code&gt;timedatectl&lt;/code&gt; 确认系统时区与 NTP 同步状态；journalctl 想按 UTC 看加 &lt;code&gt;--utc&lt;/code&gt;；跨机器对日志时，先统一口径（都换算成 UTC 或都看本地时间）再比时间线，别拿着差 8 小时的两份日志拼案发经过。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. journalctl 输出被分页器截断、脚本里拿不到全量。&lt;/strong&gt; 交互终端里它默认进 less 分页，脚本和管道里记得加 &lt;code&gt;--no-pager&lt;/code&gt;，或者设环境变量 &lt;code&gt;SYSTEMD_PAGER=cat&lt;/code&gt;，这是自动化脚本里最常见的假故障。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. 某个日志文件突然不更新了。&lt;/strong&gt; 先分清是真没日志还是换了地方：应用升级后改成输出到标准输出的，日志会进 journal，文件自然停更，用 &lt;code&gt;journalctl -u 服务名&lt;/code&gt; 一看便知；如果是 rsyslog 写的系统日志集体停更，查 &lt;code&gt;systemctl status rsyslog&lt;/code&gt; 和 journald 本身是否正常——rsyslog 挂掉时文本日志会停，但 journal 还在，可以先从 journal 顶着查。另外磁盘曾经满过的话，某些应用会因为一次写入失败就不再写了，重启该应用即可恢复。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;日志是排障的眼睛，但只进不出必然爆盘，管理目标就一句：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;查得到、存得住、封得住顶&amp;lt;/span&amp;gt;；&lt;/li&gt;
&lt;li&gt;地图先记牢：journal 是总入口，&lt;code&gt;auth.log&lt;/code&gt; 管登录，&lt;code&gt;kern.log&lt;/code&gt; 管内核，应用日志各自为政，Docker 日志另走一套；&lt;/li&gt;
&lt;li&gt;journalctl 五组核心用法：&lt;code&gt;-u&lt;/code&gt; 按服务、&lt;code&gt;--since/--until&lt;/code&gt; 按时间、&lt;code&gt;-p&lt;/code&gt; 按级别、&lt;code&gt;-b&lt;/code&gt; 按启动次、&lt;code&gt;-f&lt;/code&gt; 实时跟踪，再配 &lt;code&gt;--disk-usage&lt;/code&gt; 随时看占用；&lt;/li&gt;
&lt;li&gt;journald 必改三项：&lt;code&gt;Storage=persistent&lt;/code&gt; 保住跨重启记录、&lt;code&gt;SystemMaxUse&lt;/code&gt; 封顶容量、&lt;code&gt;MaxRetentionSec&lt;/code&gt; 封顶时间，改完重启 systemd-journald 并验证；&lt;/li&gt;
&lt;li&gt;logrotate 的关键在选对模式：应用能重开日志文件就用 create + postrotate 通知，叫不动的应用才用 copytruncate，并接受它丢几行的代价；新规则先 &lt;code&gt;-d&lt;/code&gt; 试运行再上线；&lt;/li&gt;
&lt;li&gt;爆盘应急三步走：定位大文件 → 归档可删、当前文件用 truncate 清空（不 rm 正在写的文件）→ 补上限防复发；&lt;/li&gt;
&lt;li&gt;三个挖日志套路（SSH 爆破、OOM 击杀、磁盘错误）建议存成顺手命令，半夜排障时不用现想。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>Linux 网络命令与排障</title><link>https://www.anexns.cloudns.org/posts/linux-network-troubleshooting/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-network-troubleshooting/</guid><description>网络不通时别瞎猜，按层查：ip 与路由、ping 与 mtr、ss 查监听、curl 分段计时、dig 查解析，一套组合拳从链路一路定位到应用。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;服务器网络一出问题，最常见的场面是：有人说&quot;网站打不开&quot;，然后所有人开始瞎猜——有人重启服务，有人改配置，有人怀疑被攻击，折腾半天，最后发现是 DNS 解析到了一个错的 IP。网络排障最大的忌讳就是跳步：问题明明出在第二层，你却在第七层反复折腾应用，怎么折腾都不会好。&lt;/p&gt;
&lt;p&gt;这篇给你一套固定的排查顺序：从链路到应用共七层，每层都有对应的命令和明确的判定标准。以后再遇到&quot;网络不通&quot;，不要先想原因，先想&quot;我现在查到第几层了&quot;。按层往上走，问题必然在某一层现形。&lt;/p&gt;
&lt;p&gt;先把核心思路说透：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;网络排障就是二分定位：先确认本机配置对不对，再确认路通不通，最后确认对方的服务在不在。&amp;lt;/span&amp;gt;下面所有命令，都是为这三句话服务的。&lt;/p&gt;
&lt;h2&gt;分层排查法：七层顺序与命令总表&lt;/h2&gt;
&lt;p&gt;这套分层不是 OSI 七层模型的照搬，而是按实际排障顺序排的实战版：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;层&lt;/th&gt;
&lt;th&gt;查什么&lt;/th&gt;
&lt;th&gt;主力命令&lt;/th&gt;
&lt;th&gt;通过标准&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1 链路&lt;/td&gt;
&lt;td&gt;网卡有没有起来、IP 配没配上&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ip link&lt;/code&gt;、&lt;code&gt;ip addr&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;网卡状态 UP，有正确的 IP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2 本机路由&lt;/td&gt;
&lt;td&gt;出门走哪条路、网关是谁&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ip route&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;有默认路由，网关正确&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3 网关&lt;/td&gt;
&lt;td&gt;能不能到达网关&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ping &amp;lt;网关IP&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;网关有回应&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4 外网&lt;/td&gt;
&lt;td&gt;能不能到达公网 IP&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ping 223.5.5.5&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;公网 IP 有回应&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5 DNS&lt;/td&gt;
&lt;td&gt;域名能不能解析对&lt;/td&gt;
&lt;td&gt;&lt;code&gt;dig&lt;/code&gt;、&lt;code&gt;getent hosts&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;解析结果正确&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;6 端口&lt;/td&gt;
&lt;td&gt;对方端口通不通&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ss&lt;/code&gt;、&lt;code&gt;curl -v&lt;/code&gt;、&lt;code&gt;nc&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;端口能建立连接&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7 应用&lt;/td&gt;
&lt;td&gt;服务本身答得对不对&lt;/td&gt;
&lt;td&gt;&lt;code&gt;curl -w&lt;/code&gt;、服务日志&lt;/td&gt;
&lt;td&gt;返回内容与状态码正常&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;排查纪律只有一条：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;下一层不通时，不要去查上一层。&amp;lt;/span&amp;gt;比如域名解析都不对，你去看 Nginx 日志纯属浪费时间；反过来，如果前六层全通、只有应用返回 500，那这根本不是网络问题，去查服务本身。&lt;/p&gt;
&lt;p&gt;下面逐层展开。&lt;/p&gt;
&lt;h2&gt;第一层、第二层：看本机 IP 与路由&lt;/h2&gt;
&lt;h3&gt;ip addr：网卡与 IP&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;ip addr
ip -br addr        # 简洁版，一块网卡一行
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重点看三件事：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;网卡状态是不是 &lt;code&gt;UP&lt;/code&gt;。如果是 &lt;code&gt;DOWN&lt;/code&gt;，先 &lt;code&gt;ip link set eth0 up&lt;/code&gt; 拉起来（网卡名以实际为准，常见 eth0、ens3、enp1s0）。&lt;/li&gt;
&lt;li&gt;有没有配上预期的 IP。云服务器常见坑是系统重装后网卡名变了、配置文件对不上，导致 IP 根本没配上。&lt;/li&gt;
&lt;li&gt;有没有意料之外的 IP。一台机器多个 IP 时，源地址选错也会出怪问题。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;只关心 IPv4 时可以过滤着看：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ip -4 -br addr
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;ip route：出门走哪条路&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;ip route
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;典型输出：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;default via 192.168.1.1 dev eth0 proto dhcp metric 100
192.168.1.0/24 dev eth0 proto kernel scope link src 192.168.1.10 metric 100
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐项读法：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;default via 192.168.1.1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;默认网关是 192.168.1.1，所有不在本地网段的流量都先交给它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;dev eth0&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;从 eth0 这块网卡出去&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;192.168.1.0/24 ... src 192.168.1.10&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;本地网段直达，本机源 IP 是 192.168.1.10&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;metric 100&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;优先级，数值越小越优先&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;没有 &lt;code&gt;default&lt;/code&gt; 这一行，本机就出不了网段，这是&quot;新机器上不了网&quot;的头号原因。想确认访问某个具体目标到底走哪条路，用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ip route get 8.8.8.8
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它会直接告诉你：走哪个网关、从哪块网卡出、源 IP 是谁。排&quot;多网卡谁在干活&quot;的问题时，这条命令一锤定音。&lt;/p&gt;
&lt;p&gt;:::warning
不要用已经废弃的 ifconfig 和 route 命令查新系统。它们来自 net-tools 包，很多发行版默认已不安装；而且 ifconfig 显示的信息不全（比如辅助 IP 会漏）。统一用 iproute2 的 ip 系列，这也是现在所有文档的口径。netstat 同理，只在老系统救急时提一句，日常查连接一律用 ss。
:::&lt;/p&gt;
&lt;h2&gt;第三层、第四层：ping 的三段定位法&lt;/h2&gt;
&lt;p&gt;ping 不是&quot;测通不通&quot;的玩具，用好了它是一把分段定位的尺子。标准动作是连打三段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ping -c 4 192.168.1.1     # 第一段：网关
ping -c 4 223.5.5.5       # 第二段：公网 IP（阿里 DNS）
ping -c 4 www.baidu.com   # 第三段：域名
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三段结果的组合直接指向故障层：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;网关&lt;/th&gt;
&lt;th&gt;公网 IP&lt;/th&gt;
&lt;th&gt;域名&lt;/th&gt;
&lt;th&gt;结论&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;不通&lt;/td&gt;
&lt;td&gt;不通&lt;/td&gt;
&lt;td&gt;不通&lt;/td&gt;
&lt;td&gt;本机或局域网问题：网卡、IP、网关配置&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;通&lt;/td&gt;
&lt;td&gt;不通&lt;/td&gt;
&lt;td&gt;不通&lt;/td&gt;
&lt;td&gt;网关之外的问题：线路、运营商、上级路由&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;通&lt;/td&gt;
&lt;td&gt;通&lt;/td&gt;
&lt;td&gt;不通&lt;/td&gt;
&lt;td&gt;DNS 问题，去查第五层&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;通&lt;/td&gt;
&lt;td&gt;通&lt;/td&gt;
&lt;td&gt;通&lt;/td&gt;
&lt;td&gt;链路与解析都正常，问题在端口或应用层&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这里有个必须纠正的执念：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;ping 不通，不等于服务挂了。&amp;lt;/span&amp;gt;大量服务器和防火墙默认禁用 ICMP 回应，云厂商的安全组也常默认不放行 ping。你 ping 不通一台活得好好的服务器，是完全正常的事。ping 只能用作&quot;我方出站&quot;的定位工具；判断对方服务在不在，要用后面讲的端口层方法（curl、nc），不要拿 ping 的结果下结论。&lt;/p&gt;
&lt;p&gt;反过来，ping 通了也有信息量：看 time 值。同一网段应该是 1ms 以内，跨城几十毫秒，跨国一两百毫秒。如果延迟突然翻了几倍或者抖动剧烈，说明路径质量出问题了，接下一节的 mtr。&lt;/p&gt;
&lt;h2&gt;路径质量：traceroute 与 mtr 怎么读&lt;/h2&gt;
&lt;p&gt;ping 只能告诉你&quot;到终点通不通&quot;，中间经过的十几跳哪一跳在丢包、哪一跳开始变慢，要靠路径工具。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;traceroute 223.5.5.5
mtr 223.5.5.5           # 交互界面，q 退出
mtr -rwc 100 223.5.5.5  # 报告模式：发 100 个包后出统计表
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;mtr 是 traceroute 与 ping 的结合体：它对路径上每一跳持续发包统计。读 mtr 报告抓三点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;看最后一跳（目标本身）的丢包率&lt;/strong&gt;，这才是端到端的真实丢包。中间某一跳显示丢包、但后面几跳都不丢，那是中间路由器对 ICMP 限速，不是故障，别被它带偏。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;看延迟从哪一跳开始阶梯式抬升&lt;/strong&gt;。延迟是逐跳累积的，要看相邻两跳的增量：在哪一跳突然多了 100ms，瓶颈大概率就在那一段线路上（比如跨境出口）。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;间歇性问题要长跑&lt;/strong&gt;。偶发断流用 &lt;code&gt;mtr -rwc 200&lt;/code&gt; 跑几分钟再下结论，四个包的采样什么也说明不了。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
中间跳出现 &lt;code&gt;???&lt;/code&gt; 或星号同样常见：那一跳的路由器不回应探测包而已。只要后续跳数正常显示，就当它透明，不要在这一跳上浪费时间。
:::&lt;/p&gt;
&lt;h2&gt;第六层之前先查本机：ss 看监听与连接&lt;/h2&gt;
&lt;p&gt;排外网问题排得热火朝天之前，先花十秒钟确认一件事：&lt;strong&gt;服务到底有没有在本机监听&lt;/strong&gt;。别人连不上你的 443，第一嫌疑不是网络，而是 Nginx 根本没起来。&lt;/p&gt;
&lt;h3&gt;ss -tlnp：谁在监听哪个端口&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;ss -tlnp
ss -tlnp | grep :443
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;参数拆解：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-t&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只看 TCP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-l&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只看监听（LISTEN）状态&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-n&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;端口与地址都显示数字，不做反向解析（更快、更真实）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-p&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;显示占用端口的进程（需要 root 才能看全）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;UDP 服务把 &lt;code&gt;-t&lt;/code&gt; 换成 &lt;code&gt;-u&lt;/code&gt;，或者用 &lt;code&gt;ss -tulnp&lt;/code&gt; 一次看全。读输出时重点看监听地址：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;0.0.0.0:443&lt;/code&gt;：监听所有 IPv4 地址，对外可达，正常。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;127.0.0.1:443&lt;/code&gt;：只监听本机回环，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;外网永远连不上，这不是网络故障，是服务配置只绑了本地。&amp;lt;/span&amp;gt;数据库、Redis 配成这样是好事（安全），Web 服务配成这样就是事故。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;[::]:443&lt;/code&gt;：监听 IPv6 的所有地址，通常会同时接住 IPv4（dual-stack），具体取决于系统配置。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;ss 查连接状态&lt;/h3&gt;
&lt;p&gt;看已经建立的连接、以及连接都卡在什么状态：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ss -tn                     # 所有 TCP 连接
ss -tn state established   # 只看已建立的
ss -tn state time-wait     # 看 TIME-WAIT 堆积
ss -s                      # 总览统计
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;状态读法速记：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;状态&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;异常信号&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;LISTEN&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;正在监听&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ESTABLISHED&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;连接正常工作中&lt;/td&gt;
&lt;td&gt;数量异常暴涨要警惕&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;TIME-WAIT&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;主动关闭方在等待收尾&lt;/td&gt;
&lt;td&gt;海量堆积多见于高频短连接的客户端或反代&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;CLOSE-WAIT&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;对方已关、我方还没关&lt;/td&gt;
&lt;td&gt;持续堆积＝应用没正确 close，是程序 bug&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SYN-SENT&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;已发出连接请求、没等到回应&lt;/td&gt;
&lt;td&gt;大量出现＝对端不可达或被防火墙丢弃&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这里要立一条分界线：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;端口没有进程监听，就是服务问题，不是网络问题；端口在正常监听、外面却连不上，才轮到防火墙和线路背锅。&amp;lt;/span&amp;gt;这条线划不清，就会在错误的层里打转。&lt;/p&gt;
&lt;h3&gt;从外面测端口通不通&lt;/h3&gt;
&lt;p&gt;在本机确认监听没问题后，从另一台机器（或本机）测端口可达性：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -v http://example.com:8080/    # 最顺手，顺带看应用层
nc -vz example.com 443              # 纯测端口，通/不通给明确结论
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;telnet 也能测，但信息太少，只在没装 nc 的老机器上救急。&lt;/p&gt;
&lt;h2&gt;第五层：DNS 排查&lt;/h2&gt;
&lt;p&gt;&quot;能 ping 通 IP、打不开域名&quot;——出现这个症状组合，不用再猜了，直接按 DNS 问题处理。&lt;/p&gt;
&lt;h3&gt;先分清：系统解析走的是哪条路&lt;/h3&gt;
&lt;p&gt;应用程序查域名，多数走的是系统解析链：读 &lt;code&gt;/etc/nsswitch.conf&lt;/code&gt;，通常先查 &lt;code&gt;/etc/hosts&lt;/code&gt;，再问 &lt;code&gt;/etc/resolv.conf&lt;/code&gt; 里写的 DNS 服务器。快速验证系统实际解析结果：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;getent hosts example.com
cat /etc/resolv.conf
cat /etc/hosts
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意两个坑：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;/etc/hosts&lt;/code&gt; 里如果留了手工写的错误记录，会优先于 DNS 生效，症状是&quot;就这台机器解析不对，别的机器都正常&quot;。&lt;/li&gt;
&lt;li&gt;现在很多发行版的 &lt;code&gt;/etc/resolv.conf&lt;/code&gt; 其实是 systemd-resolved 的存根文件，里面只有 &lt;code&gt;127.0.0.53&lt;/code&gt; 一个地址——真正的上游 DNS 在 resolved 的配置里。用 &lt;code&gt;resolvectl status&lt;/code&gt; 能看到每块网卡实际用的 DNS 是什么。改 DNS 别直接乱改这个文件，先看清它归谁管。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;dig：把解析过程看个明明白白&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;dig example.com
dig example.com A
dig @8.8.8.8 example.com        # 指定用某个解析器查
dig @223.5.5.5 example.com      # 换一个解析器对比
dig +short example.com          # 只看结果
dig example.com +trace          # 从根开始逐级追踪（偶尔用，慢）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;读 dig 输出抓四处：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;位置&lt;/th&gt;
&lt;th&gt;看什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;status:&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;NOERROR 正常；NXDOMAIN＝域名不存在；SERVFAIL＝解析器或权威侧出错&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ANSWER SECTION&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;实际解析到的记录，对不对、是不是预期的 IP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Query time&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;解析耗时，几百毫秒以上就是解析器有问题&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SERVER:&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;这次到底问的是哪个 DNS 服务器&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;@&lt;/code&gt; 指定解析器对比是 DNS 排障的杀手锏：本机默认解析器查出来是错的、换 8.8.8.8 查是对的，结论就是本地 DNS 被污染或配置错误，与目标网站毫无关系；两个都错，那要去查这个域名自己的权威解析配置了。&lt;/p&gt;
&lt;p&gt;:::warning
dig、host、nslookup 都来自 bind-utils / dnsutils 包，新装的精简系统可能没有。没有 dig 时，先用 getent hosts 顶着判断系统解析结果，再把工具装上。不要拿 ping 域名的方式看解析——ping 显示的 IP 只能看个结果，看不到问的是谁、答得对不对。
:::&lt;/p&gt;
&lt;h2&gt;第七层：curl 深用&lt;/h2&gt;
&lt;p&gt;端口通了，不代表服务好用。&quot;网站能打开但巨慢&quot;&quot;偶尔 502&quot;，这类问题的主力工具是 curl。&lt;/p&gt;
&lt;h3&gt;curl -v：看连接与握手全过程&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;curl -v https://example.com/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它会把过程逐行打出来：解析到哪个 IP、连的哪个地址、TLS 握手用的什么版本与证书、发了什么请求头、对方回了什么状态。在哪一行卡住、哪一行报错，问题就停在哪一层。比如卡在 &lt;code&gt;Trying 1.2.3.4...&lt;/code&gt; 半天不动，是连接建立不了；握手阶段报证书错误，是证书问题，与网络无关。&lt;/p&gt;
&lt;h3&gt;curl -w：分段计时，一刀切开慢在哪&lt;/h3&gt;
&lt;p&gt;这是本篇最值得背下来的一条命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -o /dev/null -s -w &apos;dns:%{time_namelookup} conn:%{time_connect} tls:%{time_appconnect} ttfb:%{time_starttransfer} total:%{time_total}\n&apos; https://example.com/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;各段含义与慢的指向：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;变量&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;这一段慢说明什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;time_namelookup&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;DNS 解析完成时刻&lt;/td&gt;
&lt;td&gt;解析慢：换解析器或查本地 DNS&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;time_connect&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;TCP 三次握手完成时刻&lt;/td&gt;
&lt;td&gt;与上一段的差值大＝线路延迟高或丢包重传&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;time_appconnect&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;TLS 握手完成时刻&lt;/td&gt;
&lt;td&gt;与上一段差值大＝TLS 协商问题或中间设备干扰&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;time_starttransfer&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;收到第一个字节（TTFB）&lt;/td&gt;
&lt;td&gt;与握手完成差值大＝源站处理慢，锅在服务端&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;time_total&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;全部下载完成&lt;/td&gt;
&lt;td&gt;与 TTFB 差值大＝带宽或响应体太大&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一句话用法：TTFB 占了总时间的九成，就是源站慢，别再查网络了；时间大多耗在 connect 段，才是线路的问题。&lt;/p&gt;
&lt;h3&gt;curl --resolve：绕过 DNS 直打指定 IP&lt;/h3&gt;
&lt;p&gt;怀疑 DNS 给的 IP 有问题、或者想验证某台源站本身好不好，用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -v --resolve example.com:443:1.2.3.4 https://example.com/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它让 curl 跳过解析、直接连你指定的 IP，但 Host 头和证书校验仍按域名走。这是区分&quot;解析的锅&quot;和&quot;源站的锅&quot;的标准动作：直打源站正常、走域名不正常，问题百分之百在解析链路上。&lt;/p&gt;
&lt;h2&gt;MTU：小包通、大包不通的怪病&lt;/h2&gt;
&lt;p&gt;有一类症状非常有特征：SSH 能登、ping 能通、小网页能开，但传大文件就卡死、打开大页面就转圈、TLS 握手到一半断掉。这是典型的 MTU（最大传输单元）问题：小包能过，接近上限的大包被路径上某个环节悄悄丢掉。&lt;/p&gt;
&lt;p&gt;原因通常是 PPPoE 拨号、各种隧道（VPN、GRE、WireGuard）额外封装了包头，使有效 MTU 小于标准的 1500，而路径 MTU 发现又被防火墙拦了 ICMP，导致大包有去无回。&lt;/p&gt;
&lt;p&gt;测法是用 ping 手工二分包大小（&lt;code&gt;-M do&lt;/code&gt; 表示禁止分片，包超了就直接失败）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ping -M do -s 1472 -c 3 223.5.5.5    # 1472+28=1500，标准以太网满包
ping -M do -s 1464 -c 3 223.5.5.5    # 不通就逐步减小试
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;满包不通、减小到某个值就通，说明路径 MTU 小于 1500，临界值加 28（IP 头 20＋ICMP 头 8）就是实际 MTU。解法是在本机网卡或隧道接口上把 MTU 调到测出的值，或在路由器上做 MSS 钳制。先测再改，不要凭感觉填数字。&lt;/p&gt;
&lt;h2&gt;完整剧本：用户说&quot;网站打不开&quot;&lt;/h2&gt;
&lt;p&gt;把前面的东西串起来，实地走一遍。场景：用户反馈 https://blog.example.com 打不开，你手里只有这台源站服务器和一台能当外部视角的机器（自己的电脑也行）。&lt;/p&gt;
&lt;p&gt;**第一步，先在本机分清内外。**在源站本机上自测：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -I http://127.0.0.1/
ss -tlnp | grep -E &apos;:80|:443&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;本机 curl 正常、80/443 都在监听——服务本身没问题，故障在本机之外或解析上。若本机都不通，剧本到此结束，转去查服务，别再往下走网络流程。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二步，从外部视角复现并分段计时。&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -o /dev/null -s -w &apos;dns:%{time_namelookup} conn:%{time_connect} tls:%{time_appconnect} ttfb:%{time_starttransfer}\n&apos; https://blog.example.com/
curl -v https://blog.example.com/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;假设结果是：dns 段瞬间完成，conn 段直接超时，&lt;code&gt;-v&lt;/code&gt; 显示它连向的 IP 是 203.0.113.99——而你很清楚源站的真实 IP 是 198.51.100.23。连接没问题，是它连错了地方。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三步，查解析，对比解析器。&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;dig +short blog.example.com
dig @8.8.8.8 +short blog.example.com
dig @223.5.5.5 +short blog.example.com
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三个解析器一致给出 203.0.113.99，说明不是本地污染，是这个域名的权威解析记录本身就写着这个 IP——要么是之前迁移服务器时漏改了记录，要么是有人误操作。再用 &lt;code&gt;dig blog.example.com&lt;/code&gt; 看 ANSWER 段的 TTL，确认改完记录后要等多久才全网生效。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第四步，直打源站验证收尾。&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -v --resolve blog.example.com:443:198.51.100.23 https://blog.example.com/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回正常页面——源站与证书全部健康。结论闭环：去 DNS 控制台把 A 记录改回 198.51.100.23，等 TTL 过期后复测域名访问恢复。全程没有重启过任何服务，没有改过一行配置，故障纯粹出在第五层。&lt;/p&gt;
&lt;p&gt;这个剧本的价值不在具体命令，而在顺序：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;每一步的结论都决定下一步查哪里，而不是同时怀疑十个地方。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;排障清单收束&lt;/h2&gt;
&lt;p&gt;最后把高频场景收成一张速查表，遇到问题先对号入座：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;症状&lt;/th&gt;
&lt;th&gt;先查什么&lt;/th&gt;
&lt;th&gt;大概率结论&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;完全上不了网&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ip addr&lt;/code&gt;、&lt;code&gt;ip route&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;IP 没配上或没有默认路由&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;能通 IP、打不开域名&lt;/td&gt;
&lt;td&gt;&lt;code&gt;dig&lt;/code&gt; 对比解析器&lt;/td&gt;
&lt;td&gt;DNS 配置错误或解析记录写错&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;端口连不上&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ss -tlnp&lt;/code&gt; 看监听 → 再查防火墙&lt;/td&gt;
&lt;td&gt;没监听是服务问题；监听正常查防火墙与安全组（见 &lt;a href=&quot;/posts/linux-firewall-ufw-nftables/&quot;&gt;Linux 防火墙：ufw 与 nftables&lt;/a&gt;）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;连得上但很慢&lt;/td&gt;
&lt;td&gt;&lt;code&gt;curl -w&lt;/code&gt; 分段计时&lt;/td&gt;
&lt;td&gt;看时间耗在哪一段：线路慢还是源站慢&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;间歇性断流、偶发超时&lt;/td&gt;
&lt;td&gt;&lt;code&gt;mtr -rwc 200&lt;/code&gt; 长跑&lt;/td&gt;
&lt;td&gt;看最后一跳丢包与延迟抬升点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;小包通、大文件卡死&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ping -M do -s&lt;/code&gt; 二分测 MTU&lt;/td&gt;
&lt;td&gt;路径 MTU 小于 1500&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;就一台机器解析不对&lt;/td&gt;
&lt;td&gt;查它的 &lt;code&gt;/etc/hosts&lt;/code&gt; 与 resolv.conf&lt;/td&gt;
&lt;td&gt;本地 hosts 残留或 resolved 配置问题&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;连接数异常、端口耗尽&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ss -s&lt;/code&gt;、&lt;code&gt;ss -tn state&lt;/code&gt; 按状态统计&lt;/td&gt;
&lt;td&gt;TIME-WAIT/CLOSE-WAIT 堆积，回应用层查&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;还要提醒一句工具的边界：这篇讲的都是&quot;点&quot;上的定位——某一刻通不通、慢在哪。需要看实时流量长什么样、抓包看报文内容，那是 tcpdump 的活，本系列后面的抓包篇会专门讲。先把分层排查练成肌肉记忆，绝大多数&quot;网络不通&quot;，在这七层之内就能结案。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;排障按七层顺序走：链路 → 本机 IP → 路由网关 → 外网 IP → DNS → 端口 → 应用，下一层不通不查上一层。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;ip addr&lt;/code&gt; 与 &lt;code&gt;ip route&lt;/code&gt; 确认本机配置，&lt;code&gt;ip route get&lt;/code&gt; 一锤定音看流量走哪块网卡。&lt;/li&gt;
&lt;li&gt;ping 用三段定位法缩小范围；记住 ping 不通不等于服务挂了，ICMP 被禁是常态。&lt;/li&gt;
&lt;li&gt;mtr 看最后一跳的丢包才是真的丢包，延迟看逐跳增量找瓶颈段。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;ss -tlnp&lt;/code&gt; 先确认服务在监听：没监听是服务问题，在监听才轮到网络与防火墙。&lt;/li&gt;
&lt;li&gt;DNS 问题用 dig 加 &lt;code&gt;@&lt;/code&gt; 对比解析器定性；curl 用 &lt;code&gt;-v&lt;/code&gt; 看过程、&lt;code&gt;-w&lt;/code&gt; 分段计时、&lt;code&gt;--resolve&lt;/code&gt; 绕解析直打源站，是应用层的三件套。&lt;/li&gt;
&lt;li&gt;小包通大包死，测 MTU；间歇性故障，长跑 mtr。所有结论都让命令说话，不猜。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>Debian 软件包管理：APT 全套</title><link>https://www.anexns.cloudns.org/posts/linux-package-management/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-package-management/</guid><description>装、卸、查、升一次学完：apt 与 dpkg 的分工、软件源的构成、自动安全更新，以及 dpkg 被锁、依赖损坏这两种最常见翻车的修法。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;服务器上的软件从哪来、装在哪、出了问题怎么修，最终都落到包管理这一件事上。很多人在 Debian 上用了几年 &lt;code&gt;apt&lt;/code&gt;，却始终分不清 &lt;code&gt;apt&lt;/code&gt; 和 &lt;code&gt;dpkg&lt;/code&gt; 谁管什么：装本地 &lt;code&gt;.deb&lt;/code&gt; 文件时依赖报错不知道怎么办，&lt;code&gt;apt update&lt;/code&gt; 卡在锁占用就直接去删锁文件，升级之前也从不看一眼到底要升什么。这篇文章把 Debian 的包管理一次讲透：先理清 &lt;code&gt;apt&lt;/code&gt; 与 &lt;code&gt;dpkg&lt;/code&gt; 的分工，再走完日常的装、卸、查、升四件套，然后讲软件源的构成、版本锁定、自动安全更新，最后专门处理两种最常见的翻车——锁被占用和依赖损坏。&lt;/p&gt;
&lt;h2&gt;先分清：dpkg 管本地，apt 管仓库&lt;/h2&gt;
&lt;p&gt;Debian 的包管理是两层结构。底层是 &lt;code&gt;dpkg&lt;/code&gt;，它只认识本地的 &lt;code&gt;.deb&lt;/code&gt; 文件：把包里的文件释放到系统里、执行包自带的安装脚本、把状态记录进 &lt;code&gt;/var/lib/dpkg/status&lt;/code&gt; 数据库。它不知道仓库在哪，也不会帮你找依赖——你给它一个包，它缺什么依赖就直接报错给你看。&lt;/p&gt;
&lt;p&gt;上层是 &lt;code&gt;apt&lt;/code&gt;，它面向的是软件仓库：它维护一份「仓库里有什么包、每个包依赖什么」的索引，需要装某个软件时，先把整棵依赖树算清楚，从仓库把所有需要的包下载下来，再交给 &lt;code&gt;dpkg&lt;/code&gt; 逐个安装。老的 &lt;code&gt;apt-get&lt;/code&gt;、&lt;code&gt;apt-cache&lt;/code&gt; 是同一套体系的早期命令，Debian 8 之后推荐日常交互直接用合并后的 &lt;code&gt;apt&lt;/code&gt;，功能基本一致，只是输出更友好、带进度条。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;dpkg&lt;/th&gt;
&lt;th&gt;apt&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;面向对象&lt;/td&gt;
&lt;td&gt;本地的 &lt;code&gt;.deb&lt;/code&gt; 文件&lt;/td&gt;
&lt;td&gt;软件仓库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;会不会联网下载&lt;/td&gt;
&lt;td&gt;不会&lt;/td&gt;
&lt;td&gt;会&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;会不会自动解决依赖&lt;/td&gt;
&lt;td&gt;不会，缺依赖直接报错&lt;/td&gt;
&lt;td&gt;会，自动拉齐整棵依赖树&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;状态记录&lt;/td&gt;
&lt;td&gt;维护 &lt;code&gt;/var/lib/dpkg/status&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;读取 dpkg 的状态，再叠加仓库索引&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;典型命令&lt;/td&gt;
&lt;td&gt;&lt;code&gt;dpkg -i&lt;/code&gt;、&lt;code&gt;dpkg -l&lt;/code&gt;、&lt;code&gt;dpkg -S&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;apt install&lt;/code&gt;、&lt;code&gt;apt update&lt;/code&gt;、&lt;code&gt;apt-cache search&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合场景&lt;/td&gt;
&lt;td&gt;查已装的包、查文件归属、装单个本地包&lt;/td&gt;
&lt;td&gt;日常装卸、升级、搜包&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;记住一句话就够了：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;凡是涉及仓库和依赖的事找 apt，凡是只看本机现状的事找 dpkg。&amp;lt;/span&amp;gt;后面所有命令的选择都从这条分工里推出来：比如「这个文件是哪个包装的」是本机现状问题，用 &lt;code&gt;dpkg -S&lt;/code&gt;；「这个软件仓库里有没有」是仓库问题，用 &lt;code&gt;apt-cache search&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;还有一个容易混淆的点：&lt;code&gt;apt&lt;/code&gt; 操作之前几乎都要先 &lt;code&gt;apt update&lt;/code&gt;，因为 apt 做决策靠的是本地缓存的仓库索引，索引是上次 &lt;code&gt;update&lt;/code&gt; 时下载的快照。索引过期，apt 看到的世界就是过期的。&lt;/p&gt;
&lt;p&gt;再补一个使用习惯上的区别：交互终端里用 &lt;code&gt;apt&lt;/code&gt; 没问题，但写进脚本、定时任务里时更推荐用 &lt;code&gt;apt-get&lt;/code&gt;。原因是 &lt;code&gt;apt&lt;/code&gt; 的命令行界面定位是给人用的，官方明确提示过它的输出格式和行为可能随版本调整，脚本里解析它的输出容易踩坑；而 &lt;code&gt;apt-get&lt;/code&gt; 的接口多年来保持稳定。日常敲命令用哪个都行，自动化场景记得换成 &lt;code&gt;apt-get&lt;/code&gt; 配 &lt;code&gt;--yes&lt;/code&gt; 这类明确参数。&lt;/p&gt;
&lt;h2&gt;日常四件套：更新、升级、安装、卸载&lt;/h2&gt;
&lt;h3&gt;apt update：只更新索引，不动软件&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;sudo apt update
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这条命令做的唯一一件事，是把每个软件源里的包索引（Packages 列表）下载到本地 &lt;code&gt;/var/lib/apt/lists/&lt;/code&gt;，让 apt 知道「现在仓库里各包的最新版本分别是多少」。它不安装、不升级任何软件。所以 &lt;code&gt;apt update&lt;/code&gt; 之后系统里的软件一个都没变，变的只是 apt 的认知。养成习惯：任何 &lt;code&gt;install&lt;/code&gt;、&lt;code&gt;upgrade&lt;/code&gt; 之前先 &lt;code&gt;update&lt;/code&gt;，否则装到的可能是旧版本，甚至因为索引与仓库实际文件对不上而下载失败。&lt;/p&gt;
&lt;h3&gt;upgrade 与 full-upgrade 的区别&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;sudo apt upgrade        # 保守升级
sudo apt full-upgrade   # 完整升级（等同于老的 dist-upgrade）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两者的区别在于处理依赖变化的方式：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;apt upgrade&lt;/th&gt;
&lt;th&gt;apt full-upgrade&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;升级已装的包&lt;/td&gt;
&lt;td&gt;会&lt;/td&gt;
&lt;td&gt;会&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;为满足新依赖而装新包&lt;/td&gt;
&lt;td&gt;不会，宁可把相关包按住不升&lt;/td&gt;
&lt;td&gt;会&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;为满足新依赖而删已装的包&lt;/td&gt;
&lt;td&gt;不会&lt;/td&gt;
&lt;td&gt;会&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;典型场景&lt;/td&gt;
&lt;td&gt;日常小升级&lt;/td&gt;
&lt;td&gt;内核、桌面组件、依赖结构大变的升级&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;举个具体例子：新版内核包换了包名（Debian 升内核经常如此），&lt;code&gt;upgrade&lt;/code&gt; 会因为「装新包才能升」而把内核按住不动，你在输出里会看到「下列软件包被保留」。这时用 &lt;code&gt;full-upgrade&lt;/code&gt; 才能把新内核装上、旧的依赖关系理顺。日常维护可以先跑 &lt;code&gt;upgrade&lt;/code&gt; 看一眼输出，被保留的包再决定要不要 &lt;code&gt;full-upgrade&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;install：装新包，也能修复性重装&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;sudo apt install nginx
sudo apt install nginx curl vim        # 一次装多个
sudo apt install --reinstall nginx     # 重新安装（文件损坏时修）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;apt install&lt;/code&gt; 背后做的事是：算依赖树 → 下载所有缺失的包 → 交给 dpkg 安装。&lt;code&gt;--reinstall&lt;/code&gt; 值得单独记一下：某个包的二进制或配置文件被误删、改坏时，重装一遍往往比手工修更快。&lt;/p&gt;
&lt;h3&gt;remove 与 purge：删程序和删配置是两回事&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;sudo apt remove nginx     # 删程序，保留配置文件
sudo apt purge nginx      # 删程序，连配置文件一起删
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;remove&lt;/code&gt; 只删包里的程序文件，&lt;code&gt;/etc&lt;/code&gt; 下的配置文件会留下来，这样你日后重装同一个包时配置还在。&lt;code&gt;purge&lt;/code&gt; 则把配置一并清掉，适合「这个软件我再也不用了，痕迹也不要」。注意 &amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;purge 会连同你改过的配置文件一起删除且不可恢复&amp;lt;/span&amp;gt;，对数据库、Web 服务器这类配置里藏着业务参数的软件下手前，先把 &lt;code&gt;/etc&lt;/code&gt; 下对应目录备份出来。&lt;/p&gt;
&lt;h3&gt;autoremove：清孤儿依赖&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;sudo apt autoremove
sudo apt autoremove --purge    # 连孤儿包的配置一起清
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;当初为了装 A 而自动拉进来的依赖 B、C，在 A 被卸载后就成了没人需要的「孤儿包」，但 apt 不会自动删它们——它分不清这是你忘了删，还是你其实想留着用。&lt;code&gt;autoremove&lt;/code&gt; 就是专门列出并清除这批自动安装、如今无人依赖的包。每次卸载软件后顺手跑一遍，系统能保持干净。跑之前看一眼它列出的清单再确认，是个好习惯。&lt;/p&gt;
&lt;h2&gt;查询组：装之前先查清楚&lt;/h2&gt;
&lt;p&gt;装错包、装重包，多半是因为装之前没查。这一组命令分工明确：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apt-cache search keyword          # 按关键词在仓库索引里搜包名与简介
apt-cache show nginx              # 看某个包的版本、依赖、大小、详细说明
apt-cache policy nginx            # 看已装版本、候选版本分别来自哪个源
dpkg -l                           # 列出本机所有已装的包
dpkg -l | grep nginx              # 在已装列表里过滤
dpkg -S /usr/sbin/nginx           # 查这个文件是哪个包装的
apt list --upgradable             # 列出当前可升级的包（需先 apt update）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;apt-cache search&lt;/code&gt; 搜的是本地索引，所以搜之前也要 &lt;code&gt;apt update&lt;/code&gt;，不然新上架的包搜不到。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;apt-cache policy&lt;/code&gt; 是排查版本来源的神器：一个包在多个源里都有时，到底会装哪个版本、那个版本来自哪个源，一目了然。装到奇怪版本时先看它。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;dpkg -S&lt;/code&gt; 后面跟文件路径，回答「这个文件是谁带来的」。系统里冒出不认识的可执行文件、或者某个文件被改坏想知道重装哪个包，都用它。注意它只查已装的包；想查「哪个未安装的包包含这个文件」，用 &lt;code&gt;apt-file&lt;/code&gt;（需单独安装并 &lt;code&gt;apt-file update&lt;/code&gt;）。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;apt list --upgradable&lt;/code&gt; 适合升级前先摸底：到底有多少包要升、都是些什么，心里有数再动手。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;还有一个查「包是从哪次操作装上的」的需求，靠的是日志而不是命令本身：&lt;code&gt;/var/log/apt/history.log&lt;/code&gt; 记录了每一次 apt 操作的时间、命令行和涉及的包与版本变化，升级之后某个服务行为异常、想确认「是不是昨天那次升级动了它」时，翻这个日志比猜要快得多。dpkg 自己的操作记录则在 &lt;code&gt;/var/log/dpkg.log&lt;/code&gt;，两个日志配合，基本能还原任何一次包变更的前因后果。&lt;/p&gt;
&lt;h2&gt;装本地 .deb：用 apt install 带路径&lt;/h2&gt;
&lt;p&gt;从官网或第三方下载的 &lt;code&gt;.deb&lt;/code&gt; 文件，装法有新老两条路：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 推荐：apt 装本地包，依赖自动从仓库补齐
sudo apt install ./package-name.deb

# 老路：dpkg 直接装，缺依赖会报错中断
sudo dpkg -i package-name.deb
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;区别就在依赖处理上。&lt;code&gt;dpkg -i&lt;/code&gt; 装到一半发现缺依赖，会把包留在「已解包未配置」的半成品状态然后报错，你还得再跑 &lt;code&gt;apt --fix-broken install&lt;/code&gt; 给它擦屁股。而 &lt;code&gt;apt install ./xxx.deb&lt;/code&gt;（注意必须带 &lt;code&gt;./&lt;/code&gt; 或绝对路径，让 apt 知道这是本地文件而不是仓库里的包名）会先分析这个包的依赖，把缺的从仓库一并下载装好，一次到位。&lt;/p&gt;
&lt;p&gt;还有一种常见情况是版本对不上：本地包要求的某个库版本比仓库里的还新，或者反过来，它依赖一个仓库里已经下架的旧库。这时 apt 会明确报出无法满足的依赖项，不要想着去网上随便找个同名库包装上——版本和发行版代号必须严格对应，跨版本混装库文件是把系统搞成「半个新版半个旧版」的常见起点。正确的处理是去该软件的官方渠道找与你的 Debian 版本匹配的包，或者改用它提供的官方软件源安装。&lt;/p&gt;
&lt;p&gt;:::warning
第三方 .deb 是绕过仓库审核的软件来源，装之前确认下载渠道可信。来路不明的包不要装，它的安装脚本是以 root 权限在你机器上执行的。
:::&lt;/p&gt;
&lt;h2&gt;软件源：一行配置决定软件从哪来&lt;/h2&gt;
&lt;h3&gt;一行的结构&lt;/h3&gt;
&lt;p&gt;传统格式写在 &lt;code&gt;/etc/apt/sources.list&lt;/code&gt;，第三方源放在 &lt;code&gt;/etc/apt/sources.list.d/*.list&lt;/code&gt;，一行就是一个源：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;deb http://deb.debian.org/debian trixie main contrib non-free non-free-firmware
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐段拆开：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;示例&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;类型&lt;/td&gt;
&lt;td&gt;&lt;code&gt;deb&lt;/code&gt; / &lt;code&gt;deb-src&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;deb&lt;/code&gt; 是二进制包，&lt;code&gt;deb-src&lt;/code&gt; 是源码包（日常用不到可不写）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;地址&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http://deb.debian.org/debian&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;仓库根地址&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;发行版代号&lt;/td&gt;
&lt;td&gt;&lt;code&gt;trixie&lt;/code&gt;、&lt;code&gt;bookworm&lt;/code&gt;、&lt;code&gt;trixie-updates&lt;/code&gt;、&lt;code&gt;trixie-security&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;对应 Debian 13 / 12 及其更新通道&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;组件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;main&lt;/code&gt;、&lt;code&gt;contrib&lt;/code&gt;、&lt;code&gt;non-free&lt;/code&gt;、&lt;code&gt;non-free-firmware&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;按自由程度与内容分类&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;组件的区别：&lt;code&gt;main&lt;/code&gt; 是完全自由软件的主仓库；&lt;code&gt;contrib&lt;/code&gt; 是本身自由、但依赖非自由软件的包；&lt;code&gt;non-free&lt;/code&gt; 是非自由软件（某些驱动、字体）；&lt;code&gt;non-free-firmware&lt;/code&gt; 是从 Debian 12 起单列出来的硬件固件。装无线网卡固件、显卡固件找不到包时，先看看源里有没有带上后面两个组件。&lt;/p&gt;
&lt;p&gt;一个完整的 Debian 13 源通常有三组：主仓库（&lt;code&gt;trixie&lt;/code&gt;）、更新通道（&lt;code&gt;trixie-updates&lt;/code&gt;，收录版本间的常规修复）、安全通道（&lt;code&gt;trixie-security&lt;/code&gt;，安全补丁从这里发，最重要，别漏）。&lt;/p&gt;
&lt;p&gt;Debian 13 起新安装的系统默认改用 deb822 格式，源写在 &lt;code&gt;/etc/apt/sources.list.d/debian.sources&lt;/code&gt;，是分段的键值写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Types: deb
URIs: http://deb.debian.org/debian
Suites: trixie trixie-updates
Components: main contrib non-free non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两种格式 apt 都认，老格式不会失效，不用急着迁移；新加第三方源时，跟着该软件官方文档给的格式走即可。&lt;/p&gt;
&lt;p&gt;第三方源还有一个管理上的常识：每个软件的源单独成一个文件放在 &lt;code&gt;sources.list.d/&lt;/code&gt; 里，不要往主 &lt;code&gt;sources.list&lt;/code&gt; 里堆。这样某个软件不用了，删掉它自己的源文件再 &lt;code&gt;apt update&lt;/code&gt; 就干净了，不会牵动系统源。临时想禁用某个源又不想删，把文件改名成不以 &lt;code&gt;.list&lt;/code&gt; 或 &lt;code&gt;.sources&lt;/code&gt; 结尾（比如加个 &lt;code&gt;.disabled&lt;/code&gt; 后缀）即可，apt 会自动跳过它。另外，第三方源通常还附带一个独立的签名密钥文件（放在 &lt;code&gt;/usr/share/keyrings/&lt;/code&gt; 或 &lt;code&gt;/etc/apt/keyrings/&lt;/code&gt;），源和密钥是一对，迁移或排障时要一起检查，密钥过期同样会导致 &lt;code&gt;apt update&lt;/code&gt; 报签名错误。&lt;/p&gt;
&lt;h3&gt;换镜像源&lt;/h3&gt;
&lt;p&gt;官方源在国内访问慢时可以换成镜像站，步骤就三步：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 先备份现有配置
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
sudo cp -r /etc/apt/sources.list.d /etc/apt/sources.list.d.bak

# 2. 编辑源文件，把地址换成镜像站地址（发行版代号与组件保持原样）

# 3. 刷新索引验证
sudo apt update
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;换源之前务必先备份原配置&amp;lt;/span&amp;gt;，镜像站地址写错、代号对不上都会让 &lt;code&gt;apt update&lt;/code&gt; 直接报错，多一份 &lt;code&gt;.bak&lt;/code&gt; 就能一分钟回滚。换完跑 &lt;code&gt;apt update&lt;/code&gt;，没有报错、能正常拉到索引才算换成功。另外第三方软件自己的源文件（比如 Docker、Nginx 官方源）不要顺手一起改地址，它们不在镜像站上，改了反而坏。&lt;/p&gt;
&lt;h2&gt;版本控制：锁住关键包的版本&lt;/h2&gt;
&lt;p&gt;数据库、运行时这类关键软件，有时需要暂时停在某个版本不让它跟着系统一起升：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo apt-mark hold postgresql-17     # 锁定，不再被升级
apt-mark showhold                    # 查看当前锁了哪些包
sudo apt-mark unhold postgresql-17   # 解锁

sudo apt install nginx=1.26.3-3      # 安装指定版本（版本号从 apt-cache policy 里查）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;被 &lt;code&gt;hold&lt;/code&gt; 住的包在 &lt;code&gt;upgrade&lt;/code&gt; 时会被跳过并给出提示。锁定是临时手段不是长期方案：安全补丁也升不上来，锁太久等于主动保留漏洞。正确用法是「等上游修好某个问题」这种有明确期限的场景，并在事情解决后立刻 &lt;code&gt;unhold&lt;/code&gt;。锁了哪些包，定期用 &lt;code&gt;showhold&lt;/code&gt; 盘点一遍，别锁完就忘。&lt;/p&gt;
&lt;h2&gt;自动安全更新：unattended-upgrades&lt;/h2&gt;
&lt;p&gt;服务器不可能天天有人盯着手动升级，但安全补丁拖着不装更危险。Debian 官方的解法是 &lt;code&gt;unattended-upgrades&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo apt install unattended-upgrades
sudo dpkg-reconfigure --priority=low unattended-upgrades
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第二条命令会引导你开启自动更新，并写入 &lt;code&gt;/etc/apt/apt.conf.d/20auto-upgrades&lt;/code&gt;，核心是这两行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;APT::Periodic::Update-Package-Lists &quot;1&quot;;
APT::Periodic::Unattended-Upgrade &quot;1&quot;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它默认的行为是：每天自动 &lt;code&gt;update&lt;/code&gt; 索引，并只安装来自安全通道（security）的更新，常规版本更新不会自动装——这个默认策略很稳健，正是大多数服务器想要的。要调整装哪些来源的更新，看 &lt;code&gt;/etc/apt/apt.conf.d/50unattended-upgrades&lt;/code&gt; 里的 &lt;code&gt;Unattended-Upgrade::Origins-Pattern&lt;/code&gt;，以及这个值得注意的选项：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Unattended-Upgrade::Automatic-Reboot &quot;false&quot;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;要不要让它在内核等需要重启的更新后自动重启机器？个人小服务器、低峰期重启无感的，可以开并配合 &lt;code&gt;Automatic-Reboot-Time&lt;/code&gt; 指定时间；跑着业务的机器建议保持关闭，改为监控提醒、人工挑时间重启。自动更新的日志在 &lt;code&gt;/var/log/unattended-upgrades/&lt;/code&gt;，开启后头几周去翻一翻，确认它真的在按预期工作。&lt;/p&gt;
&lt;p&gt;还要注意它与前面「版本锁定」的配合：被 &lt;code&gt;apt-mark hold&lt;/code&gt; 的包，自动更新同样会跳过，这正是想要的效果。但反过来也要警惕——某个包因为依赖问题被 apt 自动按住、又恰好包含安全修复时，自动更新日志里只会留下一行提示，不去看日志就不会知道自己的机器还暴露在已修复的漏洞下。所以自动更新不是开了就一劳永逸，定期看一眼日志和待升级清单，仍然是运维的基本功。&lt;/p&gt;
&lt;h2&gt;升级纪律：动手之前先想好退路&lt;/h2&gt;
&lt;p&gt;包升级是服务器上最日常、也最容易翻车的操作，几条纪律记牢：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;先看再升&lt;/strong&gt;：&lt;code&gt;apt update&lt;/code&gt; 后先 &lt;code&gt;apt list --upgradable&lt;/code&gt; 摸底，&lt;code&gt;upgrade&lt;/code&gt; 的确认界面里把要装、要删的清单认真扫一遍，出现意料之外的删除项就先取消、查清楚再说。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;先有退路&lt;/strong&gt;：云服务器升级前打个快照，重要服务（数据库、反代）升级前备份配置与数据。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;没有回退手段，就不要在生产机上做大版本升级。&amp;lt;/span&amp;gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;避开高峰&lt;/strong&gt;：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要在业务高峰期执行 full-upgrade&amp;lt;/span&amp;gt;，尤其是涉及内核、libc、数据库的升级，留出出问题时排查和回滚的时间窗口。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;内核升级要重启才生效&lt;/strong&gt;：新内核装上后，正在跑的仍是旧内核。可以用 &lt;code&gt;needrestart&lt;/code&gt;（同名包）检查哪些服务和内核在等重启；重启前确认好带外管理或云厂商控制台可用，别把自己锁在外面。&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;排障&lt;/h2&gt;
&lt;p&gt;包管理翻车的高频场景就集中在三类：锁被占用、依赖损坏、索引对不上。处理它们有一个共同原则——先查状态再动手，每一步做完都验证结果，不要一口气连打几条修复命令。包数据库是整个系统的地基，越是报错的时候越要慢，因为很多「修不好」其实是前一步修复动作本身造成的二次损坏。&lt;/p&gt;
&lt;h3&gt;一、dpkg 锁被占用&lt;/h3&gt;
&lt;p&gt;现象：执行 apt 时报 &lt;code&gt;Could not get lock /var/lib/dpkg/lock-frontend&lt;/code&gt; 或提示另一个进程正在使用 dpkg。&lt;/p&gt;
&lt;p&gt;先搞清楚锁的本质：锁不是某个文件本身，而是进程通过文件锁（flock）占着数据库。常见占用者是无人值守的 &lt;code&gt;unattended-upgrades&lt;/code&gt; 正在后台装安全更新，或者另一个终端里开着的 apt 没退出。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 看是谁占着
sudo fuser -v /var/lib/dpkg/lock-frontend
ps aux | grep -E &apos;apt|dpkg&apos; | grep -v grep
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;处理顺序：能等就等它跑完（安全更新一般几分钟）；确认是残留的僵死进程时，先温和终止再处理：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo kill &amp;lt;进程号&amp;gt;              # 先普通终止，不行再 kill -9
sudo dpkg --configure -a        # 修复可能被中断的配置状态
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不要直接删除 /var/lib/dpkg/lock 等锁文件来「解锁」&amp;lt;/span&amp;gt;：占用锁的进程还活着时删掉文件，不但解不了锁，还可能让两个进程同时写包数据库，把状态文件写坏，把小问题搞成大问题。&lt;/p&gt;
&lt;h3&gt;二、依赖损坏、包处于半配置状态&lt;/h3&gt;
&lt;p&gt;现象：&lt;code&gt;apt install&lt;/code&gt; 报错提示有未满足的依赖，或某个包状态是「iF」「iU」这类半成品。&lt;/p&gt;
&lt;p&gt;按顺序来，先让 dpkg 把没配置完的包配置完，再让 apt 补齐或移除坏掉的依赖关系：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo dpkg --configure -a        # 把处于半配置状态的包逐个配置完
sudo apt --fix-broken install   # 修复损坏的依赖（可能装新包，也可能卸掉冲突包）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--fix-broken&lt;/code&gt; 给出的方案要看清楚再确认：它有时会以「卸载某个包」来解开死结，如果那个包正是你要用的服务，先别同意，回到具体是哪个依赖冲突，考虑换版本或用 &lt;code&gt;apt-mark hold&lt;/code&gt; 配合处理。&lt;/p&gt;
&lt;h3&gt;三、Hash Sum mismatch&lt;/h3&gt;
&lt;p&gt;现象：&lt;code&gt;apt update&lt;/code&gt; 时某个源报 &lt;code&gt;Hash Sum mismatch&lt;/code&gt;，索引下载失败。&lt;/p&gt;
&lt;p&gt;这通常是本地缓存的索引与仓库文件对不上：镜像同步到一半、本地列表损坏都可能造成。先清掉本地索引重拉：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo apt clean
sudo rm -rf /var/lib/apt/lists/*
sudo apt update
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;还不行，多半是当前镜像站本身同步异常，临时切回官方源 &lt;code&gt;deb.debian.org&lt;/code&gt; 验证一下，能通就说明问题在镜像侧，等它同步完成或换一个镜像。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;分工记牢：dpkg 管本地包与本机状态，apt 管仓库、索引与依赖；查文件归属用 &lt;code&gt;dpkg -S&lt;/code&gt;，查仓库用 &lt;code&gt;apt-cache&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;apt update&lt;/code&gt; 只更新索引，任何装升操作之前先跑；&lt;code&gt;upgrade&lt;/code&gt; 保守，&lt;code&gt;full-upgrade&lt;/code&gt; 才会为依赖变化装新包、删旧包。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;remove&lt;/code&gt; 留配置，&lt;code&gt;purge&lt;/code&gt; 连配置一起删；卸载后顺手 &lt;code&gt;autoremove&lt;/code&gt; 清孤儿依赖。&lt;/li&gt;
&lt;li&gt;装本地 &lt;code&gt;.deb&lt;/code&gt; 用 &lt;code&gt;apt install ./文件&lt;/code&gt;，依赖自动补齐，别再走 &lt;code&gt;dpkg -i&lt;/code&gt; 再擦屁股的老路。&lt;/li&gt;
&lt;li&gt;软件源一行 = 类型 + 地址 + 发行版代号 + 组件，安全通道不能漏；换源先备份，换完用 &lt;code&gt;apt update&lt;/code&gt; 验证。&lt;/li&gt;
&lt;li&gt;关键包可以 &lt;code&gt;apt-mark hold&lt;/code&gt; 临时锁版本，但别锁完就忘；安全更新交给 &lt;code&gt;unattended-upgrades&lt;/code&gt; 自动跑，自动重启与否按业务取舍。&lt;/li&gt;
&lt;li&gt;翻车处理有顺序：锁占用先查进程、绝不删锁文件；依赖损坏先 &lt;code&gt;dpkg --configure -a&lt;/code&gt; 再 &lt;code&gt;apt --fix-broken install&lt;/code&gt;；Hash 不一致先清索引重拉。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>Linux 性能排障：CPU、内存、IO、网络四条线</title><link>https://www.anexns.cloudns.org/posts/linux-performance-troubleshooting/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-performance-troubleshooting/</guid><description>服务器卡了不要靠重启大法：按 CPU、内存、磁盘 IO、网络四条线逐条定位，负载与使用率的区别、内存到底去哪了、IO 等待怎么看，一套能落地的排查顺序。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h1&gt;Linux 性能排障：CPU、内存、IO、网络四条线&lt;/h1&gt;
&lt;p&gt;服务器变卡的时候，多数人的第一反应是重启。重启确实常常&quot;立竿见影&quot;，但它解决的不是问题，是证据：进程内存泄漏了？某个任务在狂写磁盘？连接堆积了？重启之后现场全部清零，下次再犯还是抓瞎，而且两次故障之间你什么都没学到。&lt;/p&gt;
&lt;p&gt;这篇讲一套能落地的排查顺序。核心思路只有一句：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;先分清卡在哪条线上，再沿着那条线往下钻&amp;lt;/span&amp;gt;。服务器性能问题归根结底逃不出四条线：CPU、内存、磁盘 IO、网络。每条线都有自己的入口命令和判断标准，按顺序过一遍，绝大多数&quot;变卡&quot;都能定位到具体进程和具体原因。&lt;/p&gt;
&lt;p&gt;全文以 Debian 为主线，命令在 Ubuntu 上同样适用。工具大多来自 &lt;code&gt;procps&lt;/code&gt;、&lt;code&gt;sysstat&lt;/code&gt; 这两个包，文中会先把工具装齐。&lt;/p&gt;
&lt;h2&gt;一、方法论先行：先确认症状，再分线排查&lt;/h2&gt;
&lt;p&gt;动手之前先花两分钟把症状确认清楚，这一步省掉的弯路比后面所有命令加起来都多。&lt;/p&gt;
&lt;h3&gt;1.1 先回答四个问题&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;卡的表现是什么？&lt;/strong&gt; 是网页打开慢、SSH 登录迟钝、命令执行卡顿，还是某个服务直接无响应？不同表现指向不同的线。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;范围有多大？&lt;/strong&gt; 整台机器都卡，还是只有一个服务卡？只有一个容器卡，先去看那个容器，别急着查整机。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;什么时候开始的？&lt;/strong&gt; 刚部署完新版本之后？某个整点任务跑起来之后？流量高峰？时间点往往直接指向元凶。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;是突发的还是缓慢恶化的？&lt;/strong&gt; 突发多半是任务、流量或故障；缓慢恶化多半是泄漏、数据增长、日志膨胀。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;1.2 四条线的排查顺序&lt;/h3&gt;
&lt;p&gt;推荐的默认顺序是 CPU → 内存 → IO → 网络，原因很实际：前两条线用 &lt;code&gt;top&lt;/code&gt; 一眼就能看个大概，IO 和网络需要多敲几个命令。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;顺序&lt;/th&gt;
&lt;th&gt;线&lt;/th&gt;
&lt;th&gt;入口命令&lt;/th&gt;
&lt;th&gt;一眼能确认什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;CPU&lt;/td&gt;
&lt;td&gt;&lt;code&gt;uptime&lt;/code&gt;、&lt;code&gt;top&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;负载多高、谁在吃 CPU、IO 等待占比&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;内存&lt;/td&gt;
&lt;td&gt;&lt;code&gt;free -h&lt;/code&gt;、&lt;code&gt;top&lt;/code&gt;（按 M 排序）&lt;/td&gt;
&lt;td&gt;真实可用内存、谁是内存大户、有没有在用 Swap&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;IO&lt;/td&gt;
&lt;td&gt;&lt;code&gt;iostat -x 1&lt;/code&gt;、&lt;code&gt;iotop&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;磁盘忙不忙、延迟多高、谁在读写&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;网络&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ss -s&lt;/code&gt;、&lt;code&gt;sar -n DEV 1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;连接堆积、流量异常、丢包重传&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要上来就重启&amp;lt;/span&amp;gt;。除非业务正在遭受不可承受的损失、必须先恢复再说，否则至少先把 &lt;code&gt;top&lt;/code&gt;、&lt;code&gt;free -h&lt;/code&gt;、&lt;code&gt;iostat&lt;/code&gt; 的输出截图或存档留一份。没有现场的故障，复盘时只能靠猜。
:::&lt;/p&gt;
&lt;h3&gt;1.3 把工具装齐&lt;/h3&gt;
&lt;p&gt;Debian 默认不带 &lt;code&gt;iostat&lt;/code&gt;、&lt;code&gt;iotop&lt;/code&gt; 这些工具，先装好：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apt update
apt install -y sysstat htop iotop iftop
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;sysstat&lt;/code&gt; 提供 &lt;code&gt;iostat&lt;/code&gt;、&lt;code&gt;sar&lt;/code&gt;、&lt;code&gt;pidstat&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;htop&lt;/code&gt; 是 &lt;code&gt;top&lt;/code&gt; 的增强版，看进程更直观；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;iotop&lt;/code&gt; 按进程看磁盘读写，需要 root 权限；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;iftop&lt;/code&gt; 按连接看网卡流量。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;二、通用入口：uptime 与 top 先过一遍&lt;/h2&gt;
&lt;h3&gt;2.1 load average：三个数到底怎么读&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;uptime&lt;/code&gt; 的输出末尾是三组负载数字：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt; 14:32:07 up 26 days,  3:14,  2 users,  load average: 2.85, 1.92, 1.20
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;三个数分别是过去 &lt;strong&gt;1 分钟、5 分钟、15 分钟&lt;/strong&gt; 的平均负载。看趋势比看绝对值重要：1 分钟远大于 15 分钟，说明负载正在爬升；反过来说明高峰已过。&lt;/p&gt;
&lt;p&gt;负载的定义是：&lt;strong&gt;处于可运行状态（R）和不可中断睡眠状态（D）的进程平均数&lt;/strong&gt;。这里有个最常见的误解必须纠正：load 高不等于 CPU 高。D 状态进程通常是卡在磁盘 IO 上等数据，它们不消耗 CPU，但会计入负载。所以 load 很高而 CPU 使用率不高时，问题多半在 IO 线，不在 CPU 线。&lt;/p&gt;
&lt;p&gt;负载和核数的关系决定了&quot;多高算高&quot;：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;机器核数&lt;/th&gt;
&lt;th&gt;load 长期值&lt;/th&gt;
&lt;th&gt;判断&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;2 核&lt;/td&gt;
&lt;td&gt;接近或超过 2&lt;/td&gt;
&lt;td&gt;CPU/IO 已排队，开始变慢&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4 核&lt;/td&gt;
&lt;td&gt;接近或超过 4&lt;/td&gt;
&lt;td&gt;满负荷，进一步恶化会雪崩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;8 核&lt;/td&gt;
&lt;td&gt;3～4&lt;/td&gt;
&lt;td&gt;只用了一半左右，不算高&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;查核数：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;nproc
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;经验线：load 长期超过核数的 70% 就值得警惕，持续超过核数本身说明请求已经在排队。&lt;/p&gt;
&lt;h3&gt;2.2 top 的关键列逐个讲&lt;/h3&gt;
&lt;p&gt;运行 &lt;code&gt;top&lt;/code&gt; 后先看顶部汇总区：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;%Cpu(s): 12.5 us,  3.1 sy,  0.0 ni, 78.2 id,  5.9 wa,  0.0 hi,  0.3 si,  0.0 st
&lt;/code&gt;&lt;/pre&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;高了说明什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;us&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;用户态 CPU&lt;/td&gt;
&lt;td&gt;应用程序本身在忙（计算、循环、请求量大）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;sy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;内核态 CPU&lt;/td&gt;
&lt;td&gt;系统调用频繁、网络收发包、上下文切换多&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;id&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;空闲&lt;/td&gt;
&lt;td&gt;越低越忙，长期接近 0 说明 CPU 真不够用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;wa&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;IO 等待&lt;/td&gt;
&lt;td&gt;CPU 在等磁盘，长期高直接转 IO 线排查&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;st&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;被宿主机偷走的时间&lt;/td&gt;
&lt;td&gt;云服务器特有，高了是宿主机超售或邻居抢资源&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;进程列表里重点看这几列：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;列&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;排查要点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;%CPU&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;进程 CPU 占用&lt;/td&gt;
&lt;td&gt;多核机器上可以超过 100%，400% 约等于吃满 4 个核&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;RES&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;实际占用的物理内存&lt;/td&gt;
&lt;td&gt;判断内存大户看这个，不要看 &lt;code&gt;VIRT&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SHR&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;共享内存&lt;/td&gt;
&lt;td&gt;多个进程共用同一批库时不要重复计算&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;S&lt;/code&gt;（状态）&lt;/td&gt;
&lt;td&gt;进程状态&lt;/td&gt;
&lt;td&gt;&lt;code&gt;R&lt;/code&gt; 在跑、&lt;code&gt;S&lt;/code&gt; 在睡、&lt;code&gt;D&lt;/code&gt; 不可中断睡眠（多在等 IO）、&lt;code&gt;Z&lt;/code&gt; 僵尸&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;top&lt;/code&gt; 里两个高频操作：按 &lt;code&gt;M&lt;/code&gt; 按内存排序找大户，按 &lt;code&gt;P&lt;/code&gt; 回到按 CPU 排序。&lt;code&gt;htop&lt;/code&gt; 里同样的事用 F6 选排序列，还能直接看到每个核的占用条。&lt;/p&gt;
&lt;h2&gt;三、CPU 线：谁在吃、吃在哪&lt;/h2&gt;
&lt;h3&gt;3.1 先分清是 us 高还是 sy 高&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;us&lt;/code&gt; 高&lt;/strong&gt;：应用程序自己的代码在烧 CPU。可能是流量真的大，也可能是死循环、正则回溯、加密计算过重。用 &lt;code&gt;top&lt;/code&gt; 找到进程后，剩下的事是去看这个应用的日志和监控。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;sy&lt;/code&gt; 高&lt;/strong&gt;：内核在替进程忙。常见原因是小包高频收发（网络服务没做批量处理）、疯狂打日志、频繁创建销毁进程和线程。这类问题 CPU 使用率看着高，但业务代码本身没干多少活。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;找吃 CPU 的进程：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 按 CPU 排序看前 10 个进程
ps aux --sort=-%cpu | head -11

# 实时盯某个进程的线程级占用（有些程序是一个进程多线程在烧）
top -H -p &amp;lt;PID&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;3.2 上下文切换：隐形的 CPU 小偷&lt;/h3&gt;
&lt;p&gt;进程切换本身不干活，但切换太频繁会把 CPU 耗在调度上，表现是 &lt;code&gt;sy&lt;/code&gt; 偏高、吞吐上不去。用 &lt;code&gt;vmstat&lt;/code&gt; 看：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;vmstat 1 5
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重点看两列：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;列&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;判断&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cs&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每秒上下文切换次数&lt;/td&gt;
&lt;td&gt;空闲机器一般几百到几千；长期十万级且伴随 sy 高，就是切换在吃 CPU&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;in&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每秒中断次数&lt;/td&gt;
&lt;td&gt;网卡中断风暴时异常高&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;想定位到具体进程，用 &lt;code&gt;pidstat&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 每秒刷新，看各进程的 CPU 与上下文切换
pidstat -w 1

# 只看某个进程
pidstat -p &amp;lt;PID&amp;gt; 1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出里的 &lt;code&gt;cswch/s&lt;/code&gt; 是主动切换（多在等锁、等 IO），&lt;code&gt;nvcswch/s&lt;/code&gt; 是被动切换（时间片用完被抢）。主动切换高，先查它在等什么；被动切换高，说明 CPU 竞争确实激烈。&lt;/p&gt;
&lt;h3&gt;3.3 CPU 线的判断标准汇总&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;现象&lt;/th&gt;
&lt;th&gt;结论&lt;/th&gt;
&lt;th&gt;下一步&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;us&lt;/code&gt; 高、单进程吃满&lt;/td&gt;
&lt;td&gt;应用热点或死循环&lt;/td&gt;
&lt;td&gt;查该应用日志、请求量&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;sy&lt;/code&gt; 高、&lt;code&gt;cs&lt;/code&gt; 十万级&lt;/td&gt;
&lt;td&gt;切换/系统调用过载&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pidstat -w&lt;/code&gt; 定位进程&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;load 高但 CPU 使用率低&lt;/td&gt;
&lt;td&gt;不是 CPU 的问题&lt;/td&gt;
&lt;td&gt;转 IO 线，查 D 状态进程&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;st&lt;/code&gt; 长期大于 5%&lt;/td&gt;
&lt;td&gt;云主机被偷算力&lt;/td&gt;
&lt;td&gt;换宿主机或升级规格，优化代码没用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
&lt;code&gt;st&lt;/code&gt; 高是云服务器上最容易误判的情况：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要在 st 高的时候去优化自己的代码&amp;lt;/span&amp;gt;，算力是被宿主机拿走的，工单和迁移才是正解。
:::&lt;/p&gt;
&lt;h2&gt;四、内存线：内存到底去哪了&lt;/h2&gt;
&lt;h3&gt;4.1 free 的正确读法&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;free -h
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;               total        used        free      shared  buff/cache   available
Mem:           7.8Gi       3.1Gi       512Mi       128Mi       4.2Gi       4.3Gi
Swap:          2.0Gi       380Mi       1.6Gi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;新手最容易被 &lt;code&gt;free&lt;/code&gt; 只剩 512Mi 吓到，其实完全不用慌：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;buff/cache&lt;/code&gt; 是内核拿空闲内存做的磁盘缓存，&lt;strong&gt;不是被程序吃掉的&lt;/strong&gt;，程序需要内存时它会立刻让出来；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;available&lt;/code&gt; 才是内核估算的&quot;还能给新程序用多少&quot;，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;判断内存够不够，只看 available&amp;lt;/span&amp;gt;；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;used&lt;/code&gt; 里包含了各种常驻服务，单独看它没有意义。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;真正的内存紧张信号是：&lt;code&gt;available&lt;/code&gt; 长期只剩总量的 5% 以下，并且 Swap 在持续增长。&lt;/p&gt;
&lt;h3&gt;4.2 找内存大户&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 按内存排序看前 10 个进程
ps aux --sort=-%mem | head -11

# top 里按 M 键排序，效果相同
top
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意按进程看会漏掉一种情况：单个进程不大，但同名进程有一百个（比如 PHP-FPM、预派生工作进程）。这时按进程名汇总：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ps -eo rss,comm --no-headers | awk &apos;{a[$2]+=$1} END {for (k in a) print a[k]/1024 &quot; MB&quot;, k}&apos; | sort -rn | head
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;4.3 OOM Killer：进程&quot;莫名消失&quot;的证据在这&lt;/h3&gt;
&lt;p&gt;内存真的耗尽时，内核会启动 OOM Killer 杀掉一个进程换空间。服务半夜&quot;自己停了&quot;，十有八九是它干的。证据查这里：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 内核日志里找 Out of memory 记录
dmesg -T | grep -i -E &quot;out of memory|oom-kill|killed process&quot;

# 用 journalctl 查也一样
journalctl -k --since &quot;24 hours ago&quot; | grep -i &quot;killed process&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;典型输出：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Out of memory: Killed process 12845 (java) total-vm:5234108kB, anon-rss:3102456kB
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这行日志会写清谁被杀、当时占了多少内存。看到它，方向就明确了：要么那个进程在泄漏，要么机器内存真不够，靠加 Swap 只能延缓。&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;千万不要把&quot;关掉 OOM Killer&quot;当解决方案&amp;lt;/span&amp;gt;。关掉它不会变出内存，只会让整机在内存耗尽时一起卡死，从&quot;死一个服务&quot;变成&quot;全站宕机&quot;。
:::&lt;/p&gt;
&lt;h3&gt;4.4 Swap 被用上了意味着什么&lt;/h3&gt;
&lt;p&gt;Swap 里有数据不等于出事——内核会把长期不用的冷页换出去，给缓存腾地方。判断标准看&lt;strong&gt;换入换出是否持续发生&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;vmstat 1 5
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;看 &lt;code&gt;si&lt;/code&gt;（每秒从 Swap 换入）和 &lt;code&gt;so&lt;/code&gt;（每秒换出到 Swap）两列：偶尔有数字正常；&lt;strong&gt;长期持续非零，说明内存确实不够，程序正在拿磁盘当内存用&lt;/strong&gt;，这时整机会明显变卡，先按 4.2 找大户，或者准备扩容。&lt;/p&gt;
&lt;h2&gt;五、IO 线：磁盘在忙什么&lt;/h2&gt;
&lt;h3&gt;5.1 iostat -x：一眼看清磁盘状态&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;iostat -x 1 5
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重点看这几列（以输出设备行为准）：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;列&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;判断&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;r/s&lt;/code&gt;、&lt;code&gt;w/s&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每秒读/写次数&lt;/td&gt;
&lt;td&gt;结合业务量看是否异常暴增&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;rkB/s&lt;/code&gt;、&lt;code&gt;wkB/s&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每秒读写吞吐&lt;/td&gt;
&lt;td&gt;是否顶到磁盘带宽上限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;await&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;IO 平均等待时间（毫秒）&lt;/td&gt;
&lt;td&gt;SSD 应在 1ms 上下；持续超过 10ms 就有明显排队&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;%util&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;磁盘忙碌时间占比&lt;/td&gt;
&lt;td&gt;长期接近 100% 说明这块盘已满负荷&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
&lt;code&gt;%util&lt;/code&gt; 接近 100% 对传统机械盘和单队列设备基本等于饱和，但对 NVMe 和多队列 SSD 只能作参考——它们能并行处理请求，util 满了不一定慢。判断 IO 到底卡不卡，最终看 await，延迟上去了才是真排队。
:::&lt;/p&gt;
&lt;h3&gt;5.2 iotop：找到底是哪个进程在读写&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;iotop -o
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;-o&lt;/code&gt; 只显示正在发生 IO 的进程。看 &lt;code&gt;DISK READ&lt;/code&gt;、&lt;code&gt;DISK WRITE&lt;/code&gt; 两列和右侧的命令名。日志狂写、数据库刷盘、备份任务、解压大文件，最常见的元凶都在这里现形。&lt;/p&gt;
&lt;h3&gt;5.3 wa 高和 D 状态：IO 卡的典型画像&lt;/h3&gt;
&lt;p&gt;回到 &lt;code&gt;top&lt;/code&gt;：如果 &lt;code&gt;%Cpu(s)&lt;/code&gt; 那行里 &lt;code&gt;wa&lt;/code&gt; 长期高于 20%～30%，说明大量 CPU 时间在等磁盘。再看进程列表里 &lt;code&gt;D&lt;/code&gt; 状态进程堆了几个：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 数一数当前有多少 D 状态进程
ps -eo state | grep -c &quot;^D&quot;

# 把它们列出来
ps -eo pid,state,comm | awk &apos;$2 ~ /^D/&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;D 状态进程堆积的含义是：&lt;strong&gt;请求已经发给磁盘了，但磁盘迟迟不回话&lt;/strong&gt;。可能是磁盘满负荷、磁盘故障（云盘劣化也算）、或者网络存储（NFS 等）无响应。这类进程 &lt;code&gt;kill -9&lt;/code&gt; 也杀不掉，只能等 IO 返回或处理底层存储，别在进程层面浪费时间。&lt;/p&gt;
&lt;h3&gt;5.4 磁盘满和 IO 卡是两回事&lt;/h3&gt;
&lt;p&gt;顺手把这组命令也跑一下，空间问题伪装成性能问题的案例太多了：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;df -h          # 看容量
df -i          # 看 inode，小文件太多时容量没满 inode 先满
du -sh /var/* 2&amp;gt;/dev/null | sort -rh | head   # 找占空间的大目录
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;容量 100%：写不进新数据，数据库、日志、上传一起报错；&lt;/li&gt;
&lt;li&gt;inode 100%：表现一模一样（无法创建文件），但 &lt;code&gt;df -h&lt;/code&gt; 看着还有空间，只看 &lt;code&gt;-i&lt;/code&gt; 才发现。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;六、网络线：连接堆积与丢包&lt;/h2&gt;
&lt;h3&gt;6.1 ss 看连接状态分布&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 汇总：各状态连接数一目了然
ss -s

# 只统计状态分布
ss -tan | awk &apos;NR&amp;gt;1 {a[$1]++} END {for (k in a) print k, a[k]}&apos; | sort -k2 -rn
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两种最常见的堆积，含义完全不同：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;状态&lt;/th&gt;
&lt;th&gt;堆积说明什么&lt;/th&gt;
&lt;th&gt;常见原因&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;TIME_WAIT&lt;/code&gt; 多（上万）&lt;/td&gt;
&lt;td&gt;本机在频繁主动关连接&lt;/td&gt;
&lt;td&gt;短连接太多、没用连接池；多数情况可承受，别急着改内核参数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;CLOSE_WAIT&lt;/code&gt; 多且持续增长&lt;/td&gt;
&lt;td&gt;对端关了，本机程序没关&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;基本是应用 bug：连接用完没 close&amp;lt;/span&amp;gt;，改代码，别调系统&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;查哪个进程占着连接：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ss -tanp | grep CLOSE_WAIT | head
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;6.2 网卡流量：跑满了还是异常突增&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 每秒刷新各网卡的收发速率
sar -n DEV 1

# 按连接看谁在传
iftop -i eth0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;网卡名先用 &lt;code&gt;ip -br a&lt;/code&gt; 确认。判断两点：速率是否顶到带宽上限（千兆网卡约 125 MB/s，云主机看实例规格的带宽上限）；是否出现与业务无关的异常流量（比如半夜备份、被盗刷流量）。&lt;/p&gt;
&lt;h3&gt;6.3 丢包与重传：连接慢的隐形原因&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;netstat -s | grep -i -E &quot;retrans|drop|overflow|timeout&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;（&lt;code&gt;netstat&lt;/code&gt; 来自 &lt;code&gt;net-tools&lt;/code&gt; 包，新系统可用 &lt;code&gt;nstat&lt;/code&gt; 替代，或看 &lt;code&gt;ss -ti&lt;/code&gt; 里单个连接的 &lt;code&gt;retrans&lt;/code&gt; 字段。）&lt;/p&gt;
&lt;p&gt;重点看：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;指标&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;判断&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;segments retransmitted&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;TCP 重传段数&lt;/td&gt;
&lt;td&gt;持续快速增长说明链路在丢包，先查网络侧&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;listen queue overflow&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;监听队列溢出次数&lt;/td&gt;
&lt;td&gt;大于 0 说明连接进来的速度超过程序 accept 的速度&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SYNs to LISTEN sockets dropped&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;半连接被丢弃&lt;/td&gt;
&lt;td&gt;队列满或疑似 SYN 洪水&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;单个连接的实时情况用 &lt;code&gt;ss -ti&lt;/code&gt; 看，里面的 &lt;code&gt;rtt&lt;/code&gt;（往返时延）和 &lt;code&gt;retrans&lt;/code&gt;（已重传次数）能直接判断这条连接的链路质量。&lt;/p&gt;
&lt;h2&gt;七、完整剧本：网站变慢，十五分钟定位到日志打满 IO&lt;/h2&gt;
&lt;p&gt;下面是一次真实感的完整排查，命令链按顺序执行，演示四条线怎么串起来用。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;背景&lt;/strong&gt;：下午三点，监控报警：网站响应时间从 200ms 涨到 3 秒以上，偶发 502。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第 1 分钟，先看负载和全局状态：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;uptime
# load average: 6.42, 5.87, 4.15 —— 4 核机器，负载已超核数且还在涨

top
# %Cpu(s): 8.2 us, 4.1 sy, 55.3 id, 31.8 wa
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;CPU 使用率总共才百分之十几，但 &lt;code&gt;wa&lt;/code&gt; 高达 31.8%——第一判断：&lt;strong&gt;不是 CPU 的问题，是 IO 在拖&lt;/strong&gt;。load 高的原因也找到了：进程都堵在磁盘上。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第 3 分钟，确认内存没参与作案：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;free -h
# available 还有 3.2Gi，Swap 只用了 90Mi 且 vmstat 里 si/so 都是 0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;内存线排除。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第 5 分钟，锁定磁盘状态：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;iostat -x 1 3
# vda: w/s 412, wkB/s 38500, await 46.20, %util 99.8
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;写等待 46ms、利用率 99.8%，这块盘已经被写满了。接下来只有一个问题：谁在写？&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第 7 分钟，揪出写盘的进程：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;iotop -o
# Total DISK WRITE: 37.5 MB/s
#  12845 be/4 root  0.00 B/s  34.2 MB/s  ...  app-worker --log-level=debug
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;一个应用进程在以 34 MB/s 的速度写盘。顺手确认它在写哪个文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ls -l /proc/12845/fd | grep -v -E &quot;socket|pipe&quot; | tail
# 3 -&amp;gt; /var/log/app/app.log

du -sh /var/log/app/
# 18G    /var/log/app/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;第 10 分钟，找根因而不是只处理现场：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;tail -c 2000 /var/log/app/app.log
# 满屏同一条 DEBUG 级别的请求体打印

grep -rn &quot;log&quot; /opt/app/config/ | grep -i level
# config.yaml: level: debug
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;根因清楚了：上午发版时把日志级别误改成了 &lt;code&gt;debug&lt;/code&gt;，每个请求都把完整请求体和响应体写进日志，磁盘 IO 被日志写满，所有服务一起变慢。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第 13 分钟，处置与收尾：&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 改回 info 并重启该服务（配置类问题，重启是正当处置）
sed -i &apos;s/level: debug/level: info/&apos; /opt/app/config/config.yaml
systemctl restart app

# 2. 清理失控的日志文件并确认空间回收
truncate -s 0 /var/log/app/app.log
df -h /

# 3. 给日志目录配上轮转，防止再犯（logrotate 配置略，见本系列日志管理篇）

# 4. 回看指标确认恢复
iostat -x 1 3
# await 回到 0.8ms，%util 12%
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;整个过程没重启整机、没瞎试参数，四条线排除三条、在第四条线上走到底，并且留下了明确根因和防再犯措施——这就是分线排查的价值。&lt;/p&gt;
&lt;h2&gt;八、症状速查表&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;症状&lt;/th&gt;
&lt;th&gt;先看哪条线&lt;/th&gt;
&lt;th&gt;关键命令&lt;/th&gt;
&lt;th&gt;典型元凶&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;整机卡顿、命令都慢&lt;/td&gt;
&lt;td&gt;CPU → IO&lt;/td&gt;
&lt;td&gt;&lt;code&gt;uptime&lt;/code&gt;、&lt;code&gt;top&lt;/code&gt; 看 &lt;code&gt;wa&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;任务打满 CPU、磁盘被写满&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;load 很高但 CPU 不高&lt;/td&gt;
&lt;td&gt;IO&lt;/td&gt;
&lt;td&gt;&lt;code&gt;iostat -x 1&lt;/code&gt;、&lt;code&gt;ps&lt;/code&gt; 看 D 状态&lt;/td&gt;
&lt;td&gt;磁盘排队、存储故障、NFS 无响应&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;服务进程半夜消失&lt;/td&gt;
&lt;td&gt;内存&lt;/td&gt;
&lt;td&gt;&lt;code&gt;dmesg -T | grep -i &quot;killed process&quot;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;OOM Killer、内存泄漏&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;越跑越慢、重启就好（几天后复发）&lt;/td&gt;
&lt;td&gt;内存&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ps aux --sort=-%mem&lt;/code&gt;、&lt;code&gt;vmstat 1&lt;/code&gt; 看 &lt;code&gt;si/so&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;内存泄漏、连接/句柄泄漏&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;网站慢但机器很闲&lt;/td&gt;
&lt;td&gt;网络&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ss -s&lt;/code&gt;、&lt;code&gt;netstat -s&lt;/code&gt; 看重传&lt;/td&gt;
&lt;td&gt;链路丢包、连接堆积、带宽跑满&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;某个端口连接不上、新连接被拒&lt;/td&gt;
&lt;td&gt;网络&lt;/td&gt;
&lt;td&gt;&lt;code&gt;netstat -s&lt;/code&gt; 看 listen overflow&lt;/td&gt;
&lt;td&gt;监听队列满、程序 accept 太慢&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;磁盘空间没满却写不了文件&lt;/td&gt;
&lt;td&gt;IO&lt;/td&gt;
&lt;td&gt;&lt;code&gt;df -i&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;inode 耗尽（小文件太多）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;九、什么时候该扩容，而不是优化&lt;/h2&gt;
&lt;p&gt;排查的终点不总是&quot;改个参数就好了&quot;。出现下面这些信号，说明瓶颈是规格本身，继续优化是浪费时间：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;某条线的水位&lt;strong&gt;长期&lt;/strong&gt;（以周为单位）处在高位：CPU 使用率常年 80% 以上、内存 available 常年见底、磁盘 await 在业务低峰也降不下来；&lt;/li&gt;
&lt;li&gt;已经确认没有异常进程、没有泄漏、没有配置错误，吃资源的都是正经业务；&lt;/li&gt;
&lt;li&gt;流量和数据量的增长曲线明确，现有规格按当前增速撑不过一两个月。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这时候正确的动作是升配、拆分服务或加机器。反过来，突发异常先排查再扩容——给一台被日志打满 IO 的机器升配，只会得到一块更贵的、继续被打满的盘。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;排障先讲方法论：确认症状、范围、时间和趋势，再按 CPU → 内存 → IO → 网络四条线逐条排除；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;load&lt;/code&gt; 高不等于 CPU 高，D 状态进程一样计入负载，&lt;code&gt;top&lt;/code&gt; 里的 &lt;code&gt;wa&lt;/code&gt; 是分流到 IO 线的信号；&lt;/li&gt;
&lt;li&gt;看内存只看 &lt;code&gt;available&lt;/code&gt;，&lt;code&gt;buff/cache&lt;/code&gt; 不是被吃掉；进程消失先去 &lt;code&gt;dmesg&lt;/code&gt; 找 OOM 证据；&lt;/li&gt;
&lt;li&gt;看磁盘最终看 &lt;code&gt;await&lt;/code&gt; 而不是 &lt;code&gt;%util&lt;/code&gt;；D 状态堆积说明请求在等存储返回，杀进程没用；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;TIME_WAIT&lt;/code&gt; 多半无害，&lt;code&gt;CLOSE_WAIT&lt;/code&gt; 堆积基本是应用没关连接的代码问题；&lt;/li&gt;
&lt;li&gt;处置完要留根因和防再犯措施；水位长期高位且无异常，就是该扩容的信号，别和规格硬耗。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;下一篇是本系列的收官篇：《Linux 安全巡检清单》，把前面各篇的安全要点汇成一张可以逐项打勾的检查表。&lt;/p&gt;
</content:encoded></item><item><title>Linux 进程管理实战</title><link>https://www.anexns.cloudns.org/posts/linux-process-management/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-process-management/</guid><description>看懂、管好、杀对进程：ps 与 top 的字段解读、信号的语义差别、前后台作业、优先级调整，以及杀不掉的进程与僵尸进程到底怎么回事。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;服务器运维里最高频的动作之一，就是跟进程打交道：CPU 跑满了要找到是谁在吃、服务卡死了要把它结束掉、脚本跑一半想切到后台继续、某个进程怎么杀都杀不掉……这些场景背后其实只有三件事：&lt;strong&gt;看懂进程、发对信号、理清父子关系&lt;/strong&gt;。这篇就围绕这三件事展开：先讲清进程的基本概念和 PID/PPID，再把 &lt;code&gt;ps&lt;/code&gt; 与 &lt;code&gt;top&lt;/code&gt; 的输出逐列读懂，然后讲信号体系——为什么结束进程要先发 TERM 再发 KILL、每个信号到底意味着什么，接着是前后台作业、nice 优先级，最后专讲两个最容易让人抓狂的问题：杀不掉的进程和僵尸进程。性能层面的整体排查思路，可以配合本系列的&lt;a href=&quot;/posts/linux-performance-troubleshooting/&quot;&gt;性能排障篇&lt;/a&gt;一起看。&lt;/p&gt;
&lt;h2&gt;一、进程是什么&lt;/h2&gt;
&lt;p&gt;一句话：&lt;strong&gt;进程就是正在运行的程序实例&lt;/strong&gt;。你把一个程序从磁盘加载到内存、由内核调度着占用 CPU 执行，它就是一个进程。同一个程序可以同时跑出多个进程（比如开多个 &lt;code&gt;ssh&lt;/code&gt; 会话），每个进程都有自己独立的内存空间和身份编号。&lt;/p&gt;
&lt;p&gt;几个绕不开的概念：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;PID&lt;/strong&gt;：进程的唯一编号，内核分配，从 1 开始递增。PID 1 在 systemd 系统上就是 systemd 本身，它是所有进程的老祖宗。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;PPID&lt;/strong&gt;：父进程的 PID。每个进程都是被另一个进程&quot;生&quot;出来的（通过 fork/exec），父子关系构成了整棵进程树。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;进程树&lt;/strong&gt;：用 &lt;code&gt;pstree&lt;/code&gt; 可以把父子关系画出来，看清&quot;谁拉起了谁&quot;——这在排查&quot;进程杀了又活&quot;时是关键线索。&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;# 看进程树（-p 带 PID，-a 带命令行参数）
pstree -ap

# 只看某个进程的子孙
pstree -ap &amp;lt;PID&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;每个进程在 &lt;code&gt;/proc&lt;/code&gt; 文件系统里都有一个以 PID 命名的目录，这是内核暴露的&quot;进程档案室&quot;，很多工具（包括 &lt;code&gt;ps&lt;/code&gt;、&lt;code&gt;top&lt;/code&gt;）的数据其实都来自这里。手动看一眼，能加深理解：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 以 PID 1234 为例
cat /proc/1234/status        # 状态、内存、父进程、线程数等总览
ls -l /proc/1234/exe         # 这个进程实际执行的是哪个程序文件
cat /proc/1234/cmdline | tr &apos;\0&apos; &apos; &apos;   # 启动它的完整命令行
ls -l /proc/1234/cwd         # 它当前的工作目录
ls /proc/1234/fd             # 它打开了哪些文件/套接字
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;/proc/&amp;lt;PID&amp;gt;&lt;/code&gt; 目录只在进程活着时存在，进程一退出目录就消失。排查转瞬即逝的短命进程时，不要指望事后去翻 &lt;code&gt;/proc&lt;/code&gt;。
:::&lt;/p&gt;
&lt;h2&gt;二、查进程：ps 逐列读懂&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;ps&lt;/code&gt; 是最常用的查进程命令，但很多人只会敲 &lt;code&gt;ps aux&lt;/code&gt; 然后对着一屏输出发呆。先把字段读懂，它才真正有用。&lt;/p&gt;
&lt;h3&gt;2.1 ps aux 的字段&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;ps aux
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出示例（节选）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;USER         PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root           1  0.0  0.3 168000 12400 ?        Ss   Nov10   0:32 /sbin/init
www-data    2451 12.5  4.1 985000 168000 ?       S    09:12   3:47 nginx: worker process
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐列解读：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;列&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;怎么看&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;USER&lt;/td&gt;
&lt;td&gt;进程属主&lt;/td&gt;
&lt;td&gt;排查权限问题先看它是谁在跑&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;PID&lt;/td&gt;
&lt;td&gt;进程编号&lt;/td&gt;
&lt;td&gt;后续 kill、查 /proc 都靠它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;%CPU&lt;/td&gt;
&lt;td&gt;CPU 占用率&lt;/td&gt;
&lt;td&gt;是进程生命周期内的平均值，不是瞬时值&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;%MEM&lt;/td&gt;
&lt;td&gt;占物理内存百分比&lt;/td&gt;
&lt;td&gt;配合 RSS 看实际占用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;VSZ&lt;/td&gt;
&lt;td&gt;虚拟内存大小（KB）&lt;/td&gt;
&lt;td&gt;申请了多少地址空间，参考意义有限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;RSS&lt;/td&gt;
&lt;td&gt;实际驻留物理内存（KB）&lt;/td&gt;
&lt;td&gt;判断内存大户看这个&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TTY&lt;/td&gt;
&lt;td&gt;所属终端&lt;/td&gt;
&lt;td&gt;&lt;code&gt;?&lt;/code&gt; 表示不依附终端（守护进程常见）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;STAT&lt;/td&gt;
&lt;td&gt;进程状态&lt;/td&gt;
&lt;td&gt;见后面第八节的状态码表&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;START&lt;/td&gt;
&lt;td&gt;启动时间&lt;/td&gt;
&lt;td&gt;判断进程是不是刚被拉起的&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TIME&lt;/td&gt;
&lt;td&gt;累计占用的 CPU 时间&lt;/td&gt;
&lt;td&gt;一直涨说明一直在烧 CPU&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;COMMAND&lt;/td&gt;
&lt;td&gt;启动命令&lt;/td&gt;
&lt;td&gt;带方括号的是内核线程&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;2.2 ps -ef 与 aux 的区别&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;ps -ef
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;ps -ef&lt;/code&gt; 是另一种风格（UNIX 风格），字段是 UID、PID、PPID、C（CPU 占用）、STIME、TTY、TIME、CMD。它最大的价值是&lt;strong&gt;直接给出 PPID&lt;/strong&gt;，追父子关系时比 aux 顺手。简单记：看资源占用用 &lt;code&gt;aux&lt;/code&gt;，看谁生了谁用 &lt;code&gt;-ef&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;2.3 按资源排序，快速找大户&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 按 CPU 占用从高到低，前 10 个
ps aux --sort=-%cpu | head -11

# 按内存占用从高到低，前 10 个
ps aux --sort=-%mem | head -11

# 只看某个用户的进程
ps -u www-data -f
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;2.4 pgrep：按名字查 PID&lt;/h3&gt;
&lt;p&gt;脚本里要拿某个程序的 PID，不要再用 &lt;code&gt;ps aux | grep xxx&lt;/code&gt; 这种容易误伤自己的老办法，用 &lt;code&gt;pgrep&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pgrep nginx            # 输出所有 nginx 进程的 PID
pgrep -a nginx         # 连完整命令行一起输出
pgrep -u root sshd     # 限定属主
pidof nginx            # 同类工具，只输出 PID 列表
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;三、top 深用：看实时动态&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;ps&lt;/code&gt; 是快照，&lt;code&gt;top&lt;/code&gt; 是直播。&lt;code&gt;top&lt;/code&gt; 里最有价值的是顶部汇总区，逐行读懂它，机器的健康状况一眼就有数。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;top - 10:23:41 up 12 days,  3:07,  2 users,  load average: 1.85, 1.20, 0.76
Tasks: 132 total,   1 running, 131 sleeping,   0 stopped,   0 zombie
%Cpu(s): 25.3 us,  6.1 sy,  0.0 ni, 67.2 id,  1.1 wa,  0.0 hi,  0.3 si,  0.0 st
MiB Mem :   3924.3 total,    412.5 free,   2210.8 used,   1301.0 buff/cache
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;load average&lt;/strong&gt;：最近 1、5、15 分钟的平均负载，即&quot;平均有多少进程在等 CPU 或在跑&quot;。经验值：持续超过 CPU 核数，说明 CPU 开始排队了。三个数从高到低回落，说明压力在缓解；反之在积压。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Tasks&lt;/strong&gt;：进程总数与各状态计数。重点扫一眼 zombie 是不是 0。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;%Cpu(s)&lt;/strong&gt;：这一行最容易被忽略，但信息量最大。&lt;code&gt;us&lt;/code&gt; 是用户态占用，&lt;code&gt;sy&lt;/code&gt; 是内核态占用，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;code&gt;id&lt;/code&gt; 是空闲率，&lt;code&gt;wa&lt;/code&gt; 是等 I/O 的时间占比——&lt;code&gt;wa&lt;/code&gt; 持续很高而 &lt;code&gt;us&lt;/code&gt; 不高，瓶颈在磁盘不在 CPU&amp;lt;/span&amp;gt;。&lt;code&gt;st&lt;/code&gt; 是虚拟化环境里被宿主机&quot;偷走&quot;的时间，云服务器上这个值高，说明邻居在抢资源或套餐超卖。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;进程列表区常用交互键：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;按键&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;P&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;按 %CPU 排序&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;M&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;按 %MEM 排序&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;k&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;结束选中的进程（会提示输 PID 和信号）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;r&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;对进程 renice 改优先级&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;展开每个 CPU 核的占用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;q&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;退出&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;只关心某个进程时，不必开着整个 top：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;top -p 2451            # 只盯一个 PID（多个用逗号分隔）
top -H -p 2451         # 展开到线程级别，看是哪条线程在忙
top -b -n 1 | head -20 # 批处理模式打一帧就走，适合写进脚本
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;htop&lt;/code&gt; 是更好看的增强版（彩色、可鼠标点、可滚动），Debian 上 &lt;code&gt;apt install htop&lt;/code&gt; 即可，日常巡检推荐用它，但救命时刻系统里不一定装了，&lt;code&gt;top&lt;/code&gt; 的基本功还是得有。&lt;/p&gt;
&lt;h2&gt;四、信号体系：结束进程的&quot;语言&quot;&lt;/h2&gt;
&lt;p&gt;进程之间、用户与进程之间，用**信号（signal）**通信。&lt;code&gt;kill&lt;/code&gt; 命令的本质不是&quot;杀&quot;，而是&quot;给进程发一个信号&quot;。理解信号，才能理解为什么有的进程一杀就死、有的纹丝不动。&lt;/p&gt;
&lt;h3&gt;4.1 常用信号表&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;编号&lt;/th&gt;
&lt;th&gt;名称&lt;/th&gt;
&lt;th&gt;默认动作&lt;/th&gt;
&lt;th&gt;语义与程序的典型反应&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;HUP&lt;/td&gt;
&lt;td&gt;终止&lt;/td&gt;
&lt;td&gt;原意是&quot;终端挂断&quot;。很多守护进程借它表示&quot;重读配置文件&quot;（如 nginx、sshd 收到 HUP 会重新加载配置而不退出）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;INT&lt;/td&gt;
&lt;td&gt;终止&lt;/td&gt;
&lt;td&gt;终端上按 Ctrl+C 发的就是它，程序可以捕获并做收尾&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;QUIT&lt;/td&gt;
&lt;td&gt;终止并生成 core dump&lt;/td&gt;
&lt;td&gt;Ctrl+\ 触发，比 INT 更&quot;硬&quot;，退出时留下内存快照供调试&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;9&lt;/td&gt;
&lt;td&gt;KILL&lt;/td&gt;
&lt;td&gt;立即终止&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;不可捕获、不可忽略&lt;/strong&gt;，内核直接回收进程，程序没有任何收尾机会&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;15&lt;/td&gt;
&lt;td&gt;TERM&lt;/td&gt;
&lt;td&gt;终止&lt;/td&gt;
&lt;td&gt;&lt;code&gt;kill&lt;/code&gt; 的默认信号。礼貌地通知&quot;请退出&quot;，程序可捕获后保存数据、释放资源再自行结束&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;18&lt;/td&gt;
&lt;td&gt;CONT&lt;/td&gt;
&lt;td&gt;继续&lt;/td&gt;
&lt;td&gt;把被 STOP 暂停的进程恢复运行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;19&lt;/td&gt;
&lt;td&gt;STOP&lt;/td&gt;
&lt;td&gt;暂停&lt;/td&gt;
&lt;td&gt;不可捕获，进程被冻结在原地（Ctrl+Z 发的是 TSTP，效果类似但可捕获）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;10/12&lt;/td&gt;
&lt;td&gt;USR1/USR2&lt;/td&gt;
&lt;td&gt;终止&lt;/td&gt;
&lt;td&gt;留给程序自定义的两个信号，不同软件约定不同，用前必须查该软件的文档&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;查看完整信号列表：&lt;code&gt;kill -l&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;4.2 为什么&quot;先 TERM 后 KILL&quot;是纪律&lt;/h3&gt;
&lt;p&gt;因为 TERM 给了程序体面收尾的机会：数据库刷盘、Web 服务处理完手头请求、程序删掉自己的临时文件和锁文件。而 KILL 是内核直接抹除，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;正在写盘的数据可能只写了一半，锁文件、PID 文件会残留，数据库下次启动要先做崩溃恢复，极端情况下数据直接损坏&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;标准操作顺序：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;kill &amp;lt;PID&amp;gt;          # 第一步：发 TERM（默认就是 15，可以不写 -15）
sleep 3             # 给它几秒钟收尾
ps -p &amp;lt;PID&amp;gt;         # 还在吗？
kill -9 &amp;lt;PID&amp;gt;       # 确实不肯退，最后才用 KILL
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
对数据库、消息队列这类有状态服务，&lt;code&gt;kill -9&lt;/code&gt; 应该是最后手段而不是顺手动作。生产环境里因为图省事直接 &lt;code&gt;-9&lt;/code&gt; 引发的数据问题，远比&quot;多等三秒&quot;代价大得多。
:::&lt;/p&gt;
&lt;p&gt;还有一个细节：信号是发给进程的，但&lt;strong&gt;只有进程的属主（或 root）能给它发信号&lt;/strong&gt;，普通用户对别人的进程执行 kill 会得到 &lt;code&gt;Operation not permitted&lt;/code&gt;，这是权限设计，不是命令坏了。&lt;/p&gt;
&lt;h2&gt;五、结束进程：kill、pkill、killall&lt;/h2&gt;
&lt;h3&gt;5.1 三个工具的差别&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;工具&lt;/th&gt;
&lt;th&gt;定位方式&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;th&gt;风险&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;kill&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;按 PID&lt;/td&gt;
&lt;td&gt;精确结束已确认的进程&lt;/td&gt;
&lt;td&gt;最低，前提是 PID 没认错&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;pkill&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;按进程名/模式匹配&lt;/td&gt;
&lt;td&gt;一批同名进程一起处理，如 &lt;code&gt;pkill -f worker&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;匹配范围靠模式，写宽了会误伤&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;killall&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;按进程名精确匹配&lt;/td&gt;
&lt;td&gt;结束某程序的全部实例，如 &lt;code&gt;killall nginx&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;名字对得上的全杀，不分会话不分用户（root 执行时）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;pre&gt;&lt;code&gt;kill 2451                      # 给单个 PID 发 TERM
kill -9 2451 2452              # 可以一次给多个 PID 发
pkill -TERM -u www-data php-fpm  # 给某用户的某类进程发 TERM
killall -w nginx               # -w 会等到进程全部退出才返回
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;5.2 下手之前的核查顺序&lt;/h3&gt;
&lt;p&gt;结束进程是不可逆操作，尤其在生产服务器上，养成固定的核查顺序：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;确认 PID 对应的到底是什么&lt;/strong&gt;：&lt;code&gt;ps -p &amp;lt;PID&amp;gt; -o pid,ppid,user,etime,cmd&lt;/code&gt;，把命令行看全，别凭印象。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;确认它是不是服务的主进程&lt;/strong&gt;：如果是 systemd 管的服务，优先用 &lt;code&gt;systemctl stop&lt;/code&gt;（原因见第九节），而不是 kill。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;先 TERM，等一等，复查&lt;/strong&gt;：&lt;code&gt;ps -p &amp;lt;PID&amp;gt;&lt;/code&gt; 还在，再考虑升级到 KILL。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;批量操作先 dry-run&lt;/strong&gt;：用 &lt;code&gt;pgrep -a &amp;lt;模式&amp;gt;&lt;/code&gt; 或 &lt;code&gt;pkill&lt;/code&gt; 前先把匹配列表打出来看一遍，确认没有误伤，再真正发信号。&lt;code&gt;pkill&lt;/code&gt; 本身不带预览，&lt;code&gt;pgrep -a&lt;/code&gt; 就是它的预览。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;code&gt;pkill -f&lt;/code&gt; 按完整命令行匹配时，模式写得太宽（比如只写 &lt;code&gt;java&lt;/code&gt;、&lt;code&gt;python&lt;/code&gt;）可能把无关进程甚至你自己的 shell 一起匹配进去&amp;lt;/span&amp;gt;。批量发信号前务必先用同样的模式跑一遍 &lt;code&gt;pgrep -af&lt;/code&gt; 核对清单。
:::&lt;/p&gt;
&lt;h2&gt;六、前后台作业：让进程在终端里&quot;排队&quot;&lt;/h2&gt;
&lt;p&gt;在 shell 里直接运行命令，它默认占据前台：终端被它霸占，你敲什么都进不去，直到它结束。作业控制就是把进程在前台、后台、暂停之间挪来挪去的一套机制。&lt;/p&gt;
&lt;h3&gt;6.1 基本操作&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;./long-task.sh &amp;amp;        # 命令末尾加 &amp;amp;，直接在后台启动，shell 立刻空出来
jobs                    # 查看当前 shell 的后台作业列表（带作业号 %1、%2）
fg %1                   # 把 1 号作业调回前台
bg %1                   # 让已暂停的 1 号作业在后台继续
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;前台正在跑的进程，可以这样处理：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;按 &lt;strong&gt;Ctrl+Z&lt;/strong&gt;：把当前前台进程&lt;strong&gt;暂停&lt;/strong&gt;（发送 TSTP 信号），shell 拿回来，进程冻在原地不继续跑；&lt;/li&gt;
&lt;li&gt;然后 &lt;code&gt;bg&lt;/code&gt; 让它在后台继续，或 &lt;code&gt;fg&lt;/code&gt; 拉回前台接着跑。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;注意区分：Ctrl+Z 只是暂停，不接着处理它，它就一直停在那儿——很多人以为 Ctrl+Z 是&quot;转入后台&quot;，其实少了 &lt;code&gt;bg&lt;/code&gt; 这一步，进程根本没在运行。&lt;/p&gt;
&lt;h3&gt;6.2 关掉终端进程也别死：nohup 与 disown&lt;/h3&gt;
&lt;p&gt;后台作业仍然挂在当前 shell 名下，&lt;strong&gt;退出登录（终端关闭）时，shell 会给它的作业发 HUP 信号&lt;/strong&gt;，进程通常就跟着死了。想让进程脱离终端存活：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;nohup ./long-task.sh &amp;gt; task.log 2&amp;gt;&amp;amp;1 &amp;amp;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;nohup&lt;/code&gt; 的作用是让进程忽略 HUP 信号；同时记得把输出重定向到文件，否则输出会写进当前目录的 &lt;code&gt;nohup.out&lt;/code&gt;，而且终端关闭后无处可写也可能出问题。&lt;/p&gt;
&lt;p&gt;已经在跑的进程忘了加 nohup，可以用 &lt;code&gt;disown&lt;/code&gt; 补救：先 Ctrl+Z 暂停，&lt;code&gt;bg&lt;/code&gt; 转后台，再 &lt;code&gt;disown -h %1&lt;/code&gt; 把它从 shell 的作业表里摘除，退出登录时就不会被连带发送 HUP。&lt;/p&gt;
&lt;p&gt;:::warning
nohup 只是&quot;关终端不死&quot;，它不是守护进程工具：没有自动重启、没有日志管理、开机也不会自启。长期运行的服务应该交给 systemd，见本系列的 &lt;a href=&quot;/posts/linux-systemd-services/&quot;&gt;systemd 服务管理篇&lt;/a&gt;。
:::&lt;/p&gt;
&lt;h2&gt;七、优先级：nice 与 renice&lt;/h2&gt;
&lt;p&gt;机器资源紧张时，可以通过 &lt;strong&gt;nice 值&lt;/strong&gt;影响进程的 CPU 调度优先级：nice 值越低，优先级越高，越优先被调度。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;取值范围：&lt;strong&gt;-20（最高优先级）到 19（最低优先级）&lt;/strong&gt;，默认是 0。&lt;/li&gt;
&lt;li&gt;方向记法：nice 值越&quot;不友好&quot;（数值越低）越抢 CPU；给进程调高 nice 值，就是让它&quot;礼让&quot;别人。&lt;/li&gt;
&lt;li&gt;权限：普通用户只能调高自己进程的 nice 值（降低优先级），&lt;strong&gt;调低 nice 值（提优先级）只有 root 可以&lt;/strong&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;# 以低优先级启动一个吃 CPU 的任务，让它别跟在线业务抢
nice -n 10 ./compress-backup.sh

# 对已经在跑的进程调整（renice 新值 PID）
renice 5 2451

# 在 top 里看 NI 列就是 nice 值，PR 是内核实际调度优先级
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;需要泼一盆冷水：nice 只影响 CPU 调度，对内存不够、磁盘 I/O 打满这类瓶颈基本无能为力。进程慢是因为在等磁盘时，把它的 nice 调到 -20 也不会快一分。先用 top 确认瓶颈在 CPU（&lt;code&gt;us/sy&lt;/code&gt; 高、&lt;code&gt;wa&lt;/code&gt; 低），nice 才是对症的工具；瓶颈定位的方法见&lt;a href=&quot;/posts/linux-performance-troubleshooting/&quot;&gt;性能排障篇&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;八、进程状态码：R/S/D/Z/T 各是什么意思&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;ps&lt;/code&gt; 的 STAT 列和 &lt;code&gt;top&lt;/code&gt; 的 S 列，第一个字母就是进程状态，这是判断进程&quot;活得怎么样&quot;的核心信息：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;状态&lt;/th&gt;
&lt;th&gt;名称&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;常见程度&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;R&lt;/td&gt;
&lt;td&gt;Running&lt;/td&gt;
&lt;td&gt;正在 CPU 上运行，或在运行队列里等 CPU&lt;/td&gt;
&lt;td&gt;正常&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;S&lt;/td&gt;
&lt;td&gt;Sleeping&lt;/td&gt;
&lt;td&gt;可中断的睡眠，在等某个事件（网络数据、用户输入、定时器）&lt;/td&gt;
&lt;td&gt;最常见，绝大多数进程平时都是 S&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;D&lt;/td&gt;
&lt;td&gt;Disk Sleep&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;不可中断的睡眠&lt;/strong&gt;，通常在等磁盘 I/O 完成&lt;/td&gt;
&lt;td&gt;少量短暂出现正常，大量长期存在是磁盘/存储故障信号&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;T&lt;/td&gt;
&lt;td&gt;Stopped&lt;/td&gt;
&lt;td&gt;被暂停（收到 STOP/TSTP，或被调试器断住）&lt;/td&gt;
&lt;td&gt;Ctrl+Z 后就是它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Z&lt;/td&gt;
&lt;td&gt;Zombie&lt;/td&gt;
&lt;td&gt;进程已退出，但父进程还没来回收它的退出状态，只剩一个空条目&lt;/td&gt;
&lt;td&gt;异常，见下文&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;STAT 里后续的附加字符也顺带认识一下：&lt;code&gt;&amp;lt;&lt;/code&gt; 高优先级、&lt;code&gt;N&lt;/code&gt; 低优先级、&lt;code&gt;s&lt;/code&gt; 会话首领、&lt;code&gt;l&lt;/code&gt; 多线程、&lt;code&gt;+&lt;/code&gt; 位于前台进程组。&lt;/p&gt;
&lt;h3&gt;8.1 D 状态：为什么杀不掉&lt;/h3&gt;
&lt;p&gt;D 状态的进程在内核里等 I/O 操作返回，这段等待&lt;strong&gt;不可中断&lt;/strong&gt;——连 KILL 信号都只能挂起等着，信号要等它从 D 状态出来才会被处理。所以你对一个 D 状态进程 &lt;code&gt;kill -9&lt;/code&gt;，它毫无反应，不是命令失效，而是它正卡在内核里出不来。&lt;/p&gt;
&lt;p&gt;D 状态的根因几乎都在存储侧：磁盘坏道、NFS/网络存储失联、存储驱动卡死。处理思路是修存储而不是跟进程较劲：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 找出所有 D 状态进程
ps aux | awk &apos;$8 ~ /^D/&apos;

# 看内核日志有没有 I/O 报错
dmesg | tail -30
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;偶尔一两个 D 状态一闪而过是正常的；如果持续出现一堆，优先怀疑磁盘健康和挂载的网络存储。&lt;/p&gt;
&lt;h3&gt;8.2 Z 状态：僵尸进程的处理&lt;/h3&gt;
&lt;p&gt;僵尸进程的真相是：&lt;strong&gt;子进程已经死了，但父进程还没有调用 wait() 来领取它的退出状态&lt;/strong&gt;，内核只能先在进程表里留一个空壳占位。僵尸不占 CPU、不占内存（只占一个 PID 名额），但它赖着不走，且你&lt;strong&gt;杀不掉它&lt;/strong&gt;——它已经死了，&lt;code&gt;kill&lt;/code&gt; 对一具&quot;尸体&quot;发信号毫无意义。&lt;/p&gt;
&lt;p&gt;正确处理对象是它的&lt;strong&gt;父进程&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 找到僵尸和它的父进程
ps aux | awk &apos;$8 ~ /^Z/&apos;
ps -o pid,ppid,cmd -p &amp;lt;僵尸的PPID&amp;gt;

# 方法一：给父进程发 SIGCHLD，提醒它去收尸（有些程序会响应）
kill -SIGCHLD &amp;lt;PPID&amp;gt;

# 方法二：父进程本身有问题、无响应时，只能重启或结束父进程
# 父进程一死，僵尸会被 PID 1（systemd）收养并自动回收
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要试图用 &lt;code&gt;kill -9&lt;/code&gt; 去&quot;杀&quot;僵尸进程，那只会让你误以为命令坏了&amp;lt;/span&amp;gt;。少量僵尸可以暂不处理，但如果僵尸持续堆积成百上千，说明父进程的逻辑有缺陷（生了子进程却不回收），根治办法是修父进程或重启它，否则 PID 名额耗尽后系统将无法创建新进程。
:::&lt;/p&gt;
&lt;h2&gt;九、进程与服务的关系：systemd 管的别硬杀&lt;/h2&gt;
&lt;p&gt;服务器上的长期进程，大多是 systemd 拉起的服务单元。用 &lt;code&gt;kill&lt;/code&gt; 直接结束这类进程，会出现两个问题：一是 systemd 发现进程&quot;意外死亡&quot;，按单元的重启策略&lt;strong&gt;立刻把它重新拉起来&lt;/strong&gt;，你以为杀掉了，它转眼又活了；二是绕过了单元定义的停止流程（ExecStop、依赖顺序、资源回收）。&lt;/p&gt;
&lt;p&gt;所以纪律是：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;凡是 &lt;code&gt;systemctl status&lt;/code&gt; 能查到的服务，启停一律走 &lt;code&gt;systemctl stop/start/restart&lt;/code&gt;，不要用 kill 硬来&amp;lt;/span&amp;gt;。判断某个 PID 归不归 systemd 管，一条命令即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 看进程属于哪个 systemd 单元
systemctl status &amp;lt;PID&amp;gt;

# 或从 /proc 的 cgroup 信息判断
cat /proc/&amp;lt;PID&amp;gt;/cgroup
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;服务管理的完整用法见本系列的 &lt;a href=&quot;/posts/linux-systemd-services/&quot;&gt;systemd 服务管理篇&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;十、排障实战&lt;/h2&gt;
&lt;h3&gt;10.1 CPU 100%：定位到具体进程与线程&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 第一步：top 看是谁在吃 CPU（按 P 排序）
top

# 第二步：锁定嫌疑进程的静态信息
ps -p &amp;lt;PID&amp;gt; -o pid,ppid,user,%cpu,%mem,etime,cmd

# 第三步：如果是一个多线程程序，展开看哪条线程在忙
top -H -p &amp;lt;PID&amp;gt;
ps -T -p &amp;lt;PID&amp;gt; -o pid,tid,%cpu,comm --sort=-%cpu | head
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;确认线程后，再结合程序自身的日志、监控去判断它是正常忙（突发流量）还是异常忙（死循环、重试风暴）。不要一看到 CPU 高就 kill，先分清敌我。&lt;/p&gt;
&lt;h3&gt;10.2 内存大户与 OOM 被杀&lt;/h3&gt;
&lt;p&gt;内存被吃满时，内核的 OOM Killer 会挑一个进程杀掉腾内存，被杀的往往不一定是吃内存的元凶。查法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 按内存排序找大户
ps aux --sort=-%mem | head -11

# 查系统日志里 OOM 的记录（谁被杀、当时内存全景）
journalctl -k | grep -i -A5 &quot;out of memory&quot;
dmesg | grep -i &quot;killed process&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;Killed process 2451 (java)&lt;/code&gt; 这样的记录会明确写出被杀进程。找到之后要回头分析：是内存泄漏慢慢涨上去的，还是业务量真的超出了机器规格，对策完全不同。整体的内存分析方法在&lt;a href=&quot;/posts/linux-performance-troubleshooting/&quot;&gt;性能排障篇&lt;/a&gt;里有更完整的展开。&lt;/p&gt;
&lt;h3&gt;10.3 进程杀了又活&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;kill&lt;/code&gt; 完一刷新，进程换了个新 PID 又出现了——这不是闹鬼，是有人在守护它。按这个顺序查：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 先看父进程是谁（PPID），顺藤摸瓜
ps -o pid,ppid,cmd -p &amp;lt;新PID&amp;gt;

# 2. 是不是 systemd 单元（最常见）
systemctl status &amp;lt;新PID&amp;gt;
# 是服务就用 systemctl stop，想彻底不让它起来再加 mask/disable

# 3. 是不是被 cron、其他守护脚本定时拉起
grep -r &quot;程序名&quot; /etc/cron* 2&amp;gt;/dev/null
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;常见来源就三类：systemd 的 &lt;code&gt;Restart=&lt;/code&gt; 策略、独立的监控/守护脚本、父进程的自动重生逻辑。找到守护者，从守护者下手，而不是反复杀进程本体。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;进程管理的三件套：&lt;strong&gt;看懂（ps/top）、发对信号、理清父子关系&lt;/strong&gt;，绝大多数问题都在这三件事里。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;ps aux&lt;/code&gt; 看资源，&lt;code&gt;ps -ef&lt;/code&gt; 看父子；&lt;code&gt;pgrep&lt;/code&gt; 是脚本里查 PID 的正道，批量操作前先用它预览。&lt;/li&gt;
&lt;li&gt;top 顶部汇总区要会读：load average 看排队，&lt;code&gt;%Cpu&lt;/code&gt; 行的 &lt;code&gt;wa&lt;/code&gt; 高说明瓶颈在磁盘。&lt;/li&gt;
&lt;li&gt;信号是&quot;语言&quot;不是&quot;武器&quot;：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;先 TERM 给程序收尾的机会，KILL 是最后手段&amp;lt;/span&amp;gt;，尤其对有状态服务。&lt;/li&gt;
&lt;li&gt;Ctrl+Z 只是暂停，&lt;code&gt;bg&lt;/code&gt; 才是转后台；长期任务用 nohup 防终端关闭，但正经服务要交给 systemd。&lt;/li&gt;
&lt;li&gt;nice 只治 CPU 排队，治不了 I/O 和内存瓶颈，别用错药。&lt;/li&gt;
&lt;li&gt;D 状态杀不掉是卡在内核 I/O，要修存储；Z 僵尸杀不掉是父进程没收尸，要找父进程。&lt;/li&gt;
&lt;li&gt;systemd 管的进程杀了又活是正常设计，启停走 &lt;code&gt;systemctl&lt;/code&gt;，不要跟守护机制对着干。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>服务器安全巡检清单</title><link>https://www.anexns.cloudns.org/posts/linux-security-checklist/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-security-checklist/</guid><description>定期给服务器做一次体检：异常登录与陌生账号、计划任务与自启项、开放端口清点、弱配置与过期软件，一份可以照着逐项打勾的巡检清单，附发现异常时的处置顺序。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;服务器被入侵这件事，最可怕的往往不是入侵本身，而是&lt;strong&gt;入侵了三个月你都不知道&lt;/strong&gt;。攻击者拿到一台机器后通常不会立刻搞破坏，而是先潜伏下来：留后门账号、埋计划任务、把你的机器当挖矿或跳板慢慢用。等你发现时，日志都轮转掉两轮了，根本查不清对方是什么时候、从哪进来的。&lt;/p&gt;
&lt;p&gt;防住这种事靠的不是某个神器，而是两个习惯：第一，把 SSH 入口先加固好（这是本系列《SSH 安全加固》的主题，没做的先去补）；第二，&lt;strong&gt;定期巡检&lt;/strong&gt;——拿着一份固定的清单，把账号、登录、计划任务、端口、软件逐项过一遍，和「正常状态」做对比。异常之所以能被发现，前提是你心里清楚正常长什么样。&lt;/p&gt;
&lt;p&gt;这篇就是那份清单本身。它是本系列的收官篇：前面几篇讲的是怎么把服务器装好、用好、监控好（监控的常态化做法见《服务器监控与告警》），这一篇讲怎么定期确认它&lt;strong&gt;还是你的&lt;/strong&gt;。所有命令都以 Debian 为例，可以直接复制执行，建议边看边在自己的机器上跑一遍，把输出存下来当第一份基线。&lt;/p&gt;
&lt;h2&gt;一、巡检的定位：本质是和基线做对比&lt;/h2&gt;
&lt;p&gt;巡检不是漫无目的地翻日志找坏人，而是&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;拿当前状态和已知正常的基线逐项对比，对不上的地方就是线索&amp;lt;/span&amp;gt;。没有基线，&lt;code&gt;ss -tlnp&lt;/code&gt; 打出一屏端口，你根本判断不出哪个是多余的；有了基线，多一个监听端口、多一个账号、多一条计划任务，一眼就能看出来。&lt;/p&gt;
&lt;p&gt;所以巡检分两步：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;阶段&lt;/th&gt;
&lt;th&gt;做什么&lt;/th&gt;
&lt;th&gt;产物&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;首次建基线&lt;/td&gt;
&lt;td&gt;服务器刚装好、确认干净时，把账号、端口、自启服务、计划任务、授权密钥全部导出存档&lt;/td&gt;
&lt;td&gt;一份 &lt;code&gt;baseline-日期.txt&lt;/code&gt;，存在本地或另一台机器上&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;定期巡检&lt;/td&gt;
&lt;td&gt;按本文清单逐项检查，把结果和基线 diff&lt;/td&gt;
&lt;td&gt;对不上的条目逐条核实，是自己改的就更新基线，来历不明的按异常处置&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;频率建议：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;频率&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;每周&lt;/td&gt;
&lt;td&gt;对外开放 Web 服务、流量较大的机器&lt;/td&gt;
&lt;td&gt;重点看登录线和网络线，十分钟能过完&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每月&lt;/td&gt;
&lt;td&gt;一般个人服务器&lt;/td&gt;
&lt;td&gt;全清单完整过一遍&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;事件触发&lt;/td&gt;
&lt;td&gt;改过防火墙、装过新软件、给别人开过临时账号之后&lt;/td&gt;
&lt;td&gt;针对性核对变更项，顺手更新基线&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
基线文件不要只存在被巡检的那台服务器上。机器真被拿下时，攻击者能改你的清单，你的「基线」也就不可信了。存到本地电脑、另一台服务器或私有 Git 仓库里。
:::&lt;/p&gt;
&lt;p&gt;下面五条线——账号、登录、持久化、网络、软件——就是清单的正文。每条线给出的命令，建议第一次运行时把输出完整保存，那就是你的基线。&lt;/p&gt;
&lt;h2&gt;二、账号线：谁能登进这台机器&lt;/h2&gt;
&lt;p&gt;账号是攻击者最爱留的后门：新建一个不起眼的用户、或者往现有用户的 &lt;code&gt;authorized_keys&lt;/code&gt; 里塞一把自己的密钥，就能长期自由进出，而且不触发任何登录失败告警。&lt;/p&gt;
&lt;h3&gt;1. 查 uid=0 的非 root 账号&lt;/h3&gt;
&lt;p&gt;Linux 里真正的超级用户看的不是名字，而是 uid。正常情况下只有 root 的 uid 是 0：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;awk -F: &apos;$3 == 0 {print $1}&apos; /etc/passwd
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;正常输出应该只有一行 &lt;code&gt;root&lt;/code&gt;。如果多出任何陌生名字，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;这意味着对方已经拥有等同于 root 的权限，按已被完全入侵处置&amp;lt;/span&amp;gt;，不要试图「删掉就完事」，直接跳到本文第八节的处置顺序。&lt;/p&gt;
&lt;h3&gt;2. 清点所有能登录的账号&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;awk -F: &apos;$7 !~ /(nologin|false)$/ {print $1, $3, $7}&apos; /etc/passwd
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这条列出所有登录 shell 不是 &lt;code&gt;nologin&lt;/code&gt;/&lt;code&gt;false&lt;/code&gt; 的账号（即理论上能登录的账号），连同 uid 和 shell 一起看。逐个核对：系统服务账号大多应该是 &lt;code&gt;nologin&lt;/code&gt;，如果某个服务账号挂着 &lt;code&gt;/bin/bash&lt;/code&gt;，要回忆是不是自己改的；个人账号只应有你自己和你明确开过的。&lt;/p&gt;
&lt;p&gt;再看一眼最近改动过的账号文件本身：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ls -l /etc/passwd /etc/shadow /etc/group
stat /etc/passwd
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;mtime&lt;/code&gt; 如果在你没有做账号操作的日期变动过，值得警惕。&lt;/p&gt;
&lt;h3&gt;3. 逐个核对 authorized_keys&lt;/h3&gt;
&lt;p&gt;密钥登录绕过了密码，塞一把陌生公钥进来非常隐蔽。每台机器、每个用户都要查：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cat /root/.ssh/authorized_keys
ls -la /home/*/.ssh/
cat /home/*/.ssh/authorized_keys
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;核对要点：每一行密钥你都要能说出它对应哪台设备（你的电脑、手机、跳板机）。密钥末尾的注释通常带设备名或邮箱，对不上的就是嫌疑。数量也要对——你记得放了 2 把，文件里有 3 行，就是出事了。&lt;/p&gt;
&lt;p&gt;:::warning
发现陌生密钥时，先别急着删了事。删密钥只是关门，对方可能还有别的入口（后门账号、计划任务、Web 后门）。正确做法是先按第八节留证，再统一清理。
:::&lt;/p&gt;
&lt;h3&gt;4. 空口令与弱口令检查&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 查空口令账号（需要 root 权限读 /etc/shadow）
awk -F: &apos;$2 == &quot;&quot; {print $1}&apos; /etc/shadow

# 查哪些账号设了密码（$2 是长串哈希即有密码，! 或 * 开头表示锁定/无密码登录）
awk -F: &apos;$2 !~ /^[!*]/ {print $1}&apos; /etc/shadow
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;空口令账号正常情况下应该一个都没有。设了密码的账号清单也要和基线对：某个本来只有密钥、没设密码的账号突然有了密码哈希，说明有人给它「补」了密码入口。&lt;/p&gt;
&lt;p&gt;弱口令没法用一条命令直接验出来，可行的办法是：确认密码登录是否已经关闭（&lt;code&gt;sshd_config&lt;/code&gt; 里 &lt;code&gt;PasswordAuthentication no&lt;/code&gt;，加固细节见《SSH 安全加固》）。只要密码登录关着，弱口令的风险就降了一大截；还开着密码登录的机器，至少要保证所有可登录账号都是强口令，并开 Fail2ban。&lt;/p&gt;
&lt;h2&gt;三、登录线：谁进来过&lt;/h2&gt;
&lt;p&gt;账号线看的是「门钥匙」，登录线看的是「进出记录」。重点不是失败记录（互联网上天天有人扫 SSH，失败几万条都正常），而是&lt;strong&gt;成功的那些&lt;/strong&gt;。&lt;/p&gt;
&lt;h3&gt;1. 看成功登录记录&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 最近的成功登录（用户、来源 IP、时间）
last -i | head -30

# 只筛 SSH 成功登录
grep &quot;Accepted&quot; /var/log/auth.log | tail -30

# 用 journald 的机器可以这样查
journalctl -u ssh --since &quot;30 days ago&quot; | grep &quot;Accepted&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐条核对来源 IP：应该是你自己的宽带、手机、公司网络或跳板机 IP。看到不认识的 IP 有 &lt;code&gt;Accepted&lt;/code&gt; 记录，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;说明对方已经拿着有效凭据进过门，这不是扫描，是入侵实锤&amp;lt;/span&amp;gt;，直接进第八节处置流程。&lt;/p&gt;
&lt;p&gt;另外注意登录时间：你睡觉的点、你在坐飞机的点出现的成功登录，同样可疑。&lt;/p&gt;
&lt;h3&gt;2. 看爆破量级有没有突变&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 失败登录记录
lastb -i | head -20

# 统计 auth.log 里失败次数最多的来源 IP
grep &quot;Failed password&quot; /var/log/auth.log | awk &apos;{print $(NF-3)}&apos; | sort | uniq -c | sort -nr | head
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;失败记录多本身不说明问题——公网机器一天被试几千次是常态。要看的是&lt;strong&gt;和基线比有没有量级突变&lt;/strong&gt;：平时一天几百次，突然某天几十万次，可能是有人在针对你跑字典；或者失败突然归零，也要想想是不是日志被清了（攻击者清日志是常规操作，&lt;code&gt;auth.log&lt;/code&gt; 异常短小、时间断档同样是线索）。&lt;/p&gt;
&lt;h3&gt;3. 顺手看当前在线会话&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;who
w
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;巡检当下如果有你不认识的在线会话，先别打草惊蛇，记下它的来源 IP 和终端，按第八节先留证再处置。&lt;/p&gt;
&lt;h2&gt;四、持久化线：对方靠什么「下次还能进来」&lt;/h2&gt;
&lt;p&gt;攻击者最怕的是你改密码、重启机器之后他就进不来了，所以一定会留持久化手段。这一线就是把所有「能让程序自动跑起来」的位置过一遍。&lt;/p&gt;
&lt;h3&gt;1. 所有用户的计划任务&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 逐个用户列 crontab
for u in $(cut -d: -f1 /etc/passwd); do
  echo &quot;== $u ==&quot;
  crontab -l -u &quot;$u&quot; 2&amp;gt;/dev/null
done

# 系统级计划任务目录
ls -la /etc/cron.d/ /etc/cron.daily/ /etc/cron.hourly/
cat /etc/crontab
ls -la /var/spool/cron/crontabs/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重点盯三类条目：指向 &lt;code&gt;/tmp&lt;/code&gt;、&lt;code&gt;/dev/shm&lt;/code&gt;、&lt;code&gt;/var/tmp&lt;/code&gt; 里脚本的；用 &lt;code&gt;curl&lt;/code&gt; 或 &lt;code&gt;wget&lt;/code&gt; 下载东西再执行的；base64 编码过、看不出原文的。正常的计划任务你都应该能说出用途，说不出的逐条查。&lt;/p&gt;
&lt;h3&gt;2. systemd 自启服务清单&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;systemctl list-unit-files --state=enabled
ls -la /etc/systemd/system/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;和基线对比：多出来的自启服务重点排查，尤其是服务文件在 &lt;code&gt;/etc/systemd/system/&lt;/code&gt; 下、且 &lt;code&gt;ExecStart&lt;/code&gt; 指向用户目录或临时目录的。自己写的服务（比如本系列前面讲的监控、自启脚本）心里有数即可，陌生的立刻查它启动的是什么二进制。&lt;/p&gt;
&lt;p&gt;顺带看一眼有没有异常的 timer：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl list-timers --all
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;3. Shell 启动文件的改动&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;~/.bashrc&lt;/code&gt;、&lt;code&gt;/etc/profile&lt;/code&gt;、&lt;code&gt;/etc/bash.bashrc&lt;/code&gt; 会在登录时自动执行，是藏命令的好地方：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ls -l ~/.bashrc /etc/profile /etc/bash.bashrc
grep -n &quot;curl\|wget\|nc \|bash -i&quot; ~/.bashrc /etc/profile /etc/bash.bashrc
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;文件修改时间对不上你的操作记录、或里面出现下载执行、反弹 shell 类命令，就是实锤。没有基线时也可以和同版本 Debian 的默认文件对比着看。&lt;/p&gt;
&lt;h3&gt;4. 临时目录里的可执行文件&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;find /tmp /dev/shm /var/tmp -type f -executable 2&amp;gt;/dev/null
ls -la /tmp /dev/shm
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;/tmp&lt;/code&gt; 和 &lt;code&gt;/dev/shm&lt;/code&gt; 是人人可写的目录，挖矿木马、扫描器最爱落脚在这里。正常情况下这里不应该有长期驻留的可执行文件。发现不认识的二进制，先记下路径和时间，不要直接运行它「看看是什么」。&lt;/p&gt;
&lt;h3&gt;5. 其他几个藏身点&lt;/h3&gt;
&lt;p&gt;持久化不止计划任务和自启服务，下面三个位置改动少、隐蔽性高，巡检时顺手扫一眼：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# sudoers 附加规则：有没有给某个账号开了免密 sudo
ls -la /etc/sudoers.d/
grep -r &quot;NOPASSWD&quot; /etc/sudoers /etc/sudoers.d/ 2&amp;gt;/dev/null

# ld.so.preload：正常系统这个文件应该不存在或为空
ls -l /etc/ld.so.preload &amp;amp;&amp;amp; cat /etc/ld.so.preload

# sshd 配置有没有被改过授权文件路径
grep -E &quot;AuthorizedKeysFile|PermitRootLogin|PasswordAuthentication&quot; /etc/ssh/sshd_config /etc/ssh/sshd_config.d/*.conf 2&amp;gt;/dev/null
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;/etc/sudoers.d/&lt;/code&gt; 里多出陌生文件、某个普通账号被授了 &lt;code&gt;NOPASSWD: ALL&lt;/code&gt;，等于对方给自己留了张随时提权的通行证；&lt;code&gt;/etc/ld.so.preload&lt;/code&gt; 里挂着来历不明的 &lt;code&gt;.so&lt;/code&gt;，是劫持系统命令输出的经典手法，会让 &lt;code&gt;ps&lt;/code&gt;、&lt;code&gt;ss&lt;/code&gt;、&lt;code&gt;ls&lt;/code&gt; 这些你巡检依赖的命令集体说谎——真到了这一步，连巡检结果本身都不可信，这也是为什么第八节强调留证要用多角度交叉验证、处置要重装优先。&lt;/p&gt;
&lt;h2&gt;五、网络线：开了哪些门、连着哪些人&lt;/h2&gt;
&lt;h3&gt;1. 开放端口与基线逐项对&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;ss -tlnp
ss -ulnp
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把监听端口清单和基线逐项比对，每个端口都要能对应到一个你知道的服务：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比结果&lt;/th&gt;
&lt;th&gt;判断&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;和基线一致&lt;/td&gt;
&lt;td&gt;正常，打勾&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;基线没有、本次新出现，且是你最近装的服务&lt;/td&gt;
&lt;td&gt;确认用途后更新基线&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;基线没有、来历不明&lt;/td&gt;
&lt;td&gt;高度可疑，查监听进程的完整路径和启动方式&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;基线有、本次消失&lt;/td&gt;
&lt;td&gt;服务挂了或被人关了，同样要查&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;查某个监听进程的底细：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# ss 输出里能看到进程名和 pid，再顺藤摸瓜
ls -l /proc/&amp;lt;pid&amp;gt;/exe
cat /proc/&amp;lt;pid&amp;gt;/cmdline | tr &apos;\0&apos; &apos; &apos;
systemctl status &amp;lt;pid&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;多余端口的处理原则：用不上的服务直接卸载或停用，只在本机用的端口绑到 &lt;code&gt;127.0.0.1&lt;/code&gt;，必须对外的端口用防火墙限制来源。关端口的动作本身在《防火墙》一篇里讲过，巡检这里只负责「发现」。&lt;/p&gt;
&lt;h3&gt;2. 查异常外连&lt;/h3&gt;
&lt;p&gt;服务器主动连出去的连接同样重要——挖矿要连矿池、被控要连控制端、数据外泄要有目的地：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 当前所有已建立的 TCP 连接及对应进程
ss -tnp state established

# 按远端 IP 汇总看看有没有陌生面孔
ss -tn state established | awk &apos;{print $5}&apos; | cut -d: -f1 | sort | uniq -c | sort -nr
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐个核对远端 IP：系统更新源、你配置的上游服务、监控上报地址应该是大头。看到连向陌生 IP 的高位端口、或者某个进程长期挂着一条你不认识的连接，用 &lt;code&gt;ls -l /proc/&amp;lt;pid&amp;gt;/exe&lt;/code&gt; 查清是哪个程序在连。注意巡检只能抓到当下活跃的连接，间歇性回连的木马可能刚好不在线，所以这一线要和持久化线结合看：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;端口对基线、连接看进程、进程追启动方式，三条对上了才算查清&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h2&gt;六、软件线：补丁欠了多少、有没有来历不明的东西&lt;/h2&gt;
&lt;h3&gt;1. 待更新的安全补丁&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;apt update
apt list --upgradable 2&amp;gt;/dev/null | grep -i security
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Debian 的安全更新走 &lt;code&gt;security.debian.org&lt;/code&gt; 源，&lt;code&gt;apt list --upgradable&lt;/code&gt; 输出里带 &lt;code&gt;Debian-Security&lt;/code&gt; 字样的就是安全补丁。看的方法：重点盯 OpenSSH、OpenSSL、内核（linux-image）、sudo、polkit 这类高权限或对外组件的安全更新，欠得越久，暴露在已知漏洞下的时间越长——很多入侵用的根本不是 0day，就是你没打的公开补丁。&lt;/p&gt;
&lt;p&gt;顺便看一眼待重启状态：内核更新后没重启，等于补丁没生效：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ls /var/run/reboot-required 2&amp;gt;/dev/null &amp;amp;&amp;amp; echo &quot;需要重启&quot;
uname -r
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拿 &lt;code&gt;uname -r&lt;/code&gt; 和 &lt;code&gt;apt list --upgradable&lt;/code&gt; 里最新的 linux-image 版本对一下就知道。&lt;/p&gt;
&lt;h3&gt;2. 要不要开自动安全更新&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;unattended-upgrades&lt;/code&gt; 可以让系统自动装安全补丁：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apt install unattended-upgrades
dpkg-reconfigure -plow unattended-upgrades
cat /etc/apt/apt.conf.d/20auto-upgrades
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;取舍很明确：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;选择&lt;/th&gt;
&lt;th&gt;适合&lt;/th&gt;
&lt;th&gt;代价&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;开，只自动装安全更新&lt;/td&gt;
&lt;td&gt;个人服务器、怕忘打补丁&lt;/td&gt;
&lt;td&gt;极小概率某个更新需要人工善后；内核更新后仍要手动重启&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;不开，手动更新&lt;/td&gt;
&lt;td&gt;对变更时机敏感的生产机&lt;/td&gt;
&lt;td&gt;全靠你记得，忘一个月就多暴露一个月&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;个人机器我的建议是开。自动更新管「装」，巡检管「核对有没有装上、有没有欠账」，两者不冲突。&lt;/p&gt;
&lt;h3&gt;3. 来源不明的软件&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# /usr/local 下的东西都是绕过包管理器装的，逐个要能说出来历
ls -la /usr/local/bin/ /usr/local/sbin/

# 查某个文件属于哪个包，查不到就是手动放进去的
dpkg -S /usr/local/bin/xxx

# 列出最近 30 天新装的软件包
grep &quot; install &quot; /var/log/dpkg.log | tail -30
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;自己编译装的、脚本一键装的心里有数；说不出来历的二进制，结合它的出现时间和持久化线的结果一起判断。还有一类要留心：名字长得像系统命令的冒牌货，比如在 &lt;code&gt;/tmp&lt;/code&gt; 或用户目录里出现名为 &lt;code&gt;sshd&lt;/code&gt;、&lt;code&gt;systemd&lt;/code&gt; 的程序——真身都在固定路径，出现在别处就是伪装。&lt;/p&gt;
&lt;h2&gt;七、Web 与 Docker 面：一句带过&lt;/h2&gt;
&lt;p&gt;如果这台机器上跑了 Web 服务或 Docker，巡检时多看两眼：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;管理面板别裸奔公网&lt;/strong&gt;：数据库管理、Docker 面板、监控面板这类后台，要么只绑 &lt;code&gt;127.0.0.1&lt;/code&gt; 走 SSH 隧道访问，要么至少加一层登录认证和 IP 白名单。监控面板的暴露问题在《服务器监控与告警》里也提过。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Docker 特权容器&lt;/strong&gt;：&lt;code&gt;docker ps&lt;/code&gt; 过一遍在跑的容器，再用 &lt;code&gt;docker inspect&lt;/code&gt; 看有没有 &lt;code&gt;--privileged&lt;/code&gt;、挂载了 &lt;code&gt;/var/run/docker.sock&lt;/code&gt; 或宿主机根目录的容器——这类容器一旦被攻破等于宿主机沦陷，配置原则在 &lt;a href=&quot;/posts/docker-security-resources/&quot;&gt;Docker 安全与资源限制实战&lt;/a&gt; 里讲过，巡检时对照着核查一遍即可。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这一节只做提醒，不展开，因为它们各自有专篇；巡检清单里给它们留两个勾就行。&lt;/p&gt;
&lt;h2&gt;八、发现异常的处置顺序&lt;/h2&gt;
&lt;p&gt;前面任何一条线查出实锤异常（陌生 uid=0 账号、陌生 IP 成功登录、来历不明的持久化条目），都不要慌着删东西。按下面的顺序来：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;先留证&lt;/strong&gt;。把当前状态快照下来再说：&lt;code&gt;last&lt;/code&gt;、&lt;code&gt;ss -tlnp&lt;/code&gt;、&lt;code&gt;ps aux&lt;/code&gt;、可疑文件的路径与哈希、相关日志，先复制到另一台机器或本地保存。云厂商控制台有快照功能的，整机打一个快照。手一快先删文件、重启机器，证据链就断了，之后你永远不知道对方还留了什么。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;断网隔离&lt;/strong&gt;。在云厂商安全组/防火墙层面把这台机器的出入流量掐掉（保留你自己的管理通道，或直接控制台操作），防止它继续对外作恶或被远程操控。不要只在机器内部关服务——你不确定对方的权限深度，机器内的操作都可能被干扰。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;找入口&lt;/strong&gt;。对照留下的日志和时间线，判断对方最初是怎么进来的：弱口令爆破、某个未打补丁的服务、泄露的密钥，还是某个 Web 应用漏洞。找不到入口就贸然恢复，等于把门留着请他再来一次。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;重装，而不是清马&lt;/strong&gt;。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;已经确认被入侵的系统，靠杀进程、删文件「清理干净」是不现实的&amp;lt;/span&amp;gt;——你无法证明没有漏掉的后门。正确做法是：数据（网站文件、数据库、配置）经过检查后导出，在一台全新建好的系统上恢复，旧系统整盘丢弃。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;轮换全部凭据&lt;/strong&gt;。这台机器上出现过的所有密码、SSH 密钥、API Token、数据库口令，一律当作已泄露处理，全部更换；其他机器上如果复用了同一套凭据，跟着一起换。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;复盘补漏&lt;/strong&gt;。按找到的入口补上对应的防线——该关的密码登录关掉、该打的补丁打上、Fail2ban 和监控告警补齐（参见 &lt;a href=&quot;/posts/linux-ssh-hardening/&quot;&gt;SSH 安全加固&lt;/a&gt; 与 &lt;a href=&quot;/posts/linux-server-monitoring/&quot;&gt;服务器监控与告警&lt;/a&gt;），然后重新建一份基线。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::warning
处置期间不要在这台被入侵的机器上登录其他重要服务（邮箱、云厂商控制台、其他服务器）。如果对方在机器上留了键盘记录或凭据窃取程序，你等于把新钥匙也送了出去。所有善后操作用一台干净的设备做。
:::&lt;/p&gt;
&lt;h2&gt;九、把巡检做成习惯&lt;/h2&gt;
&lt;p&gt;清单的价值在于重复执行，三件事能帮你坚持下去：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;清单存成文档&lt;/strong&gt;。把本文的命令按你的机器实际情况删减定制，存成一份自己的 &lt;code&gt;checklist.md&lt;/code&gt;，每台机器一份基线文件放旁边。每次巡检照着从上往下打勾，不用临时回忆「该查啥来着」。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;固定节奏&lt;/strong&gt;。每月挑个固定日子（比如发工资日、每月 1 号）过一遍全清单，每周有空时快速扫一眼登录线和网络线。一次全清单熟练之后二十分钟左右，比事后救火便宜得多。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;结果留档对比&lt;/strong&gt;。每次巡检的输出按日期存档，下次直接和上次 diff。变化点自动浮现，你只需要对变化点做判断——这正是第一节说的基线对比，留档就是在给基线续命。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;能自动化的部分（端口清单、账号清单、自启服务清单）可以写成脚本定时导出，但&lt;strong&gt;不要让脚本替代你的眼睛&lt;/strong&gt;：脚本负责收集，最后那一眼对比和判断必须是人来看。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;巡检的本质是和基线做对比：先在干净时导出账号、端口、自启、计划任务、密钥五份基线，之后每次巡检对不上的地方就是线索。&lt;/li&gt;
&lt;li&gt;五条线分工明确：账号线查钥匙、登录线查成功记录（失败记录只看量级突变）、持久化线查后门、自启与计划任务全过一遍、网络线端口对基线＋外连看进程、软件线盯安全补丁欠账和来历不明的二进制。&lt;/li&gt;
&lt;li&gt;查出实锤异常时按顺序处置：留证 → 断网隔离 → 找入口 → 重装恢复 → 轮换全部凭据 → 复盘补漏，其中&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;重装优先于清马&amp;lt;/span&amp;gt;是底线。&lt;/li&gt;
&lt;li&gt;频率上，对外服务多的机器每周、一般机器每月，变更之后追加一次针对性核对；结果按日期留档，下次直接 diff。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;至此 Linux 运维系列的十篇就完整了：从装机初始化、SSH 加固、防火墙、systemd、磁盘、日志、监控、备份、排障，一直到这篇安全巡检——一套自己动手把服务器管起来的完整路径。愿你的每台机器，巡检永远只是走个过场。&lt;/p&gt;
</content:encoded></item><item><title>新服务器初始化全流程</title><link>https://www.anexns.cloudns.org/posts/linux-server-init/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-server-init/</guid><description>一台新 Linux 服务器到手先干什么：系统更新、时区与语言、普通用户与 sudo、必备工具、Swap 与主机名，一套标准初始化流程走完，后面装什么都省心。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;一台裸机，离「能放心用」还差几步&lt;/h2&gt;
&lt;p&gt;不管是云厂商开的 VPS，还是自己装的物理机，一台刚交付的 Linux 服务器通常都是「能开机、能 SSH 登录」的状态，但离「能放心往上部署服务」还差不少：软件包是几个月前的版本、时区在 UTC、系统里只有 root 一个账号、连 curl 都没装。很多人拿到机器就急着装 Docker、装面板，结果后面遇到证书报错、日志时间对不上、磁盘爆了没工具查，根源全在初始化这一步没做。&lt;/p&gt;
&lt;p&gt;本篇是 Linux 运维系列的第一篇，主线就是一件事：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;把一台裸机拉到一个已知、干净、可复现的标准起点&amp;lt;/span&amp;gt;。全程以 Debian 12 为主线操作，Ubuntu 的命令基本通用，差异处会单独点一句。做完这篇的十步，后面装什么服务都省心。&lt;/p&gt;
&lt;p&gt;先看一下差距清单，心里有个全貌：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;检查项&lt;/th&gt;
&lt;th&gt;裸机常见状态&lt;/th&gt;
&lt;th&gt;初始化后目标&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;软件包版本&lt;/td&gt;
&lt;td&gt;镜像制作时的旧版本，可能带已知漏洞&lt;/td&gt;
&lt;td&gt;全部更新到源里最新，内核为最新版&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;系统时间&lt;/td&gt;
&lt;td&gt;UTC 时区、可能没开同步&lt;/td&gt;
&lt;td&gt;Asia/Shanghai 且自动同步&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;语言环境&lt;/td&gt;
&lt;td&gt;POSIX/C locale，中文显示乱码或方框&lt;/td&gt;
&lt;td&gt;UTF-8 locale&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;登录账号&lt;/td&gt;
&lt;td&gt;只有 root&lt;/td&gt;
&lt;td&gt;普通用户 + sudo，日常不用 root&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;主机名&lt;/td&gt;
&lt;td&gt;厂商随机字符串，如 vm-3847&lt;/td&gt;
&lt;td&gt;有含义的名字，如 web-01&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;基础工具&lt;/td&gt;
&lt;td&gt;只有最精简命令集&lt;/td&gt;
&lt;td&gt;常用工具齐全，随手可用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Swap&lt;/td&gt;
&lt;td&gt;云镜像常无 Swap&lt;/td&gt;
&lt;td&gt;小内存机器补上 Swap 并持久化&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;第一步：先把系统更新干净&lt;/h2&gt;
&lt;p&gt;新机器的第一件事永远是更新。这不只是为了「用新版」，更重要的是镜像制作到交付之间可能隔了几个月，这期间修掉的安全漏洞全在更新里。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apt update
apt upgrade -y
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两条命令分工不同：&lt;code&gt;apt update&lt;/code&gt; 只是把软件源的包列表拉到本地，&lt;code&gt;apt upgrade&lt;/code&gt; 才真正下载并升级。只敲 upgrade 不先 update，装的还是旧列表里的版本。&lt;/p&gt;
&lt;p&gt;再补一个容易混淆的点：&lt;code&gt;apt upgrade&lt;/code&gt; 和 &lt;code&gt;apt full-upgrade&lt;/code&gt;（老写法叫 dist-upgrade）不完全一样。upgrade 比较保守，遇到需要卸载旧包或新增依赖包才能完成的升级时会把包「保留」住不升；full-upgrade 则允许增删依赖，把系统完整带到最新状态。初始化阶段系统里还没装业务服务，用 full-upgrade 更彻底：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apt full-upgrade -y
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;升级完成后顺手清掉已经用不上的旧依赖和旧内核（保留当前运行内核，apt 会自动处理，不会误删正在用的那个）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apt autoremove -y
apt clean
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;autoremove&lt;/code&gt; 卸载不再被任何包依赖的孤儿包，&lt;code&gt;apt clean&lt;/code&gt; 清空本地下载缓存的 .deb 文件。新机器上这两步省不了多少空间，但养成习惯后，老机器上能避免 /var 分区被缓存和旧内核慢慢吃满。&lt;/p&gt;
&lt;h3&gt;要不要换软件源&lt;/h3&gt;
&lt;p&gt;Debian 官方源在全球有镜像网络，一般不需要折腾。是否换源按这个标准判断：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;情况&lt;/th&gt;
&lt;th&gt;建议&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;海外机房的服务器&lt;/td&gt;
&lt;td&gt;用默认官方源，通常速度足够&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;国内机房、官方源 update 明显缓慢（几十 KB/s）&lt;/td&gt;
&lt;td&gt;换国内镜像源，如清华、阿里云镜像站&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;云厂商（阿里云、腾讯云等）自家机器&lt;/td&gt;
&lt;td&gt;优先用厂商内网镜像源，快且不计流量&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;换源就是改 &lt;code&gt;/etc/apt/sources.list&lt;/code&gt;（Debian 12 也可能用 &lt;code&gt;/etc/apt/sources.list.d/debian.sources&lt;/code&gt; 这个新格式文件），把域名替换成镜像站域名即可，发行版代号（bookworm）和组件（main contrib non-free non-free-firmware）不要动。换完必须再跑一次 &lt;code&gt;apt update&lt;/code&gt; 确认没有报错。&lt;/p&gt;
&lt;h3&gt;更新后重启并确认内核&lt;/h3&gt;
&lt;p&gt;如果升级里包含内核（包名形如 linux-image-*），需要重启才能生效：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;reboot
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重新连上后确认实际运行的内核版本：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;uname -r
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出类似 &lt;code&gt;6.1.0-38-amd64&lt;/code&gt;。再和已安装的最新内核对比一下，确认跑的是新内核而不是旧的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;dpkg -l | grep linux-image
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;apt upgrade&lt;/code&gt; 过程中&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要断开 SSH、不要关机&amp;lt;/span&amp;gt;，尤其升级到一半涉及 libc、内核这类核心包时强行中断，可能把包管理状态搞坏，后续修复非常麻烦。网络不稳时先用 &lt;code&gt;tmux&lt;/code&gt; 或 &lt;code&gt;screen&lt;/code&gt; 开个会话再升级，断线了任务也不会死。
:::&lt;/p&gt;
&lt;h2&gt;第二步：时区与时间同步&lt;/h2&gt;
&lt;p&gt;时间不对是一类特别阴险的问题：HTTPS 证书校验会因为「证书尚未生效」直接失败，日志时间戳全乱、排障时对不上线，定时任务在错误的时间触发。所以初始化时必须把时区和同步一起做对。&lt;/p&gt;
&lt;p&gt;查看当前时间状态：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;timedatectl
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重点看三行：&lt;code&gt;Local time&lt;/code&gt; 是本地时间，&lt;code&gt;Time zone&lt;/code&gt; 是当前时区，&lt;code&gt;System clock synchronized&lt;/code&gt; 表示是否已同步成功。&lt;/p&gt;
&lt;p&gt;设置时区为上海：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;timedatectl set-timezone Asia/Shanghai
timedatectl
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Debian 默认带 &lt;code&gt;systemd-timesyncd&lt;/code&gt; 做时间同步，一般装完系统就自动在跑。确认它的状态：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;timedatectl timesync-status
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;能看到 &lt;code&gt;Server:&lt;/code&gt; 有 NTP 服务器地址、&lt;code&gt;Packet count&lt;/code&gt; 大于 0，就说明同步正常。如果 timesyncd 没在运行，手动启用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl enable --now systemd-timesyncd
timedatectl set-ntp true
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;做完后 &lt;code&gt;date&lt;/code&gt; 命令输出的时间应该就是北京时间。记住：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;时间同步不是可选项，是所有服务能正常工作的前提&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;有人习惯服务器统一用 UTC，理由是跨国业务对时间方便。这没有对错，但对个人运维和国内业务，本地时区更直观：看日志不用在脑子里减 8 小时，定时任务想让它凌晨 3 点跑就写 3 点。关键不是选哪个，而是全队机器统一、且你自己清楚选的是哪个。云厂商的镜像默认几乎都是 UTC，新机器到手先查一眼时区，别默认它已经是北京时间。&lt;/p&gt;
&lt;p&gt;还要区分两个概念：时区决定「显示几点」，时间同步决定「走得准不准」。只改时区不同步，时钟漂移几个月后能差出几分钟，证书和令牌照样出问题；只同步不改时区，时间是准的但显示的是 UTC。两件事都要做，才算完整。&lt;/p&gt;
&lt;h2&gt;第三步：语言与 locale&lt;/h2&gt;
&lt;p&gt;locale 决定了程序输出用什么语言、什么字符编码。精简镜像常默认 &lt;code&gt;POSIX&lt;/code&gt; 或 &lt;code&gt;C&lt;/code&gt; locale，后果是中文文件名、中文日志在终端里显示成乱码或问号，部分程序（比如 PostgreSQL 初始化）还会直接拒绝在非 UTF-8 环境下工作。&lt;/p&gt;
&lt;p&gt;先看现状：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;locale
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果 &lt;code&gt;LANG&lt;/code&gt; 为空或显示 &lt;code&gt;C&lt;/code&gt;，就需要设置。Debian 上生成并启用一个 UTF-8 locale：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apt install -y locales
dpkg-reconfigure locales
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;在弹出的界面里勾选 &lt;code&gt;en_US.UTF-8&lt;/code&gt;（或 &lt;code&gt;zh_CN.UTF-8&lt;/code&gt;），下一步选它为默认。也可以不用界面，纯命令完成：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sed -i &apos;s/^# *en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/&apos; /etc/locale.gen
locale-gen
update-locale LANG=en_US.UTF-8
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重新登录 SSH 后再跑 &lt;code&gt;locale&lt;/code&gt;，&lt;code&gt;LANG=en_US.UTF-8&lt;/code&gt; 即生效。这里选英文还是中文 locale 看个人习惯，关键是编码必须是 UTF-8；服务器环境一般推荐英文 locale，报错信息用英文更方便检索。&lt;/p&gt;
&lt;p&gt;乱码的根源一句话说清：终端、系统 locale、文件本身的编码三者不一致，就会乱码。现在编辑器和文件默认都是 UTF-8，所以只要把系统 locale 这一环补上 UTF-8，链条就通了。另一个常见坑是：locale 没装好时执行某些命令会刷一串 &lt;code&gt;perl: warning: Setting locale failed&lt;/code&gt; 的警告，看着吓人，本质就是系统找不到你环境变量里指定的 locale，回到这一步把对应 locale 生成出来即可消除。&lt;/p&gt;
&lt;h2&gt;第四步：建普通用户，配 sudo&lt;/h2&gt;
&lt;p&gt;裸机默认只有 root。日常操作全部用 root 有两个问题：一是权限没有任何约束，手滑一条命令就能删掉系统关键文件；二是所有操作都记在 root 名下，出事了分不清是谁干的。&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;用 root 执行 &lt;code&gt;rm&lt;/code&gt;、&lt;code&gt;chmod&lt;/code&gt;、&lt;code&gt;dd&lt;/code&gt; 这类命令时打错路径，没有任何拦截，删错就是删错&amp;lt;/span&amp;gt;，这也是老运维都坚持「日常普通用户、提权走 sudo」的根本原因：sudo 至少让你在敲回车前多想一秒。
:::&lt;/p&gt;
&lt;p&gt;创建普通用户（以用户名 &lt;code&gt;dev&lt;/code&gt; 为例，下文按需替换）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;adduser dev
usermod -aG sudo dev
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;adduser&lt;/code&gt; 会交互式地让你设密码并填写用户信息，一路回车即可。&lt;code&gt;usermod -aG sudo dev&lt;/code&gt; 把用户加入 sudo 组，注意 &lt;code&gt;-a&lt;/code&gt; 表示追加，不能漏，漏了会把用户从其他组里踢出去。&lt;/p&gt;
&lt;p&gt;验证一下，切到新用户试跑 sudo：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;su - dev
sudo whoami
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第一次用 sudo 会提示输入该用户自己的密码，输出 &lt;code&gt;root&lt;/code&gt; 说明提权链路通了。之后日常就用这个普通账号登录，需要管理员权限时在命令前加 &lt;code&gt;sudo&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;root 和 sudo 的分工，记住这张表就够了：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;用哪个&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;日常登录、看日志、改自己目录的文件&lt;/td&gt;
&lt;td&gt;普通用户&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;装软件、改系统配置、重启服务&lt;/td&gt;
&lt;td&gt;普通用户 + &lt;code&gt;sudo&lt;/code&gt; 临时提权&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;紧急救援、sudo 本身坏了&lt;/td&gt;
&lt;td&gt;root（本地或厂商控制台登录）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;长期跑脚本、定时任务&lt;/td&gt;
&lt;td&gt;单独建专用用户，别混用个人账号&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;root 账号本身不要删、密码设强一点留着应急，但日常别拿它干活。&lt;/p&gt;
&lt;p&gt;建完用户记得马上用新账号实际登录一次 SSH，确认密码正确、能 sudo，再退出 root 会话。不要等到把 root 远程登录关掉之后，才发现新账号进不去——那是下一篇 SSH 加固里最经典的翻车姿势，提前在这里把账号可用性验掉。多人共用一台机器时，一人一个账号，不要共用同一个账号再共享密码，谁做过什么操作在 auth 日志里才能对得上人。&lt;/p&gt;
&lt;h2&gt;第五步：主机名与 hosts&lt;/h2&gt;
&lt;p&gt;厂商给的主机名通常是随机字符串，机器一多根本分不清谁是谁。改成有含义的名字：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;hostnamectl set-hostname web-01
hostnamectl
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;命名建议带用途和序号，如 &lt;code&gt;web-01&lt;/code&gt;、&lt;code&gt;db-01&lt;/code&gt;、&lt;code&gt;hk-node-02&lt;/code&gt;，以后看日志、看监控一眼就知道是哪台。&lt;/p&gt;
&lt;p&gt;改完主机名，顺手把本机记录补进 &lt;code&gt;/etc/hosts&lt;/code&gt;。很多程序启动时会反查本机主机名，查不到就报错或卡顿。用编辑器打开 &lt;code&gt;/etc/hosts&lt;/code&gt;，确保有一行把主机名指向本机：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;127.0.1.1   web-01
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;（Debian 系习惯用 127.0.1.1 这一行放本机主机名；如果文件里已有写着旧主机名的行，直接把旧名改成新名即可。）改完用 &lt;code&gt;hostname&lt;/code&gt; 命令确认输出与预期一致。&lt;/p&gt;
&lt;p&gt;主机名命名再多说一句：只用小写字母、数字和连字符，别用下划线和中文，避免某些程序解析时出怪问题；名字里别带域名后缀（那是 FQDN 的事，主机名本体保持简短）。改主机名不需要重启，&lt;code&gt;hostnamectl&lt;/code&gt; 设置后立即生效，但已经登录的会话提示符可能要重新登录才刷新显示。&lt;/p&gt;
&lt;h2&gt;第六步：装齐必备工具&lt;/h2&gt;
&lt;p&gt;精简镜像为了体积，常用工具缺得厉害，真到排障时才发现 &lt;code&gt;curl&lt;/code&gt; 都没有，现场再装又慢又耽误事。初始化时一次性装齐，按用途分组：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;分组&lt;/th&gt;
&lt;th&gt;工具&lt;/th&gt;
&lt;th&gt;干什么用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;基础&lt;/td&gt;
&lt;td&gt;curl、wget&lt;/td&gt;
&lt;td&gt;发 HTTP 请求、下载文件，接口调试必备&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;基础&lt;/td&gt;
&lt;td&gt;vim&lt;/td&gt;
&lt;td&gt;终端编辑器，不习惯 vim 可换 nano&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;基础&lt;/td&gt;
&lt;td&gt;git&lt;/td&gt;
&lt;td&gt;拉代码、管配置版本&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;基础&lt;/td&gt;
&lt;td&gt;unzip、tar（一般自带）&lt;/td&gt;
&lt;td&gt;解压各类压缩包&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;基础&lt;/td&gt;
&lt;td&gt;ca-certificates&lt;/td&gt;
&lt;td&gt;HTTPS 证书根证书包，缺了它 curl 访问 HTTPS 会报错&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;排障&lt;/td&gt;
&lt;td&gt;htop&lt;/td&gt;
&lt;td&gt;交互式看 CPU、内存、进程，比 top 直观&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;排障&lt;/td&gt;
&lt;td&gt;lsof&lt;/td&gt;
&lt;td&gt;查文件和端口被哪个进程占用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;排障&lt;/td&gt;
&lt;td&gt;psmisc&lt;/td&gt;
&lt;td&gt;提供 pstree、killall 等进程小工具&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;网络&lt;/td&gt;
&lt;td&gt;dnsutils&lt;/td&gt;
&lt;td&gt;提供 dig、nslookup，查 DNS 解析&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;网络&lt;/td&gt;
&lt;td&gt;iputils-ping&lt;/td&gt;
&lt;td&gt;ping 命令，精简镜像可能没带&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;网络&lt;/td&gt;
&lt;td&gt;mtr-tiny&lt;/td&gt;
&lt;td&gt;路由追踪 + ping 合体，定位网络丢包段&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;网络&lt;/td&gt;
&lt;td&gt;tcpdump&lt;/td&gt;
&lt;td&gt;抓包，网络问题终极取证工具&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;网络&lt;/td&gt;
&lt;td&gt;iproute2&lt;/td&gt;
&lt;td&gt;提供 ip、ss 命令，一般自带，确认即可&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一条命令装完：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apt install -y curl wget vim git unzip ca-certificates htop lsof psmisc dnsutils iputils-ping mtr-tiny tcpdump
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;装完随手验证两个最常用的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -I https://deb.debian.org
dig deb.debian.org
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;curl 能返回 HTTP 状态行、dig 能返回解析结果，说明网络和 DNS 工具链都正常。&lt;/p&gt;
&lt;h2&gt;第七步：小内存机器补 Swap&lt;/h2&gt;
&lt;p&gt;Swap 是磁盘上划出来的一块区域，物理内存不够时把暂时不用的内存页挪过去，避免进程被系统直接杀掉（OOM）。1GB、2GB 内存的小机器强烈建议加 Swap；内存 8GB 以上的机器可加可不加，加一小块也能在内存突增时多一层缓冲。&lt;/p&gt;
&lt;p&gt;先看现状：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;free -h
swapon --show
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果 Swap 一行是 0、且 &lt;code&gt;swapon --show&lt;/code&gt; 没有输出，说明当前没 Swap。很多云镜像默认不带 Swap，一是镜像要适配各种规格，二是厂商更希望你升配加内存而不是用磁盘凑——但对个人小机器来说，Swap 是性价比最高的保险：没有它，内存被某个进程吃满时内核会直接杀进程（OOM Killer），被杀的可能是你的数据库，而不是占内存的那个；有了 Swap，系统先变慢、给你留出处理时间，而不是直接丢服务。&lt;/p&gt;
&lt;p&gt;实现方式上，传统的独立 Swap 分区和现在的 swapfile 效果相同，swapfile 胜在随时能建、能改大小、能删，不用动分区表，新机器统一用 swapfile 即可。按下面流程建一个 2GB 的 swapfile（大小按内存调整：内存 1GB 建 2GB，2GB 建 2GB，4GB 建 1~2GB 足够）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;code&gt;/swapfile&lt;/code&gt; 的权限必须设为 600&amp;lt;/span&amp;gt;。Swap 里存放的是内存页的副本，可能包含密码、密钥等敏感数据，权限放宽等于把内存内容摆在明面上，任何本地用户都能读。
:::&lt;/p&gt;
&lt;p&gt;&lt;code&gt;swapon&lt;/code&gt; 只是临时启用，重启就没了。写入 &lt;code&gt;/etc/fstab&lt;/code&gt; 持久化，在文件末尾加一行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/swapfile none swap sw 0 0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再调低 swappiness。这个参数控制系统「多积极地使用 Swap」，默认 60 对服务器偏高，会在内存还够用时就频繁换页、拖慢性能；服务器一般设为 10：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;echo &apos;vm.swappiness=10&apos; &amp;gt; /etc/sysctl.d/99-swap.conf
sysctl -p /etc/sysctl.d/99-swap.conf
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;最后验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;free -h
cat /proc/sys/vm/swappiness
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;free -h&lt;/code&gt; 的 Swap 行显示 2.0Gi 总量、swappiness 输出 10，Swap 这一步就完成了。Ubuntu 的流程与上面完全一致。&lt;/p&gt;
&lt;p&gt;最后强调一句定位：Swap 是救急的缓冲垫，不是内存的替代品。如果一台机器长期在用 Swap 跑业务，说明内存是真的不够了，正确动作是加内存或把服务拆走，而不是把 Swap 建得更大——磁盘再快也比内存慢几个数量级，长期靠 Swap 撑着的服务，延迟会难看到没法用。&lt;/p&gt;
&lt;h2&gt;收尾自查清单&lt;/h2&gt;
&lt;p&gt;十步走完，用一组命令把关键项快速过一遍，确认初始化真的落地：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cat /etc/os-release | head -2   # 系统版本
uname -r                        # 内核版本，应为更新后的新内核
date                            # 时间应为北京时间
timedatectl | grep -E &apos;Time zone|synchronized&apos;   # 时区与同步状态
id dev                          # 普通用户存在且在 sudo 组里
hostname                        # 主机名正确
df -h /                         # 根分区磁盘容量心里有数
free -h                         # 内存与 Swap 总量
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐项核对无误，这台机器的初始化就正式完成。建议把这套命令和顺序存成自己的检查清单，以后每开一台新机器照着走一遍，五分钟搞定且不漏项。&lt;/p&gt;
&lt;h2&gt;排障小节&lt;/h2&gt;
&lt;p&gt;初始化过程中最常撞上的三个问题：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;1. apt 报锁被占用&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;报错形如 &lt;code&gt;Could not get lock /var/lib/dpkg/lock-frontend&lt;/code&gt;。多数情况是系统自带的自动更新（unattended-upgrades）正在后台跑，稍等几分钟再试即可。确认到底是谁占着：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ps aux | grep -E &apos;apt|dpkg&apos; | grep -v grep
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果没有任何 apt/dpkg 进程在跑、锁却还在报错，先确认没有进程占用再处理。切忌在没确认的情况下直接删锁文件强行继续，可能把包数据库弄坏。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 时区改了，日志时间还是不对&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;code&gt;date&lt;/code&gt; 已经是北京时间，但某些服务的日志还打 UTC 时间。通常是服务在改时区之前就启动了，进程还记着旧时区。重启对应服务即可；系统日志（journald）的时间显示由读取时按本地时区换算，一般不用处理。个别应用（如某些 Java 程序、数据库）有自己的时区配置项，需要在应用配置里单独设，这不属于系统初始化的问题。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. sudo 提示用户不在 sudoers 文件里&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;报错 &lt;code&gt;dev is not in the sudoers file&lt;/code&gt;，说明用户没成功加入 sudo 组，或改配置时写错。解决办法：用 root 登录（或厂商控制台），重新执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;usermod -aG sudo dev
groups dev
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;确认输出里有 &lt;code&gt;sudo&lt;/code&gt; 后，让该用户重新登录再试。注意修改 &lt;code&gt;/etc/sudoers&lt;/code&gt; 本体时&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;必须用 &lt;code&gt;visudo&lt;/code&gt; 命令编辑，它会做语法校验；直接用普通编辑器改错一行，可能导致所有人都用不了 sudo&amp;lt;/span&amp;gt;。日常授权优先用加组的方式，尽量别动 sudoers 本体。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 换完软件源后 apt update 报错&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;换源后 &lt;code&gt;apt update&lt;/code&gt; 出现 404，通常是源地址里的发行版代号写错或该镜像站没有同步这个版本，对照官方源把代号改对；出现 &lt;code&gt;NO_PUBKEY&lt;/code&gt; 或签名错误，多半是镜像站地址写错了协议或路径，先换回官方源验证系统本身没问题，再逐项排查镜像源配置。原则：换源只换域名部分，路径结构和代号与官方保持一致，出错概率最低。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;本篇把新服务器初始化拆成了固定十步：更新系统、校准时间和时区、设好 UTF-8 locale、建普通用户配 sudo、改主机名补 hosts、装齐必备工具、给小内存机器补 Swap，最后用一组命令自查收尾。每一步都不难，难的是形成习惯、不漏项——机器开得越多，越能体会到统一初始化省下的排障时间。&lt;/p&gt;
&lt;p&gt;下一篇进入 SSH 安全加固：换密钥登录、关掉密码登录、改端口、装 Fail2ban，把这台已经初始化好的服务器的大门先锁结实。&lt;/p&gt;
</content:encoded></item><item><title>服务器监控与告警实战</title><link>https://www.anexns.cloudns.org/posts/linux-server-monitoring/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-server-monitoring/</guid><description>服务器出事要在用户之前知道：监控该盯哪几个指标、从命令行巡检到探针面板的方案梯度、磁盘与证书到期这类隐形雷的提前告警，以及一套自己用的巡检脚本长什么样。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;服务器最怕的不是出故障，而是出了故障你不知道——网站挂了三天，是访问者跑来告诉你的；磁盘写满导致数据库崩掉，你是在查日志的时候才顺带发现的；证书过期那天早上，所有用户看到的是浏览器的大红警告页。&lt;/p&gt;
&lt;p&gt;监控要解决的从来不是&quot;把数据画成图&quot;，而是&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;让异常在变成事故之前，先找到你&amp;lt;/span&amp;gt;。这一篇讲三件事：该盯哪些指标、用什么方案盯、告警怎么设才真的有用。主线是 Debian，最后给一套可以直接抄走改改就用的巡检脚本加 systemd timer，把磁盘、服务存活、证书到期这三颗最常见的雷一次性排掉。&lt;/p&gt;
&lt;h2&gt;一、监控到底在监控什么&lt;/h2&gt;
&lt;p&gt;先把目标说清楚，免得装了一堆仪表盘却什么都没防住。监控的价值只有三条：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;目标&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;th&gt;例子&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;发现异常&lt;/td&gt;
&lt;td&gt;服务挂了、端口不通，第一时间知道&lt;/td&gt;
&lt;td&gt;网站 502，监控比用户先发现&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;提前预警&lt;/td&gt;
&lt;td&gt;资源还没耗尽时就提醒，留出处理时间&lt;/td&gt;
&lt;td&gt;磁盘 85% 时告警，而不是 100% 时崩溃&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;事后追溯&lt;/td&gt;
&lt;td&gt;出事之后能查到当时的曲线，定位根因&lt;/td&gt;
&lt;td&gt;半夜 CPU 打满过一次，醒来能看到几点、涨了多少&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;三条里面，第一条和第二条靠的是&lt;strong&gt;告警&lt;/strong&gt;，第三条靠的是&lt;strong&gt;历史数据&lt;/strong&gt;。很多人的监控只做到了&quot;有个面板可以看&quot;，既没有历史留存，也没有主动告警——平时想不起来看，出事时也指望不上。这里把话说死：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;没告警的监控等于没监控&amp;lt;/span&amp;gt;。面板是给人巡检时看的，告警才是替你 24 小时值班的那个。&lt;/p&gt;
&lt;p&gt;所以本篇的思路是：指标可以盯得少而精，告警必须通、必须准、必须能把人叫醒。&lt;/p&gt;
&lt;h2&gt;二、必盯指标清单&lt;/h2&gt;
&lt;p&gt;不要一上来就追求&quot;全量指标&quot;。对个人和中小规模的服务器来说，下面这八项覆盖了 95% 以上的真实事故，每一项都给建议阈值和理由：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;指标&lt;/th&gt;
&lt;th&gt;看什么&lt;/th&gt;
&lt;th&gt;建议告警阈值&lt;/th&gt;
&lt;th&gt;为什么盯它&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;CPU 负载&lt;/td&gt;
&lt;td&gt;load average（1/5/15 分钟）&lt;/td&gt;
&lt;td&gt;15 分钟负载持续高于核数 × 1.5&lt;/td&gt;
&lt;td&gt;负载是综合信号，进程排队、IO 堵塞都会反映在这里&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;内存&lt;/td&gt;
&lt;td&gt;可用内存、Swap 使用量&lt;/td&gt;
&lt;td&gt;可用内存低于 10%，或 Swap 持续增长&lt;/td&gt;
&lt;td&gt;内存耗尽会触发 OOM Killer 随机杀进程，死状千奇百怪&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;磁盘水位&lt;/td&gt;
&lt;td&gt;各分区使用率&lt;/td&gt;
&lt;td&gt;80% 预警、90% 严重&lt;/td&gt;
&lt;td&gt;日志和数据库只涨不缩，写满是迟早的事，见过太多&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;inode&lt;/td&gt;
&lt;td&gt;inode 使用率&lt;/td&gt;
&lt;td&gt;80%&lt;/td&gt;
&lt;td&gt;小文件太多时空间没满 inode 先满，症状是&quot;明明有空间却无法创建文件&quot;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;服务存活&lt;/td&gt;
&lt;td&gt;关键进程 / 服务单元状态&lt;/td&gt;
&lt;td&gt;非 active 立即告警&lt;/td&gt;
&lt;td&gt;进程崩了、被误杀了、重启后没拉起来，都靠这条兜底&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;端口可达&lt;/td&gt;
&lt;td&gt;对外服务端口从外部探测&lt;/td&gt;
&lt;td&gt;连续 2~3 次失败&lt;/td&gt;
&lt;td&gt;本机看着活着、外网连不上（防火墙、云厂商安全组）只有外部探测能发现&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;证书到期&lt;/td&gt;
&lt;td&gt;HTTPS 证书剩余天数&lt;/td&gt;
&lt;td&gt;剩余 14 天预警、7 天严重&lt;/td&gt;
&lt;td&gt;过期即全站红页，且往往是&quot;突然&quot;发生，专节细讲&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;登录异常&lt;/td&gt;
&lt;td&gt;SSH 登录成功 / 失败记录&lt;/td&gt;
&lt;td&gt;非白名单 IP 成功登录立即告警&lt;/td&gt;
&lt;td&gt;成功登录里混进一个陌生 IP，就是入侵实锤&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个阈值背后的逻辑值得多说一句：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;磁盘为什么 80% 就要报。&lt;/strong&gt; 因为从 80% 到 100% 的速度取决于写入速率，日志爆量、数据库暴涨时可能只要几个小时。等告警阈值设在 95%，留给你的处理时间经常是负数。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;负载为什么看 15 分钟而不是瞬时值。&lt;/strong&gt; 编译、备份、定时任务都会造成短时尖峰，看瞬时值必然误报连连。15 分钟平均负载还压不下来，才是真问题。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;内存为什么盯 Swap。&lt;/strong&gt; 内存使用率本身参考意义有限（Linux 会拿空闲内存做缓存），但 Swap 开始持续被用且不断增长，说明物理内存是真的不够了，这是比&quot;内存使用率 90%&quot;可靠得多的信号。&lt;/p&gt;
&lt;h2&gt;三、命令行巡检基线：五分钟看完一台机器&lt;/h2&gt;
&lt;p&gt;任何面板和脚本都替代不了一件事：你自己心里要有&quot;这台机器正常时是什么样&quot;的基线。第一次接手一台机器，或者每月例行，花五分钟跑一遍下面这套组合：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;uptime          # 开机时长 + 三档负载，和核数对比着看
free -h         # 内存与 Swap，重点看 available 和 Swap 已用量
df -h           # 磁盘水位，先扫一眼有没有超过 80% 的分区
df -i           # inode 使用率，别漏
ss -tlnp        # 正在监听的 TCP 端口，对一遍是不是都是该开的
systemctl --failed   # 有没有挂掉的服务单元
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再加两个&quot;体检&quot;命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;htop            # 交互式看进程排行，谁吃 CPU、谁吃内存一目了然
journalctl -p err -b --no-pager | tail -50    # 本次开机以来的错误级日志
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;巡检的关键不在命令本身，而在&lt;strong&gt;和基线对比&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;这台机器平时负载 0.3，今天 2.8 —— 有事；&lt;/li&gt;
&lt;li&gt;平时根分区 45%，这周 71% —— 有东西在涨，找出是什么在涨；&lt;/li&gt;
&lt;li&gt;监听端口里多了一个不认识的 —— 要么是你忘了，要么就不是你开的。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
巡检时发现&quot;不认识的监听端口&quot;或&quot;不认识的进程&quot;不要随手杀掉就完事：先记录下进程路径、启动时间和父进程，确认来源再处理。直接 kill 等于销毁现场，真出了安全问题就再也查不清了。
:::&lt;/p&gt;
&lt;p&gt;没有基线意识，指标数字再多也只是数字。先知道正常长什么样，异常才认得出来。&lt;/p&gt;
&lt;h2&gt;四、方案梯度：从脚本到体系&lt;/h2&gt;
&lt;p&gt;工具方案按&quot;机器数量 × 愿意投入的精力&quot;分四档，没有哪档是错的，选错规模才是错的：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方案&lt;/th&gt;
&lt;th&gt;适合规模&lt;/th&gt;
&lt;th&gt;能做什么&lt;/th&gt;
&lt;th&gt;短板&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;自写脚本 + 通知&lt;/td&gt;
&lt;td&gt;1~3 台&lt;/td&gt;
&lt;td&gt;查指定指标、超阈值发消息，灵活轻量&lt;/td&gt;
&lt;td&gt;没有历史曲线，脚本本身要自己维护&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Uptime Kuma&lt;/td&gt;
&lt;td&gt;1~10 台&lt;/td&gt;
&lt;td&gt;专盯存活：HTTP、端口、Ping、证书到期，自带漂亮面板和通知&lt;/td&gt;
&lt;td&gt;只管&quot;活没活&quot;，不管资源指标&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Komari / 哪吒类探针&lt;/td&gt;
&lt;td&gt;3~30 台&lt;/td&gt;
&lt;td&gt;多机一屏概览：负载、内存、磁盘、流量、到期时间&lt;/td&gt;
&lt;td&gt;指标深度有限，告警规则相对简单&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Prometheus + Grafana 体系&lt;/td&gt;
&lt;td&gt;认真做指标时&lt;/td&gt;
&lt;td&gt;全量指标存储、任意维度查询、复杂告警规则&lt;/td&gt;
&lt;td&gt;组件多、吃资源、学习成本最高&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选型建议很简单：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;只有一两台机器&lt;/strong&gt;：脚本巡检 + Uptime Kuma 的组合足够，前者管资源，后者管存活和证书；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;三五台到二三十台&lt;/strong&gt;：上探针面板做多机概览，省掉逐台登录巡检的时间，告警规则在探针里配；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;容器很多、要查历史指标定位性能问题&lt;/strong&gt;：再考虑 Prometheus 体系。容器场景的完整搭法在 Docker 系列的&lt;a href=&quot;/posts/docker-monitoring-prometheus/&quot;&gt;容器监控体系一篇&lt;/a&gt;里讲过，这里不重复。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;一个常见的误区是按&quot;哪个功能强&quot;选，而不是按&quot;我有几台机器、愿意花多少时间维护监控本身&quot;选。监控系统自己的维护成本必须算进方案里——为了监控三台小机器养一套 Prometheus，多数人最后是把监控先放弃了。&lt;/p&gt;
&lt;p&gt;还有一条铁律：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;监控不要和被监控对象放在同一台机器上&amp;lt;/span&amp;gt;。机器整机宕机时，同机的监控会陪葬，连最后一条告警都发不出来。探针面板、Uptime Kuma 尽量放另一台机器或另一个机房。&lt;/p&gt;
&lt;h2&gt;五、告警通道怎么选&lt;/h2&gt;
&lt;p&gt;指标采得再全，告警发不出去、发出去没人看，等于零。通道按&quot;能不能半夜把人叫醒&quot;来评估：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;通道&lt;/th&gt;
&lt;th&gt;门槛&lt;/th&gt;
&lt;th&gt;特点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;邮件&lt;/td&gt;
&lt;td&gt;最低，装个发送工具即可&lt;/td&gt;
&lt;td&gt;可靠但容易被淹没在收件箱里，适合低频的预警类（如证书 14 天提醒）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Telegram Bot&lt;/td&gt;
&lt;td&gt;低，建 Bot 拿 Token 即可&lt;/td&gt;
&lt;td&gt;到达快、手机必看，个人运维最常用；需要服务器能访问 Telegram&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;企业微信 / 钉钉机器人&lt;/td&gt;
&lt;td&gt;低，群里加 Webhook 机器人&lt;/td&gt;
&lt;td&gt;国内到达率好，适合团队；个人用略显正式&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;短信 / 电话&lt;/td&gt;
&lt;td&gt;高，一般走云厂商付费接口&lt;/td&gt;
&lt;td&gt;叫醒能力最强，只留给最严重级别&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;实际搭配建议：日常预警走 Telegram 或企业微信这类即时消息，严重告警再叠加一层更&quot;吵&quot;的通道。不要把所有级别都堆在同一个通道里——每天响二十次的通道，第三天就会被静音，那之后真正的严重告警也一起聋了。告警降噪是第八节的主题，这里先记住：&lt;strong&gt;通道的信誉是被误报一点点败光的&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;六、实战：一套自用巡检脚本&lt;/h2&gt;
&lt;p&gt;下面这套脚本是我建议的起步模板：检查磁盘水位、关键服务存活、指定域名证书剩余天数，任何一项超阈值就发通知。它故意写得朴素——变量都在开头，改成你自己的值就能用。&lt;/p&gt;
&lt;p&gt;先建脚本 &lt;code&gt;/usr/local/bin/server-check.sh&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/usr/bin/env bash
# 服务器巡检：磁盘 / 服务存活 / 证书到期，超阈值发通知
set -u

# ============ 按需修改区 ============
DISK_WARN=80                      # 磁盘使用率预警阈值（%）
DISK_CRIT=90                      # 磁盘使用率严重阈值（%）
CERT_WARN_DAYS=14                 # 证书剩余天数预警阈值
SERVICES=&quot;nginx docker ssh&quot;       # 要盯存活的 systemd 服务，空格分隔
DOMAINS=&quot;example.com blog.example.com&quot;   # 要盯证书的域名，空格分隔
STATE_FILE=&quot;/var/tmp/server-check.state&quot; # 状态文件，用于降噪（见下文）
# ===================================

MSG=&quot;&quot;

add_msg() { MSG=&quot;${MSG}$1\n&quot;; }

# ---- 1. 磁盘水位 ----
while read -r mount pct; do
    pct=${pct%\%}
    if [ &quot;$pct&quot; -ge &quot;$DISK_CRIT&quot; ]; then
        add_msg &quot;[严重] 磁盘 ${mount} 已用 ${pct}%&quot;
    elif [ &quot;$pct&quot; -ge &quot;$DISK_WARN&quot; ]; then
        add_msg &quot;[预警] 磁盘 ${mount} 已用 ${pct}%&quot;
    fi
done &amp;lt; &amp;lt;(df -P | awk &apos;NR&amp;gt;1 &amp;amp;&amp;amp; $6!~/^\/(dev|run|sys)/ {print $6, $5}&apos;)

# ---- 2. 服务存活 ----
for svc in $SERVICES; do
    if ! systemctl is-active --quiet &quot;$svc&quot;; then
        add_msg &quot;[严重] 服务 ${svc} 未运行&quot;
    fi
done

# ---- 3. 证书到期 ----
for d in $DOMAINS; do
    end=$(echo | openssl s_client -servername &quot;$d&quot; -connect &quot;${d}:443&quot; 2&amp;gt;/dev/null \
        | openssl x509 -noout -enddate 2&amp;gt;/dev/null | cut -d= -f2)
    [ -z &quot;$end&quot; ] &amp;amp;&amp;amp; { add_msg &quot;[预警] 域名 ${d} 证书读取失败&quot;; continue; }
    end_ts=$(date -d &quot;$end&quot; +%s)
    days=$(( (end_ts - $(date +%s)) / 86400 ))
    if [ &quot;$days&quot; -lt 0 ]; then
        add_msg &quot;[严重] 域名 ${d} 证书已过期&quot;
    elif [ &quot;$days&quot; -le &quot;$CERT_WARN_DAYS&quot; ]; then
        add_msg &quot;[预警] 域名 ${d} 证书剩余 ${days} 天&quot;
    fi
done

# ---- 4. 发送（降噪：同一批问题只报一次，见第八节）----
[ -z &quot;$MSG&quot; ] &amp;amp;&amp;amp; { : &amp;gt; &quot;$STATE_FILE&quot;; exit 0; }

HASH=$(printf &apos;%b&apos; &quot;$MSG&quot; | md5sum | cut -d&apos; &apos; -f1)
LAST=$(cat &quot;$STATE_FILE&quot; 2&amp;gt;/dev/null || true)
[ &quot;$HASH&quot; = &quot;$LAST&quot; ] &amp;amp;&amp;amp; exit 0        # 问题没变化，不重复轰炸
echo &quot;$HASH&quot; &amp;gt; &quot;$STATE_FILE&quot;

# ↓↓↓ 把这一段换成你自己的通知通道 ↓↓↓
# 示例：Telegram Bot（把 TOKEN 和 CHAT_ID 换成自己的）
# curl -s -X POST &quot;https://api.telegram.org/botTOKEN/sendMessage&quot; \
#   -d &quot;chat_id=CHAT_ID&quot; --data-urlencode &quot;text=$(printf &apos;%b&apos; &quot;$MSG&quot;)&quot; &amp;gt; /dev/null
# 示例：只写日志（先这样跑通流程，再接通道）
logger -t server-check &quot;$(printf &apos;%b&apos; &quot;$MSG&quot;)&quot;
printf &apos;%b&apos; &quot;$MSG&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐段说明几个关键点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;磁盘检查&lt;/strong&gt;用 &lt;code&gt;df -P&lt;/code&gt; 保证一行一个文件系统不折行，&lt;code&gt;awk&lt;/code&gt; 过滤掉 &lt;code&gt;/dev&lt;/code&gt;、&lt;code&gt;/run&lt;/code&gt; 这类伪文件系统，只看真实分区；遍历的是挂载点，所以多块盘、多分区都能覆盖。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;服务存活&lt;/strong&gt;用 &lt;code&gt;systemctl is-active --quiet&lt;/code&gt;，返回非零就是没在跑，判断干净利落。服务名按你的机器改：跑 Docker 的机器盯 &lt;code&gt;docker&lt;/code&gt;，数据库盯 &lt;code&gt;postgresql&lt;/code&gt; 或 &lt;code&gt;mysql&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;证书检查&lt;/strong&gt;就是下一节要细讲的 &lt;code&gt;openssl s_client&lt;/code&gt; 套路，脚本里把到期时间换算成剩余天数再比阈值。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;发送部分留了占位&lt;/strong&gt;：先用 &lt;code&gt;logger&lt;/code&gt; 写进系统日志把全流程跑通，确认脚本逻辑没问题，再把注释里的 Telegram 示例改成你的 Token 和会话 ID 启用——通道最后接，避免调试期乱发消息。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;给执行权限，然后手动跑一次验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;chmod +x /usr/local/bin/server-check.sh
/usr/local/bin/server-check.sh; echo &quot;退出码: $?&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;故意验证一下告警通不通：把 &lt;code&gt;DISK_WARN&lt;/code&gt; 临时改成 10 再跑一次，应该立刻收到一条磁盘预警——从没被触发过的告警链路，默认按&quot;坏的&quot;处理，上线前必须人为触发验证一遍。&lt;/p&gt;
&lt;p&gt;最后挂上 systemd timer，每 30 分钟跑一次。服务单元 &lt;code&gt;/etc/systemd/system/server-check.service&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Unit]
Description=Server inspection checks

[Service]
Type=oneshot
ExecStart=/usr/local/bin/server-check.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;定时器 &lt;code&gt;/etc/systemd/system/server-check.timer&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Unit]
Description=Run server inspection every 30 minutes

[Timer]
OnBootSec=5min
OnUnitActiveSec=30min
Unit=server-check.service

[Install]
WantedBy=timers.target
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启用并确认在跑：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl daemon-reload
systemctl enable --now server-check.timer
systemctl list-timers server-check.timer    # 看下一次触发时间
journalctl -u server-check.service -n 50    # 看历次执行日志
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;用 timer 而不是 cron 的好处是执行记录、失败状态都在 journal 里，&lt;code&gt;systemctl status&lt;/code&gt; 一眼能看到上次跑没跑、挂没挂——这一点第九节还会用到。&lt;/p&gt;
&lt;h2&gt;七、证书到期：最高频的&quot;突然打不开&quot;&lt;/h2&gt;
&lt;p&gt;在所有&quot;网站突然打不开&quot;的事故里，证书过期稳居前列，而且它有个最气人的特点：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;过期之前毫无征兆，过期瞬间全站瘫痪&amp;lt;/span&amp;gt;。Let&apos;s Encrypt 的证书只有 90 天，自动续期一旦因为 DNS、端口、配置变动失败一次，没人盯着就会直接过期给你看。&lt;/p&gt;
&lt;p&gt;手动查任意域名证书到期日的命令记住这一条就够：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;echo | openssl s_client -servername example.com -connect example.com:443 2&amp;gt;/dev/null \
  | openssl x509 -noout -dates -issuer
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出类似：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;notBefore=Oct 18 03:00:00 2026 GMT
notAfter=Jan 16 03:00:00 2027 GMT
issuer=C = US, O = Let&apos;s Encrypt, CN = R12
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个细节：&lt;code&gt;-servername&lt;/code&gt; 是 SNI，一个 IP 上挂多个证书时不写它查到的可能是默认证书，结果会误导你；&lt;code&gt;echo |&lt;/code&gt; 是为了让 &lt;code&gt;openssl s_client&lt;/code&gt; 读完证书立刻退出，不要省。只想要剩余天数的话，把上一节脚本里那段换算单独拎出来用也行。&lt;/p&gt;
&lt;p&gt;防御上做两件事就够：续期走自动化（certbot 的 timer 或反代自带续期），监控里给证书留 14 天和 7 天两档提醒——14 天那档是给&quot;自动续期失败了&quot;留的人工处理窗口，7 天那档就是最后通牒。&lt;/p&gt;
&lt;h2&gt;八、告警降噪：别让告警疲劳毁掉通道&lt;/h2&gt;
&lt;p&gt;告警系统最常见的死法不是漏报，是误报太多把人逼到关通知。所以降噪不是锦上添花，是保命设置。四条原则：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;阈值分级&lt;/strong&gt;。预警和严重分开：预警进消息通道看一眼就行，严重才升级到更吵的通道。上一节脚本里磁盘 80/90 两档、消息里带 &lt;code&gt;[预警]&lt;/code&gt; / &lt;code&gt;[严重]&lt;/code&gt; 前缀，就是这个意思。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;连续失败再报&lt;/strong&gt;。端口探测、HTTP 探测这类受网络抖动影响的检查，要求连续 2~3 次失败才发告警。抖一下就恢复的那种，报出来纯属消耗信任。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;同一问题只报一次，恢复再报一次&lt;/strong&gt;。脚本里的状态文件就是干这个的：把本轮问题清单算个哈希，和上轮一样就说明问题没变化、已经报过了，闭嘴；问题集合变了（新增、消失）才再发。服务恢复时发一条&quot;已恢复&quot;，让人知道可以安心了，而不是一直惦记。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;定期复盘误报&lt;/strong&gt;。每条让你白紧张一次的告警，都要回去调阈值或加条件。误报不是忍一忍的事，它在透支整个通道的信誉。&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;九、排障&lt;/h2&gt;
&lt;h3&gt;告警没发出来&lt;/h3&gt;
&lt;p&gt;按链路从后往前查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;脚本到底跑没跑：&lt;code&gt;systemctl list-timers&lt;/code&gt; 看 timer 在不在，&lt;code&gt;journalctl -u server-check.service&lt;/code&gt; 看执行记录；timer 没启用、脚本没执行权限，是最常见的两种。&lt;/li&gt;
&lt;li&gt;脚本跑了但判断没触发：手动执行一次脚本，把阈值临时调低人为触发（第六节的方法），区分是&quot;没问题&quot;还是&quot;判断逻辑坏了&quot;。&lt;/li&gt;
&lt;li&gt;判断触发了但消息没到：单独拿 &lt;code&gt;curl&lt;/code&gt; 把通知请求发一遍看返回，Token 失效、会话 ID 写错、服务器出不了外网，都在这一步现形。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;还有一层元问题：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;监控本身也要被监控&amp;lt;/span&amp;gt;。巡检脚本所在的机器整机宕机时，它一条告警也发不出来——所以存活探测（Ping、端口）一定要由&lt;strong&gt;另一台机器&lt;/strong&gt;从外部来做，比如 Uptime Kuma 放在第二台机器上探第一台，两台互相探，谁死了都有人喊。&lt;/p&gt;
&lt;h3&gt;指标看着正常，但服务已经死了&lt;/h3&gt;
&lt;p&gt;这是新手最容易栽的坑：面板上 CPU、内存、磁盘全绿，用户却说打不开。原因是指标和存活是两个维度——进程僵死、端口假死、应用层卡死时，资源指标完全可以一切正常。对策就是第二节清单里把两者分开盯：资源指标归资源指标，服务存活必须用&quot;进程状态 + 端口探测 + HTTP 状态码&quot;单独验证，缺一不可。反过来也一样：端口通、返回 200，也不代表磁盘三天后不会写满。两个维度都齐了，监控才算完整。&lt;/p&gt;
&lt;h3&gt;探针面板全红但网站能打开&lt;/h3&gt;
&lt;p&gt;先别慌着救网站——大概率是探针 agent 掉线、面板机器网络问题，或者 agent 版本升级后不兼容。用浏览器直接访问网站、再 SSH 登录看一眼服务状态，确认是&quot;监控坏了&quot;而不是&quot;服务坏了&quot;，然后修监控。把这两类故障分清，能省掉很多半夜的无效折腾。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;监控的目的是发现异常、提前预警、事后追溯，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;核心在告警，不在面板&amp;lt;/span&amp;gt;；&lt;/li&gt;
&lt;li&gt;必盯八项：负载、内存与 Swap、磁盘水位、inode、服务存活、端口可达、证书到期、登录异常，阈值宁可保守留足处理时间；&lt;/li&gt;
&lt;li&gt;先用命令行巡检建立&quot;正常长什么样&quot;的基线，再谈任何工具；&lt;/li&gt;
&lt;li&gt;方案按规模选：脚本 + Uptime Kuma 起步，多机上探针面板，深挖指标才上 Prometheus 体系，且监控别和被监控对象同机；&lt;/li&gt;
&lt;li&gt;告警通道要分级、能叫醒人，降噪四原则（分级、连续失败再报、状态去重、复盘误报）决定这套系统能活多久；&lt;/li&gt;
&lt;li&gt;证书是最高频的隐形雷，&lt;code&gt;openssl s_client&lt;/code&gt; 查到期、14 天预警必须有；&lt;/li&gt;
&lt;li&gt;最后记住：监控本身也要被监控，存活探测永远从外部、从另一台机器发起。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>SSH 高级用法：跳板机与端口转发</title><link>https://www.anexns.cloudns.org/posts/linux-ssh-advanced/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-ssh-advanced/</guid><description>多台服务器管出效率：用 ssh config 给每台起别名、ProxyJump 经跳板机进内网、三种端口转发的区别与场景，再加连接复用与 agent 的日常便利。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;上一篇 &lt;a href=&quot;/posts/linux-ssh-hardening/&quot;&gt;SSH 加固&lt;/a&gt; 讲的是服务端：关掉密码登录、收紧 sshd 配置、别让全网扫描器惦记你的 22 端口。这一篇换个视角，讲客户端：机器只有一两台时，&lt;code&gt;ssh root@1.2.3.4 -p 3526&lt;/code&gt; 敲着还行；机器涨到五台、十台，还分布在不同机房、有的甚至没有公网入口，光是记 IP、端口、用户名和密钥路径就能把人逼疯，更别提每次登录还要重复敲一长串参数。&lt;/p&gt;
&lt;p&gt;这一篇的主线就是把客户端这一侧理顺：先用 &lt;code&gt;~/.ssh/config&lt;/code&gt; 给每台机器起别名，一条 &lt;code&gt;ssh 别名&lt;/code&gt; 走天下；再用 ssh-agent 让带密码短语的密钥不用反复输密码；然后解决「内网机器没有公网 IP 怎么进」的问题——跳板机 ProxyJump 一步直达；接着把端口转发三兄弟（-L、-R、-D）一次讲透，这是 SSH 最被低估的能力：访问内网管理页、借服务器网络出口、临时暴露本机服务，全靠它们；最后补上连接复用与保活参数，让日常操作再快一截。&lt;/p&gt;
&lt;h2&gt;一、先分工：加固管服务端，这篇管客户端&lt;/h2&gt;
&lt;p&gt;两篇的分工先说清楚，避免混淆：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;SSH 加固篇&lt;/th&gt;
&lt;th&gt;本篇（高级用法）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;配置对象&lt;/td&gt;
&lt;td&gt;服务器上的 sshd&lt;/td&gt;
&lt;td&gt;你手边机器上的 ssh 客户端&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;核心文件&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/etc/ssh/sshd_config&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;~/.ssh/config&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;解决的问题&lt;/td&gt;
&lt;td&gt;别被爆破、别被扫&lt;/td&gt;
&lt;td&gt;登录快、进得去内网、流量能借道&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;关键词&lt;/td&gt;
&lt;td&gt;密钥登录、改端口、Fail2ban&lt;/td&gt;
&lt;td&gt;别名、跳板机、端口转发、连接复用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;服务端的门锁配好了，客户端要解决的是钥匙串管理与通行路线问题。&amp;lt;/span&amp;gt;本篇所有命令都以 OpenSSH 客户端为准，Linux、macOS 自带的都是它；Windows 10/11 自带的 OpenSSH 客户端用法也基本一致。&lt;/p&gt;
&lt;h2&gt;二、ssh config：给每台机器起个名字&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;~/.ssh/config&lt;/code&gt; 是客户端的通讯录。没有它时，你的登录命令长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh -i ~/.ssh/id_ed25519_work -p 3526 deploy@203.0.113.10
ssh -i ~/.ssh/id_ed25519_home -p 22 root@198.51.100.23
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;每台机器的参数都不一样，敲错一个数字就连错机器甚至连不上。把它们写进配置文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# ~/.ssh/config

Host rn
    HostName 203.0.113.10
    User deploy
    Port 3526
    IdentityFile ~/.ssh/id_ed25519_work

Host green
    HostName 198.51.100.23
    User root
    Port 22
    IdentityFile ~/.ssh/id_ed25519_home

Host sg
    HostName 192.0.2.88
    User root
    Port 32567
    IdentityFile ~/.ssh/id_ed25519_work
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;之后登录只需要：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh rn
ssh green
scp somefile.tar.gz sg:/root/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;scp&lt;/code&gt;、&lt;code&gt;sftp&lt;/code&gt;、&lt;code&gt;rsync -e ssh&lt;/code&gt; 这些工具都认同一份 config，别名全线通用——这是很多人不知道的：你在 config 里起的别名不是 ssh 一家的福利，是整个 SSH 工具链的。&lt;/p&gt;
&lt;h3&gt;字段逐个讲&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Host&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;别名定义开头&lt;/td&gt;
&lt;td&gt;后面跟的名字就是你敲的别名，可以有多个（空格隔开）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;HostName&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;真实地址&lt;/td&gt;
&lt;td&gt;IP 或域名，连接实际打到这里&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;User&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;登录用户名&lt;/td&gt;
&lt;td&gt;不写则用当前系统用户名&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Port&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;端口&lt;/td&gt;
&lt;td&gt;不写默认 22；非标端口的机器靠它免敲 &lt;code&gt;-p&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;IdentityFile&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;私钥路径&lt;/td&gt;
&lt;td&gt;哪台机器用哪把钥匙，一台一行；多把可以写多行，按顺序试&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;IdentitiesOnly&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只用指定的钥匙&lt;/td&gt;
&lt;td&gt;写 &lt;code&gt;yes&lt;/code&gt; 后客户端不会把 agent 里的其他钥匙挨个拿去试，避免试太多把被服务器踢掉&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ServerAliveInterval&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;保活间隔&lt;/td&gt;
&lt;td&gt;后面会单独讲&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ProxyJump&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;跳板机&lt;/td&gt;
&lt;td&gt;后面会单独讲&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个使用习惯：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;别名起短的&lt;/strong&gt;。&lt;code&gt;rn&lt;/code&gt;、&lt;code&gt;green&lt;/code&gt;、&lt;code&gt;sg&lt;/code&gt; 这种两三个字母的最好，天天敲的东西不要起 &lt;code&gt;racknerd-server-01&lt;/code&gt; 这种全名。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;注释写清楚机器身份&lt;/strong&gt;。IP 会换、机器会退役，半年后你看着 &lt;code&gt;Host node3&lt;/code&gt; 根本想不起来这是哪台。每个 Host 块上方加一行注释：用途、机房、到期时间，省未来的自己一条命。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;通配兜底放最后&lt;/strong&gt;。config 的匹配规则是「先匹配到的先算数」：文件从上往下读，每个参数取&lt;strong&gt;第一个&lt;/strong&gt;匹配到的值。所以可以这样写一个全局兜底：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;Host *
    ServerAliveInterval 60
    IdentitiesOnly yes
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把它放在文件&lt;strong&gt;末尾&lt;/strong&gt;，给所有机器统一加上保活与「只用指定钥匙」，各 Host 块里自己写了的优先生效。反过来，把 &lt;code&gt;Host *&lt;/code&gt; 写在最前面，后面再写具体配置，很多字段就被兜底值抢先占住了——这是 config 不生效类问题最常见的根源，排障一节还会再提。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;code&gt;~/.ssh/config&lt;/code&gt; 和私钥一样属于敏感文件：里面写着你所有服务器的地址、端口、用户名，泄露出去等于把资产清单双手奉上。权限保持 600（&lt;code&gt;chmod 600 ~/.ssh/config&lt;/code&gt;），整个 &lt;code&gt;~/.ssh&lt;/code&gt; 目录保持 700。OpenSSH 对私钥文件权限过宽会直接拒绝使用，config 虽不强制，但习惯要一致。
:::&lt;/p&gt;
&lt;h2&gt;三、密钥日常：ssh-agent 让你只输一次密码&lt;/h2&gt;
&lt;p&gt;加固篇建议给私钥加密码短语（passphrase），这是对的——私钥文件丢了还有最后一道锁。但副作用很现实：每次登录、每次 &lt;code&gt;git push&lt;/code&gt;、每次 &lt;code&gt;scp&lt;/code&gt; 都要输一遍长密码，用不了几天人就想把密码短语去掉。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;因为嫌烦而拆掉密钥密码，等于把加固成果亲手退回。&amp;lt;/span&amp;gt;正确解法是 ssh-agent。&lt;/p&gt;
&lt;h3&gt;agent 是什么&lt;/h3&gt;
&lt;p&gt;ssh-agent 是常驻后台的一个小进程，干一件事：把解密后的私钥暂存在内存里。你登录时客户端先问 agent「这把钥匙你有吗」，有就直接签名，全程不再碰密码。流程是：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;agent 启动后，你用 &lt;code&gt;ssh-add&lt;/code&gt; 把私钥加进去，此时输&lt;strong&gt;一次&lt;/strong&gt;密码短语解密；&lt;/li&gt;
&lt;li&gt;之后所有 ssh/scp/git 操作都走 agent 签名，不再问密码；&lt;/li&gt;
&lt;li&gt;agent 随会话结束（注销/关机）清空，内存里的钥匙不落盘。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;用法&lt;/h3&gt;
&lt;p&gt;大多数桌面 Linux 与 macOS 的图形会话会自动拉起 agent，先检查一下有没有在跑：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;echo $SSH_AUTH_SOCK   # 有输出说明 agent 已就绪
ssh-add -l            # 列出已加载的钥匙，没有会提示 &quot;The agent has no identities&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;加载钥匙：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh-add ~/.ssh/id_ed25519_work
# 提示输入该密钥的密码短语，输一次
ssh-add -l            # 再确认已加载，能看到指纹
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;之后 &lt;code&gt;ssh rn&lt;/code&gt; 直接进，不再弹窗。如果你的环境没有自动启动 agent，手动起一个：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;eval &quot;$(ssh-agent -s)&quot;   # 启动并把环境变量注入当前 shell
ssh-add ~/.ssh/id_ed25519_work
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;eval&lt;/code&gt; 这行只对当前终端有效，新开终端要重来——这也是为什么推荐用桌面会话自带的 agent 或在 shell 配置里做持久化，而不是每个窗口手动敲。&lt;/p&gt;
&lt;p&gt;macOS 还有个便利：&lt;code&gt;ssh-add --apple-use-keychain ~/.ssh/xxx&lt;/code&gt; 可以把密码短语存进系统钥匙串，重启后自动恢复，配合 config 里的 &lt;code&gt;UseKeychain yes&lt;/code&gt; 体验和没密码一样，但私钥落盘仍是加密的。&lt;/p&gt;
&lt;h3&gt;agent 转发：便利与风险&lt;/h3&gt;
&lt;p&gt;还有一个进阶功能叫 agent 转发（&lt;code&gt;ssh -A&lt;/code&gt; 或 config 里 &lt;code&gt;ForwardAgent yes&lt;/code&gt;）：你登录到服务器 A 后，在 A 上再执行 &lt;code&gt;ssh B&lt;/code&gt;，B 的认证会绕回你本机的 agent 完成——A 上不需要放任何私钥，就能继续往里跳。听起来很美好，但要清楚代价：转发期间，A 上拥有你 shell 权限的人（比如 A 被入侵、或 root 用户）可以借你的 agent 去登录你所有机器，钥匙本体偷不走，但「使用权」在会话期间是敞开的。&lt;/p&gt;
&lt;p&gt;结论：自家可信的跳板机之间用可以；来路不明、共用的机器上&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝不开 agent 转发&amp;lt;/span&amp;gt;，这种场景用下面要讲的 ProxyJump，它不需要在跳板机上暴露 agent。&lt;/p&gt;
&lt;h2&gt;四、跳板机：没有公网入口的机器也能一步直达&lt;/h2&gt;
&lt;h3&gt;场景&lt;/h3&gt;
&lt;p&gt;生产环境里常见的拓扑是：只有一台机器（跳板机/堡垒机）有公网 IP，其余机器全在内网，比如数据库服务器、内部应用服务器只监听 &lt;code&gt;10.x&lt;/code&gt; 内网地址。你人在公网，想登录内网机器，老办法是两段式：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh jump            # 先进跳板机
ssh 10.0.0.15       # 在跳板机上再往里跳
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;能用，但难受：在跳板机上再敲一遍用户名密码（或要在跳板机上放私钥）、传文件要中转两次、开编辑器断线重连全套重来。ProxyJump 就是来消灭这种两段式的。&lt;/p&gt;
&lt;h3&gt;两种写法&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;命令行写法&lt;/strong&gt;，用 &lt;code&gt;-J&lt;/code&gt; 参数：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh -J jump_user@jump.example.com:22 deploy@10.0.0.15
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;config 写法&lt;/strong&gt;（推荐，一次配置长期省事）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Host jump
    HostName jump.example.com
    User jump_user
    Port 22
    IdentityFile ~/.ssh/id_ed25519_work

Host db-internal
    HostName 10.0.0.15
    User deploy
    IdentityFile ~/.ssh/id_ed25519_work
    ProxyJump jump
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;之后 &lt;code&gt;ssh db-internal&lt;/code&gt; 一步到位：客户端先和跳板机建立连接，在它上面开一条通道直通内网机器的 22 端口，然后在这条通道里完成对内网机器的认证。链路是这样走的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;你的电脑 ──SSH──&amp;gt; 跳板机（公网） ──内网转发──&amp;gt; 内网机器 10.0.0.15
   │                                                    ▲
   └──────────── 认证与会话端到端加密，跳板机只转发流量 ──┘
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;关键点：&lt;strong&gt;内网机器的认证是在你本机和它之间端到端完成的&lt;/strong&gt;，跳板机只负责搬运加密流量，看不到内容、也不需要上面存你的私钥。这正是它比 agent 转发更值得推荐的原因——跳板机哪怕被攻破，攻击者也拿不到你的会话内容（他能断你的线，但解不开）。&lt;/p&gt;
&lt;p&gt;跳板还可以串多级：&lt;code&gt;ProxyJump jump1,jump2&lt;/code&gt;，或者在 config 里让 jump2 自己再带 ProxyJump，层层套娃。真到三四层的时候先想想网络拓扑是不是画错了，但功能上确实支持。&lt;/p&gt;
&lt;h3&gt;跳板机本身的安全&lt;/h3&gt;
&lt;p&gt;跳板机是全内网的唯一入口，它的加固标准应该比普通机器更高：只开密钥登录、只允许你的固定来源 IP、fail2ban 拉满——具体做法就是 &lt;a href=&quot;/posts/linux-ssh-hardening/&quot;&gt;SSH 加固篇&lt;/a&gt; 那一整套，一项都别省。另外，跳板机尽量专机专用，别在上面跑业务、别装一堆服务，它的攻击面越小，你的内网越安稳。&lt;/p&gt;
&lt;h2&gt;五、端口转发三兄弟：先看总表&lt;/h2&gt;
&lt;p&gt;端口转发是 SSH 隧道能力的统称：在一条已建立的 SSH 连接里，顺带搬运其他 TCP 流量。三个方向长得像、用途完全不同，先用一张表钉死区别：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;名称&lt;/th&gt;
&lt;th&gt;监听端口开在哪&lt;/th&gt;
&lt;th&gt;流量去向&lt;/th&gt;
&lt;th&gt;一句话场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-L&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;本地转发&lt;/td&gt;
&lt;td&gt;你的电脑&lt;/td&gt;
&lt;td&gt;经服务器到达你指定的目标&lt;/td&gt;
&lt;td&gt;在本地浏览器打开内网的管理页面&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-R&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;远程转发&lt;/td&gt;
&lt;td&gt;服务器&lt;/td&gt;
&lt;td&gt;经你的电脑到达你指定的目标&lt;/td&gt;
&lt;td&gt;把本机的开发服务临时给外网看一眼&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-D&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;动态转发&lt;/td&gt;
&lt;td&gt;你的电脑（SOCKS 代理）&lt;/td&gt;
&lt;td&gt;经服务器访问任意目标&lt;/td&gt;
&lt;td&gt;让本地应用的流量借服务器的网络出去&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;记忆口诀：**L 是把远处的东西拉到本地，R 是把本地的东西推到远处，D 是把整个出口搬到服务器那一侧。**下面逐个上实战。&lt;/p&gt;
&lt;h2&gt;六、-L 本地转发：把内网页面拉到本地浏览器&lt;/h2&gt;
&lt;h3&gt;场景&lt;/h3&gt;
&lt;p&gt;内网有一台机器跑着管理界面（比如数据库管理台、监控面板、内部 Web 服务），监听在 &lt;code&gt;10.0.0.20:8080&lt;/code&gt;，只允许内网访问。你不想为了看它一眼专门开 VPN，也不想把管理页暴露到公网。用 -L：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh -L 18080:10.0.0.20:8080 jump
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拆开看这条命令：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;-L 18080:10.0.0.20:8080&lt;/code&gt;：在本机监听 &lt;code&gt;18080&lt;/code&gt; 端口；凡是连进来的流量，都经这条 SSH 连接送出去，最后由 &lt;strong&gt;jump 这台服务器&lt;/strong&gt;去连接 &lt;code&gt;10.0.0.20:8080&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;中间的目标地址是&lt;strong&gt;以服务器的视角&lt;/strong&gt;写的——&lt;code&gt;10.0.0.20&lt;/code&gt; 是服务器能到达的内网地址，你的电脑不需要能直达它；&lt;/li&gt;
&lt;li&gt;命令执行后你同时登录进了 jump 的 shell，隧道就挂在这条会话上，会话断，隧道断。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;然后打开本地浏览器访问 &lt;code&gt;http://127.0.0.1:18080&lt;/code&gt;，看到的就是内网那台机器的 8080 管理页，全程走加密隧道，管理页本身没有在任何公网上露面。&lt;/p&gt;
&lt;p&gt;同理，数据库也能这么连：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh -L 15432:10.0.0.20:5432 jump
# 本地数据库客户端连 127.0.0.1:15432，实际连的是内网 PostgreSQL
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;几个细节&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;目标写 localhost 的含义&lt;/strong&gt;：&lt;code&gt;ssh -L 18080:localhost:8080 jump&lt;/code&gt; 里的 localhost 指的是 &lt;strong&gt;jump 服务器自己&lt;/strong&gt;，即「服务器本机的 8080」。写内网 IP 还是 localhost，取决于服务到底跑在哪台机器上，这是新手最容易写错的一格。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;只建隧道不登录&lt;/strong&gt;：加 &lt;code&gt;-N&lt;/code&gt; 表示不执行远程命令、只转发；加 &lt;code&gt;-f&lt;/code&gt; 让它转入后台。日常固定用的隧道一般这么写：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;ssh -fN -L 18080:10.0.0.20:8080 jump
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;写进 config 长期用&lt;/strong&gt;：经常访问的映射直接固化：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;Host tunnel-db
    HostName jump.example.com
    User jump_user
    IdentityFile ~/.ssh/id_ed25519_work
    LocalForward 15432 10.0.0.20:5432
    LocalForward 18080 10.0.0.20:8080
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;ssh tunnel-db&lt;/code&gt; 一条命令，登录与两条隧道一起就位。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;验证隧道通没通&lt;/strong&gt;：本地执行 &lt;code&gt;curl -v http://127.0.0.1:18080&lt;/code&gt;，能拿到目标服务的响应（哪怕是 403、登录页）就说明隧道是通的；&lt;code&gt;Connection refused&lt;/code&gt; 先查本地端口有没有在监听：&lt;code&gt;ss -tlnp | grep 18080&lt;/code&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;七、-D 动态转发：一条命令开个 SOCKS 代理&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;ssh -D 1080 rn
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这条命令在你本机开一个 SOCKS5 代理，监听 &lt;code&gt;1080&lt;/code&gt; 端口。把浏览器或某个应用的代理设置指向 &lt;code&gt;127.0.0.1:1080&lt;/code&gt;，它的流量就会经 SSH 隧道从 &lt;code&gt;rn&lt;/code&gt; 这台服务器的网络出口出去——目标网站看到的来源 IP 是服务器的 IP，你和服务器之间的这一段是加密的。&lt;/p&gt;
&lt;p&gt;和 -L 的区别在于：-L 只能预先写死「哪个本地端口对应哪个目标」，-D 不用写死目标，凡是走这个 SOCKS 代理的流量，目的地由应用自己决定，服务器负责逐一连接。所以 -D 适合「让一批应用整体借道」的场景：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;在受限网络里访问只有服务器所在地区能打开的内部系统；&lt;/li&gt;
&lt;li&gt;调试地域相关问题：同一个页面从服务器所在机房看是什么样；&lt;/li&gt;
&lt;li&gt;临时给某个命令行工具指个干净出口：&lt;code&gt;curl --socks5-hostname 127.0.0.1:1080 https://example.com&lt;/code&gt;（&lt;code&gt;--socks5-hostname&lt;/code&gt; 连 DNS 解析都走代理，避免本地 DNS 泄漏与污染干扰）。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;边界要说清：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;-D 给的是一个临时的、单跳的 SOCKS 出口，它不是完整的 VPN。&amp;lt;/span&amp;gt;只有显式配置了代理的应用才走隧道，其余应用照常直连；UDP 流量默认也走不了。把它当「随用随开的调试通道」，别当全局网络方案。&lt;/p&gt;
&lt;p&gt;同样可以 &lt;code&gt;-fN&lt;/code&gt; 后台化：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh -fN -D 1080 rn
# 用完关掉：找到对应进程结束掉，或前台运行时直接 Ctrl+C
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;八、-R 远程转发：把本机服务临时推给服务器一侧&lt;/h2&gt;
&lt;h3&gt;场景&lt;/h3&gt;
&lt;p&gt;你在本机开发了一个 Web 服务（&lt;code&gt;localhost:3000&lt;/code&gt;），想让同事或客户临时看一眼，或者某个回调接口需要一个公网地址能打进来。-R 把监听开在服务器上：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh -R 18000:localhost:3000 rn
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;意思是：在 &lt;code&gt;rn&lt;/code&gt; 服务器上监听 &lt;code&gt;18000&lt;/code&gt; 端口，连进来的流量经隧道回到你的电脑，最终落到你本机的 &lt;code&gt;3000&lt;/code&gt;。对方访问 &lt;code&gt;rn的IP:18000&lt;/code&gt;，看到的就是你本机开发中的页面。&lt;/p&gt;
&lt;p&gt;默认情况下，服务器上的这个监听只绑在服务器的 &lt;code&gt;127.0.0.1&lt;/code&gt; 上，也就是只有登录到服务器的人能访问——这是个很克制的安全默认值。要让外网直接访问，需要服务器 sshd 打开 &lt;code&gt;GatewayPorts yes&lt;/code&gt;，客户端再把绑定地址写明：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh -R 0.0.0.0:18000:localhost:3000 rn
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
-R 是三兄弟里风险最高的一个：它等于把原本只在本机的服务临时挂到了服务器乃至公网上，本机开发服务往往没有认证、开着调试模式、连着测试数据库。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;转发开着的每一分钟，本机服务都等于在公网裸奔。&amp;lt;/span&amp;gt;纪律只有两条：用完立刻关（关掉那条 ssh 会话即可）；需要长期对外提供服务，老老实实走正规部署与反向代理，不要拿 -R 当生产方案。
:::&lt;/p&gt;
&lt;p&gt;另一个常见用途相对温和：你在内网深处有一台机器，想从家里反向连回去——在内网机器上主动向公网服务器发起 &lt;code&gt;ssh -R 12222:localhost:22 jump&lt;/code&gt;，之后在 jump 上 &lt;code&gt;ssh -p 12222 localhost&lt;/code&gt; 就能反向登录那台内网机器。这就是所谓的「反向隧道」，很多远程维护场景靠它续命；用它时同样注意：那条 -R 通道等于给内网开了一个入口，发起方机器与 jump 的账号安全必须自己兜住。&lt;/p&gt;
&lt;h2&gt;九、连接复用：同一台机器的第二次登录为什么慢&lt;/h2&gt;
&lt;p&gt;有没有注意到：对同一台服务器连开几个终端、频繁 &lt;code&gt;scp&lt;/code&gt; 小文件时，每次都要重新走一遍 TCP 连接＋密钥交换＋认证，网络延迟一高就格外磨人。OpenSSH 的连接复用（multiplexing）就是治这个的：第一条连接建立后，后续连接复用同一条通道，认证只做一次。&lt;/p&gt;
&lt;p&gt;在 config 里加三行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Host *
    ControlMaster auto
    ControlPath ~/.ssh/control/%r@%h:%p
    ControlPersist 10m
&lt;/code&gt;&lt;/pre&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ControlMaster auto&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;有现成主连接就复用，没有就新建并充当主连接&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ControlPath&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;主连接的 socket 文件路径，&lt;code&gt;%r&lt;/code&gt;/&lt;code&gt;%h&lt;/code&gt;/&lt;code&gt;%p&lt;/code&gt; 分别代入用户/主机/端口，保证不同机器不串&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ControlPersist 10m&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;主连接在最后一个会话退出后再保留 10 分钟，期间重连秒开&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;需要先建好目录：&lt;code&gt;mkdir -p ~/.ssh/control&lt;/code&gt;。生效后体感非常明显：&lt;code&gt;scp&lt;/code&gt; 连续传文件、Ansible 批量操作、VS Code Remote 这类反复建连的场景都会快一截。可以这样验证复用是否在工作：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh -O check rn    # 显示主连接的进程号说明复用中
ssh -O exit rn     # 手动关闭主连接
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;副作用也要知道一个：主连接活着的时候，你改了 config、换了密钥，后续连接因为走的是老通道，可能「不生效」——排障时先 &lt;code&gt;ssh -O exit&lt;/code&gt; 把主连接关掉再试。另外 socket 文件所在的 &lt;code&gt;~/.ssh/control&lt;/code&gt; 目录权限别放开，拿到 socket 的人等于拿到了你已认证的会话。&lt;/p&gt;
&lt;h2&gt;十、常用参数杂项&lt;/h2&gt;
&lt;p&gt;最后收几个天天用得上的小参数，都可以写进 config 长期生效，也可以临时加在命令行：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;典型值/写法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ServerAliveInterval&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每隔多少秒发一个保活包，防止连接被中间设备当空闲连接掐掉&lt;/td&gt;
&lt;td&gt;&lt;code&gt;60&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ServerAliveCountMax&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;保活包连续多少次无响应判定连接已死&lt;/td&gt;
&lt;td&gt;默认 3，一般不用改&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ExitOnForwardFailure&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;端口转发没绑成功就直接退出，而不是假装连上了&lt;/td&gt;
&lt;td&gt;&lt;code&gt;yes&lt;/code&gt;，写脚本时必开&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-f&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;认证完成后转入后台&lt;/td&gt;
&lt;td&gt;配合 &lt;code&gt;-N&lt;/code&gt; 建纯隧道&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-N&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不执行远程命令、不给 shell&lt;/td&gt;
&lt;td&gt;纯转发专用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-v&lt;/code&gt; / &lt;code&gt;-vvv&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;调试输出，-v 越多越详细&lt;/td&gt;
&lt;td&gt;排障第一手工具&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;StrictHostKeyChecking&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;主机密钥校验策略&lt;/td&gt;
&lt;td&gt;日常保持默认；内网批量装机场景才考虑 &lt;code&gt;accept-new&lt;/code&gt;，别图省事写 &lt;code&gt;no&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Compression yes&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;压缩流量&lt;/td&gt;
&lt;td&gt;高延迟、传文本多的老线路上偶尔有用，现代网络基本无感&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;其中 &lt;code&gt;ServerAliveInterval&lt;/code&gt; 建议直接写进 &lt;code&gt;Host *&lt;/code&gt; 兜底块：长连接挂着跑 &lt;code&gt;tail -f&lt;/code&gt;、看日志、跑长任务时，被运营商或防火墙的 NAT 超时半路掐断是最扫兴的事，60 秒一个保活包基本能根治。&lt;/p&gt;
&lt;h2&gt;十一、排障&lt;/h2&gt;
&lt;h3&gt;1. 端口转发绑不上：&lt;code&gt;cannot listen to port&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;执行带 &lt;code&gt;-L&lt;/code&gt;/&lt;code&gt;-D&lt;/code&gt; 的命令后报 &lt;code&gt;bind: Address already in use&lt;/code&gt; 或 &lt;code&gt;cannot listen to port: 18080&lt;/code&gt;，就是本地那个端口已经被占了。先查是谁占的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ss -tlnp | grep 18080
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;多半是你之前开的隧道没关干净，或者本地正好有别的服务用了同一个口。处理：要么关掉占用者，要么换个本地端口（本地端口号随便选，不影响目标那一侧）。养成习惯：脚本里建隧道一律加上 &lt;code&gt;ExitOnForwardFailure yes&lt;/code&gt;，绑失败立刻报错退出，而不是隧道没建成、命令却「成功」了，后面所有请求打到本地一个莫名其妙的旧服务上，查半天查错方向。&lt;/p&gt;
&lt;p&gt;另一类绑不上在服务器一侧：&lt;code&gt;-R&lt;/code&gt; 远程转发被服务端拒绝，通常是 sshd 配置里 &lt;code&gt;AllowTcpForwarding&lt;/code&gt; 被关了（设为 &lt;code&gt;no&lt;/code&gt; 或 &lt;code&gt;local&lt;/code&gt;）。同理，&lt;code&gt;ProxyJump&lt;/code&gt; 与 &lt;code&gt;-L&lt;/code&gt; 依赖跳板/服务器允许转发，被拒时客户端 &lt;code&gt;-v&lt;/code&gt; 输出里会出现 &lt;code&gt;administratively prohibited&lt;/code&gt; 字样。遇到这行字不要在客户端瞎折腾——这是服务端策略，去改 sshd 配置或找管理员开权限（加固与可用性的取舍，服务端说了算）。&lt;code&gt;ssh -vvv&lt;/code&gt; 看调试输出是定位这类问题的标准动作：它会明确告诉你通道是在哪一步被谁拒绝的。&lt;/p&gt;
&lt;h3&gt;2. 跳板链断了：一节一节查&lt;/h3&gt;
&lt;p&gt;ProxyJump 连不上时，别盯着最终目标猜，按链路逐节验：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh -v jump            # 第一节：本机 → 跳板机，先单独确认能进
ssh -v db-internal     # 第二节：再走完整链路，看 -v 输出卡在哪一跳
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;-v&lt;/code&gt; 输出里会分别打印与跳板机、与目标机的连接和认证过程，卡在哪一节一目了然。常见断点：跳板机的密钥和目标机的密钥不是同一把，而你只在目标机的 Host 块里写了 &lt;code&gt;IdentityFile&lt;/code&gt;——跳板那一节认证失败，整条链就断了（所以示例里两个 Host 块各写各的 &lt;code&gt;IdentityFile&lt;/code&gt;，不要偷懒合并）；或者跳板机只允许从特定来源 IP 连接，你换了网络环境就进不去；再或者目标机地址写的是主机名，而负责解析的是跳板机一侧的 DNS，跳板机解析不了就到不了。&lt;/p&gt;
&lt;h3&gt;3. config 写了不生效&lt;/h3&gt;
&lt;p&gt;按这个顺序自查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;文件位置与权限&lt;/strong&gt;：路径必须是 &lt;code&gt;~/.ssh/config&lt;/code&gt;（当前用户的家目录），权限别超过 644，稳妥起见 600。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;匹配顺序&lt;/strong&gt;：前面说过，同一参数取&lt;strong&gt;第一个&lt;/strong&gt;匹配到的值。把 &lt;code&gt;Host *&lt;/code&gt; 兜底块写在文件开头，是最常见的翻车姿势——把兜底块挪到文件末尾。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;别名对没对上&lt;/strong&gt;：&lt;code&gt;ssh rn&lt;/code&gt; 里的 &lt;code&gt;rn&lt;/code&gt; 必须与 &lt;code&gt;Host rn&lt;/code&gt; 逐字一致；另外注意，参数是按你&lt;strong&gt;敲的别名&lt;/strong&gt;匹配的，不是按 HostName 匹配——你直接 &lt;code&gt;ssh 203.0.113.10&lt;/code&gt; 时，&lt;code&gt;Host rn&lt;/code&gt; 块不会生效（它匹配的是字面量 &lt;code&gt;rn&lt;/code&gt;）。想验证最终生效的配置，用：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;ssh -G rn | grep -E &quot;^(hostname|user|port|identityfile|proxyjump) &quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;ssh -G 别名&lt;/code&gt; 会打印客户端解析后的完整生效配置，排障时比对着看，哪里没生效立刻现形。&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;缩进与语法&lt;/strong&gt;：Host 块内的字段建议统一缩进（不强制，但便于肉眼排版）；字段名大小写不敏感，值别多打空格；一行一个参数，老老实实分行写。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;4. 连接莫名断开&lt;/h3&gt;
&lt;p&gt;长会话频繁断线，先给 config 兜底块加上 &lt;code&gt;ServerAliveInterval 60&lt;/code&gt;（前文已讲）；若是「一断就是在某个固定操作之后」，比如一跑大输出就断，多半是网络 MTU 问题而不是 SSH 的锅，用 &lt;code&gt;-v&lt;/code&gt; 确认断在传输层之后再去查网络。&lt;/p&gt;
&lt;h2&gt;十二、小结&lt;/h2&gt;
&lt;p&gt;这一篇把 SSH 客户端的效率工具一次配齐：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;config 别名&lt;/strong&gt;：&lt;code&gt;~/.ssh/config&lt;/code&gt; 给每台机器起短别名，IP、端口、用户、钥匙全收纳进去，scp/rsync 一并受益；记住「先匹配先算数」，兜底块放最后；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;ssh-agent&lt;/strong&gt;：带密码短语的密钥只输一次密码，安全和便利不必二选一；agent 转发只在可信机器上开；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;跳板机&lt;/strong&gt;：ProxyJump 让内网机器一步直达，认证端到端加密，跳板机只搬运流量，它自身按 &lt;a href=&quot;/posts/linux-ssh-hardening/&quot;&gt;加固篇&lt;/a&gt; 的标准锁死；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;端口转发&lt;/strong&gt;：-L 把内网服务拉到本地，-D 开一个借道服务器出口的 SOCKS，-R 把本机服务临时推出去——用完就关，尤其是 -R；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;连接复用与保活&lt;/strong&gt;：ControlMaster 让重复连接秒开，ServerAliveInterval 让长连接不被半路掐断。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;把这几样配好之后，多台服务器在你手里就不再是十几条记不住的命令，而是一组敲别名就能进、内网一步直达、服务随手借道的顺手工具。&lt;/p&gt;
</content:encoded></item><item><title>SSH 安全加固实战</title><link>https://www.anexns.cloudns.org/posts/linux-ssh-hardening/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-ssh-hardening/</guid><description>公网上的 SSH 天天被人扫：密钥登录的完整配置、sshd 关键选项逐个讲、改端口的真实作用、Fail2ban 自动封禁，以及改配置时别把自己锁在门外的操作纪律。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;服务器只要上了公网，SSH 的 22 端口从第一天起就在被人扫。这不是危言耸听，而是任何一台公网 Linux 的日常：全世界的扫描器和僵尸网络 24 小时轮着敲门，试 root、试 admin、试各种弱口令字典。你的密码只要够长、够随机，短期内确实爆破不动，但「敲门声」会一直存在，而且人总有疏忽的时候——某天为了图方便设了个简单密码，某次把密码复用到了别的泄露过的站点，防线就破了。&lt;/p&gt;
&lt;p&gt;这一篇的目标，是把 SSH 从「靠密码硬扛」升级成「根本不给爆破留入口」：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;SSH 加固的核心是关掉密码登录、只留密钥，再用最小暴露和自动封禁把噪音挡在外面&amp;lt;/span&amp;gt;。全篇以 Debian 为主线，步骤依次是：先看清威胁现状，再立操作纪律，然后配密钥登录、逐条过 sshd 的关键选项、聊改端口的真实作用、装 Fail2ban 自动封禁，最后是排障。顺序不要乱，尤其是纪律那一节，先看完再动手。&lt;/p&gt;
&lt;h2&gt;一、威胁现状：先看看你的门被敲了多少次&lt;/h2&gt;
&lt;p&gt;动手加固之前，先花两分钟确认一下现状，你会对「爆破是常态」这件事有直观感受。&lt;/p&gt;
&lt;p&gt;Debian 上 SSH 的登录日志默认记在 &lt;code&gt;/var/log/auth.log&lt;/code&gt; 里。看失败记录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;grep &quot;Failed password&quot; /var/log/auth.log | tail -20
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;典型输出长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Failed password for root from 203.0.113.17 port 51234 ssh2
Failed password for invalid user admin from 198.51.100.23 port 40211 ssh2
Failed password for invalid user oracle from 192.0.2.99 port 33108 ssh2
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;invalid user&lt;/code&gt; 是对方在试你系统里根本不存在的用户名（admin、oracle、test、ubuntu……都是字典里的常客），不带 &lt;code&gt;invalid user&lt;/code&gt; 的则是直接在撞 root 或你真实存在的账号。再看看失败总次数，感受一下频率：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;grep -c &quot;Failed password&quot; /var/log/auth.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;一台刚上线几天的公网机器，这个数字到几千上万都很正常。另一个命令 &lt;code&gt;lastb&lt;/code&gt; 专门列出所有失败的登录尝试（需要 root 权限，本质是读 &lt;code&gt;/var/log/btmp&lt;/code&gt;）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;lastb | head -20
lastb | wc -l
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;相对地，&lt;code&gt;last&lt;/code&gt; 看的是成功登录记录。加固做完之后，养成偶尔扫一眼 &lt;code&gt;last&lt;/code&gt; 的习惯：里面出现的每一条都应该是你自己的 IP，冒出陌生地址就是出事了。&lt;/p&gt;
&lt;p&gt;还要说明一点：这些爆破绝大多数是自动化脚本，不针对你个人，它们扫的是整个 IP 段。所以「我的服务器上没什么值钱东西，不会有人盯上」这个想法不成立——脚本不在乎你是谁，爆破成功后你的机器会被自动拉进僵尸网络去挖矿、发垃圾邮件或者继续扫别人，云厂商收到投诉后封的是你的号。&lt;/p&gt;
&lt;h2&gt;二、操作纪律：改 sshd 之前，先给自己留后路&lt;/h2&gt;
&lt;p&gt;SSH 加固最常见的事故不是被黑，而是把自己锁在门外。sshd 配置写错一个字、密钥没配好就关了密码、改了端口忘了放行防火墙——任何一个都能让你对自己的服务器失联。所以正式动手前，先立三条纪律：&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;在确认新配置能正常登录之前，绝不要关闭当前已经登录的会话&amp;lt;/span&amp;gt;，更不要在改完配置后立刻退出重连试运气。正确姿势是：保留当前会话不动，另开一个新窗口验证新配置能登录成功，验证通过后再关旧会话。
:::&lt;/p&gt;
&lt;p&gt;第一条就是上面这条：&lt;strong&gt;双会话验证&lt;/strong&gt;。改配置、重启服务，全程留着老会话；新开一个终端窗口试登录，成功了才算数。老会话是你唯一的后悔药。&lt;/p&gt;
&lt;p&gt;第二条：&lt;strong&gt;每次改完 &lt;code&gt;sshd_config&lt;/code&gt;，先校验再重载&lt;/strong&gt;。sshd 自带配置检查：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sshd -t
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;没有任何输出就是语法没问题；有问题会明确指出哪一行错了。校验通过后用 reload 而不是 restart——reload 只让 sshd 重新读配置，不会断开已建立的连接：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl reload ssh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;sshd -t&lt;/code&gt; 不通过时&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不要强行 restart 服务&amp;lt;/span&amp;gt;：配置错误时 sshd 可能直接起不来，当前会话一断，你就只能靠云厂商控制台去修了。先把配置改对、校验过了再 reload，这一步没有例外。
:::&lt;/p&gt;
&lt;p&gt;第三条：&lt;strong&gt;记住你的救命通道在哪&lt;/strong&gt;。各家云厂商都提供网页版控制台（VNC / 救援模式 / 串口终端），不依赖 SSH 就能进系统。动手加固之前，先登录一次云厂商后台，确认这个入口能打开、账号密码能用。真把 SSH 玩坏了，就从这里进去改回配置。另外，Debian 云镜像一般还可以在控制台用 root 或默认用户加密码登录（前提是没在系统层面禁用），这条路也提前确认好。&lt;/p&gt;
&lt;h2&gt;三、密钥登录全流程：从生成到关密码&lt;/h2&gt;
&lt;p&gt;密钥登录的原理一句话：你的电脑上生成一对密钥，私钥自己留着，公钥放到服务器上；登录时服务器用公钥出题、私钥答题，答对放行。私钥文件不经过网络传输，也没法靠猜——一个 Ed25519 私钥的暴力破解在现实时间里不可行，这正是它比密码强的地方。&lt;/p&gt;
&lt;h3&gt;3.1 在本地生成密钥对&lt;/h3&gt;
&lt;p&gt;在你自己的电脑上（不是服务器上）执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh-keygen -t ed25519 -C &quot;my-laptop&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;-t ed25519&lt;/code&gt;：算法选 Ed25519，密钥短、速度快、安全性足够，是现在新生成的默认推荐；老教程里的 RSA 3072/4096 也能用，但没有理由再新生成 RSA 了。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;-C&lt;/code&gt; 是注释，写个能认出这把钥匙属于哪台设备的备注，钥匙多了不迷糊。&lt;/li&gt;
&lt;li&gt;中途会问保存路径，默认 &lt;code&gt;~/.ssh/id_ed25519&lt;/code&gt; 直接回车；会问 passphrase（给私钥再套一层口令），建议设置，这样私钥文件就算被拷走也用不了。怕每次登录都要输的话，配合 ssh-agent 用，后面一句带过。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;生成后得到两个文件：&lt;code&gt;id_ed25519&lt;/code&gt; 是私钥，&lt;code&gt;id_ed25519.pub&lt;/code&gt; 是公钥。私钥文件绝不能发给任何人、传到任何网盘或聊天窗口里，需要上服务器的只有 &lt;code&gt;.pub&lt;/code&gt; 公钥。&lt;/p&gt;
&lt;h3&gt;3.2 把公钥送上服务器&lt;/h3&gt;
&lt;p&gt;最省事的方法是 &lt;code&gt;ssh-copy-id&lt;/code&gt;（本地是 Linux/macOS 时自带或可装）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh-copy-id -i ~/.ssh/id_ed25519.pub user@服务器IP
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它会让你输一次服务器密码，然后把公钥追加到服务器的 &lt;code&gt;~/.ssh/authorized_keys&lt;/code&gt; 里，并自动修好权限。如果本地是 Windows 或者 &lt;code&gt;ssh-copy-id&lt;/code&gt; 不可用，就手动来：先在服务器上（用密码登录）建目录，然后把公钥内容粘进 &lt;code&gt;authorized_keys&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo &quot;ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... my-laptop&quot; &amp;gt;&amp;gt; ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意这里的权限不是走过场。sshd 默认开启 &lt;code&gt;StrictModes&lt;/code&gt; 检查：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;家目录、&lt;code&gt;.ssh&lt;/code&gt; 目录或 &lt;code&gt;authorized_keys&lt;/code&gt; 文件权限过宽（组或其他用户可写）时，sshd 会直接拒绝使用该密钥&amp;lt;/span&amp;gt;，而且日志里只留一句不起眼的 &lt;code&gt;Authentication refused: bad ownership or modes&lt;/code&gt;。标准权限记死：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;路径&lt;/th&gt;
&lt;th&gt;权限&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;~/.ssh&lt;/code&gt; 目录&lt;/td&gt;
&lt;td&gt;700&lt;/td&gt;
&lt;td&gt;只有自己能进&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;~/.ssh/authorized_keys&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;600&lt;/td&gt;
&lt;td&gt;只有自己能读写&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;家目录 &lt;code&gt;~&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不超过 755&lt;/td&gt;
&lt;td&gt;不能对组/其他用户可写&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;3.3 验证密钥能登录——然后再关密码&lt;/h3&gt;
&lt;p&gt;保持老会话不动，新开窗口试登录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh user@服务器IP
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果配了 passphrase 会让你输 passphrase（这是私钥的口令，不是服务器密码）。登录成功后，再用一条命令确认走的确实是密钥：加 &lt;code&gt;-v&lt;/code&gt; 看调试输出，出现 &lt;code&gt;Offering public key&lt;/code&gt; 和 &lt;code&gt;Authentication succeeded (publickey)&lt;/code&gt; 即对。或者更干脆，指定只用密钥、禁止回退密码：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh -o PasswordAuthentication=no user@服务器IP
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这条能登进去，就证明密钥链路完整。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;必须在这一步验证通过之后，才能去关密码登录&amp;lt;/span&amp;gt;；顺序反过来，先关密码再发现密钥有问题，就是标准的把自己锁在门外。&lt;/p&gt;
&lt;p&gt;日常使用想少输 passphrase：在本地启用 ssh-agent 并把钥匙加进去一次，本次开机周期内就不用反复输了：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;eval &quot;$(ssh-agent -s)&quot;
ssh-add ~/.ssh/id_ed25519
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;macOS 和多数桌面 Linux 有自己的钥匙串集成，效果类似，这里不展开。&lt;/p&gt;
&lt;h2&gt;四、sshd_config 关键选项逐条讲&lt;/h2&gt;
&lt;p&gt;配置文件是 &lt;code&gt;/etc/ssh/sshd_config&lt;/code&gt;。Debian 的新版本还支持把自定义配置单独放进 &lt;code&gt;/etc/ssh/sshd_config.d/&lt;/code&gt; 目录（主文件顶部有 &lt;code&gt;Include&lt;/code&gt; 时生效），好处是改动和系统默认分开、升级不冲突。下面逐条讲最关键的几个选项，都按「选项 / 推荐值 / 理由」过一遍，最后给一份可直接用的配置段。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;选项&lt;/th&gt;
&lt;th&gt;推荐值&lt;/th&gt;
&lt;th&gt;理由&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;PermitRootLogin&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;prohibit-password&lt;/code&gt; 或 &lt;code&gt;no&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;禁止 root 用密码登录；还想用 root 密钥直登就用 &lt;code&gt;prohibit-password&lt;/code&gt;（只许密钥），日常用普通用户加 sudo 的话直接 &lt;code&gt;no&lt;/code&gt; 最干净&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;PasswordAuthentication&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;no&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;关掉密码登录，爆破彻底失去意义——这是全篇最重要的一条&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;PubkeyAuthentication&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;yes&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;密钥登录总开关，保持开启（默认就是 yes，写出来是明示不被别处覆盖）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;MaxAuthTries&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;3&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;单次连接最多试 3 次就断开，压缩脚本的尝试效率，默认 6 偏宽&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;LoginGraceTime&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;30&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;连接建立后 30 秒内完不成认证就断开，防止大量半开连接占坑，默认 120 偏长&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;AllowUsers&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;AllowUsers yourname&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;白名单：只允许列出的用户走 SSH，系统里其他账号（各种服务账号）连试的机会都没有&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;X11Forwarding&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;no&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;服务器上没人跑图形界面转发，关掉减少攻击面，默认在 Debian 是 no，确认一遍&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;PermitEmptyPasswords&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;no&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;禁止空密码账号登录，默认就是 no，同样确认一遍&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;另外两个值得知道但不必乱改的：&lt;code&gt;MaxStartups&lt;/code&gt; 控制未完成认证的并发连接数，默认值在被猛扫时可能误伤正常登录，日志里出现 &lt;code&gt;drop connection&lt;/code&gt; 字样再考虑调大；&lt;code&gt;ClientAliveInterval&lt;/code&gt; 是服务端保活探测，和安全关系不大，别和加固混为一谈。&lt;/p&gt;
&lt;p&gt;汇总成配置段，可以放到 &lt;code&gt;/etc/ssh/sshd_config.d/60-hardening.conf&lt;/code&gt;（若主文件没有 Include，就直接改主文件末尾，注意 sshd 对同一选项取&lt;strong&gt;第一个&lt;/strong&gt;读到的值，所以放主文件时要确认前面没有同名选项已经设过）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;PermitRootLogin prohibit-password
PasswordAuthentication no
PubkeyAuthentication yes
MaxAuthTries 3
LoginGraceTime 30
AllowUsers yourname
X11Forwarding no
PermitEmptyPasswords no
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改完照例三步：&lt;code&gt;sshd -t&lt;/code&gt; 校验、&lt;code&gt;systemctl reload ssh&lt;/code&gt;、新开窗口验证登录。验证时重点确认两件事：密钥能登进去；密码登录确实被拒（用 &lt;code&gt;ssh -o PreferredAuthentications=password -o PubkeyAuthentication=no user@服务器IP&lt;/code&gt; 试一次，应该直接被拒绝）。&lt;/p&gt;
&lt;p&gt;还有一个习惯要养成：改之前先备份，&lt;code&gt;cp /etc/ssh/sshd_config /etc/ssh/sshd_config.bak&lt;/code&gt;。真改出问题，从云控制台进来一条命令就能还原。&lt;/p&gt;
&lt;h2&gt;五、改端口：降噪有效，但别把它当安全措施&lt;/h2&gt;
&lt;p&gt;把 SSH 从 22 改到一个高位端口（比如 2222、22022、3526 之类），是流传最广的「加固技巧」，但要先把它的定位说清楚：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;改端口只是降噪，不是安全本身&amp;lt;/span&amp;gt;。它挡掉的是无差别全网扫描的脚本——这些脚本只扫 22 端口，换了端口，&lt;code&gt;auth.log&lt;/code&gt; 立刻清净，Fail2ban 也少干很多活。但针对性的扫描器把 65535 个端口全扫一遍也就几分钟，扫到你的新端口后，该爆破还是爆破。所以改端口可以改，但它排在密钥登录之后，是锦上添花，不是雪中送炭。&lt;/p&gt;
&lt;p&gt;改法本身很简单，配置里加一行（Debian 默认配置里 &lt;code&gt;Port 22&lt;/code&gt; 是注释状态）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Port 22022
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后三件事一件不能少：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;防火墙同步放行新端口&lt;/strong&gt;。如果你用 UFW 或 nftables 只放行了 22，先放行新端口、验证新端口能登录之后，再关掉 22 的放行。顺序反了照样锁门。云厂商的安全组/防火墙规则同样要改，那是在系统之外的另一层，别忘了。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;sshd -t&lt;/code&gt; 校验后 reload。&lt;/li&gt;
&lt;li&gt;登录命令带上新端口验证：&lt;code&gt;ssh -p 22022 user@服务器IP&lt;/code&gt;，并在本地 &lt;code&gt;~/.ssh/config&lt;/code&gt; 里给这台机器写好 &lt;code&gt;Port&lt;/code&gt;，以后就不用每次敲。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;Debian 的一个特有坑：socket 激活&lt;/h3&gt;
&lt;p&gt;在 Debian 12 及更新版本上，OpenSSH 可能以 &lt;strong&gt;systemd socket 激活&lt;/strong&gt;方式运行：真正监听端口的不是 sshd 进程本身，而是 systemd 的 &lt;code&gt;ssh.socket&lt;/code&gt; 单元，sshd 被连接触发才拉起来。这种模式下，&lt;strong&gt;只改 &lt;code&gt;sshd_config&lt;/code&gt; 里的 &lt;code&gt;Port&lt;/code&gt; 可能不生效&lt;/strong&gt;，因为监听套接字归 systemd 管，sshd 配置里的端口设置被架空了——表现就是你改了端口、reload 了，新端口连不上，老端口还在。&lt;/p&gt;
&lt;p&gt;先确认自己是不是 socket 激活：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl is-enabled ssh.socket
systemctl status ssh.socket
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果 &lt;code&gt;ssh.socket&lt;/code&gt; 处于启用/监听状态，改端口要改它。推荐做法是给 socket 写一个 override，把监听端口换掉：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl edit ssh.socket
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;在编辑区里写入（第一行空的 &lt;code&gt;ListenStream=&lt;/code&gt; 是清空原有监听，必须写，否则是追加多一个端口）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Socket]
ListenStream=
ListenStream=22022
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;保存后执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl daemon-reload
systemctl restart ssh.socket
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再用 &lt;code&gt;ss -tlnp | grep 22022&lt;/code&gt; 确认新端口已经在监听，然后按前面的纪律新开窗口验证。另一条路线是彻底关掉 socket 激活、回到传统服务模式：&lt;code&gt;systemctl disable --now ssh.socket&lt;/code&gt; 并 &lt;code&gt;systemctl enable --now ssh.service&lt;/code&gt;，之后端口就完全由 &lt;code&gt;sshd_config&lt;/code&gt; 说了算。两种方式选一种，别让两个单元同时存在抢端口。&lt;/p&gt;
&lt;h2&gt;六、Fail2ban：让爆破脚本自动吃闭门羹&lt;/h2&gt;
&lt;p&gt;关掉密码登录之后，爆破其实已经伤不到你了，但日志噪音和连接消耗还在。Fail2ban 的活就是收尾：它盯着日志，某个 IP 在短时间内失败次数超标，就调用防火墙把这个 IP 封一段时间。装它不是为了补安全的窟窿，而是为了让日志干净、让扫描器知难而退。&lt;/p&gt;
&lt;p&gt;安装：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apt update
apt install -y fail2ban
systemctl enable --now fail2ban
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;配置不要改默认的 &lt;code&gt;jail.conf&lt;/code&gt;（升级会被覆盖），自己新建 &lt;code&gt;/etc/fail2ban/jail.local&lt;/code&gt;，写一个 sshd 的 jail：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[sshd]
enabled = true
port = 22022
maxretry = 5
findtime = 10m
bantime = 1h
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐行讲：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;配置项&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;enabled = true&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;启用这个 jail&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;port = 22022&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;封禁时封哪个端口，要和你 SSH 实际端口一致（没改端口就写 &lt;code&gt;ssh&lt;/code&gt; 或 22）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;maxretry = 5&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;失败次数上限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;findtime = 10m&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;统计窗口：在 10 分钟内失败达到 &lt;code&gt;maxretry&lt;/code&gt; 次就触发&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;bantime = 1h&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;封禁时长，1 小时；想更狠可以 &lt;code&gt;1d&lt;/code&gt;，甚至对屡犯者用后面说的加重策略&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;意思是：同一 IP 10 分钟内 SSH 登录失败 5 次，封 1 小时。改完重启服务生效：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl restart fail2ban
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;查看状态和已封的 IP：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;fail2ban-client status
fail2ban-client status sshd
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;后者会列出当前封禁名单、累计封禁数、失败计数。手动解封某个 IP（比如误封了自己）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;fail2ban-client set sshd unbanip 203.0.113.17
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;手动封一个：&lt;code&gt;fail2ban-client set sshd banip 203.0.113.17&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;和密钥登录的分工要理清：&lt;strong&gt;密钥登录是城墙，Fail2ban 是巡逻队&lt;/strong&gt;。城墙没修好（还开着密码），巡逻队封得再勤，脚本换个 IP 继续撞，总有撞开的一天；城墙修好了（密码已关），巡逻队就是纯粹的降噪和减负。两者都要，但主次不能颠倒。进阶一点还可以开 Fail2ban 的 recidive jail，专门盯「被封过又来」的惯犯并加重封禁时长，在 &lt;code&gt;jail.local&lt;/code&gt; 里加一段 &lt;code&gt;[recidive] enabled = true&lt;/code&gt; 并适当拉长其 &lt;code&gt;bantime&lt;/code&gt; 即可，参数含义与上面一致。&lt;/p&gt;
&lt;p&gt;最后提醒一句：把自己的常用 IP 加进白名单能避免手滑把自己封掉，在 &lt;code&gt;jail.local&lt;/code&gt; 的 &lt;code&gt;[DEFAULT]&lt;/code&gt; 段里加 &lt;code&gt;ignoreip = 127.0.0.1/8 你的固定公网IP&lt;/code&gt;。但家庭宽带 IP 经常变，加错了旧 IP 没意义，这条按需使用。&lt;/p&gt;
&lt;h2&gt;七、进阶方向（一句带过）&lt;/h2&gt;
&lt;p&gt;上面这套做完，已经超过绝大多数公网服务器的安全水位。再往上还有三层，按需取用：&lt;strong&gt;双因素认证&lt;/strong&gt;——给 SSH 再叠一层 TOTP 动态口令（&lt;code&gt;libpam-google-authenticator&lt;/code&gt;），私钥之外还要输手机上的验证码；&lt;strong&gt;跳板机&lt;/strong&gt;——所有服务器只允许从一台跳板机登录，暴露面收敛到一个点集中加固；&lt;strong&gt;限制来源 IP&lt;/strong&gt;——防火墙或云安全组里只放行你常用的出口 IP 段访问 SSH 端口，效果最直接，但 IP 不固定的人用不了。这三样都建立在密钥登录已经完成的基础上，别跳级。&lt;/p&gt;
&lt;h2&gt;八、排障&lt;/h2&gt;
&lt;h3&gt;8.1 改完配置连不上了&lt;/h3&gt;
&lt;p&gt;按顺序查，别慌，老会话还在就先在老会话里查；老会话也没了就走云控制台：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;配置语法：&lt;code&gt;sshd -t&lt;/code&gt;，报错会指到具体行，改对再 reload。&lt;/li&gt;
&lt;li&gt;服务状态：&lt;code&gt;systemctl status ssh&lt;/code&gt; 看是否在运行；socket 激活的机器再看 &lt;code&gt;ssh.socket&lt;/code&gt; 状态。&lt;/li&gt;
&lt;li&gt;端口监听：&lt;code&gt;ss -tlnp | grep ssh&lt;/code&gt; 或按端口号 grep，确认 sshd（或 systemd）确实在目标端口上听。&lt;/li&gt;
&lt;li&gt;防火墙：系统内的 UFW/nftables 规则和云厂商安全组，两层都要放行新端口——&lt;strong&gt;改端口后连不上，十有八九卡在这里&lt;/strong&gt;。&lt;/li&gt;
&lt;li&gt;还原：把备份的 &lt;code&gt;sshd_config.bak&lt;/code&gt; 覆盖回去，reload，先恢复登录再慢慢找原因。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;8.2 密钥放上去了，登录时还提示输密码&lt;/h3&gt;
&lt;p&gt;提示输密码说明密钥认证没走通、回退到了密码。逐项对照：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;权限：服务器上 &lt;code&gt;~/.ssh&lt;/code&gt; 是不是 700、&lt;code&gt;authorized_keys&lt;/code&gt; 是不是 600、家目录有没有对组可写。日志里搜 &lt;code&gt;Authentication refused: bad ownership or modes&lt;/code&gt;，搜到就是它。&lt;/li&gt;
&lt;li&gt;公钥内容：&lt;code&gt;authorized_keys&lt;/code&gt; 里那行有没有被粘贴断行、开头是不是完整的 &lt;code&gt;ssh-ed25519&lt;/code&gt;。一行就是一行，断行即废。&lt;/li&gt;
&lt;li&gt;送错用户：公钥送到了 root 的家目录，却在用普通用户登录（或反过来）。&lt;code&gt;authorized_keys&lt;/code&gt; 是按登录用户各一份的。&lt;/li&gt;
&lt;li&gt;服务端没开：&lt;code&gt;PubkeyAuthentication&lt;/code&gt; 被别处设成了 no，或者 &lt;code&gt;AllowUsers&lt;/code&gt; 没包含你。&lt;code&gt;sshd -T | grep -i pubkey&lt;/code&gt; 可以看最终生效值。&lt;/li&gt;
&lt;li&gt;客户端没递对钥匙：本地有多把密钥时，用 &lt;code&gt;ssh -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes user@服务器IP&lt;/code&gt; 明确指定再看。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;实在定位不到，开调试模式看全程：客户端 &lt;code&gt;ssh -vvv&lt;/code&gt;，服务端临时跑一个前台调试实例 &lt;code&gt;sshd -d -p 2222&lt;/code&gt; 用另一个端口复现，输出会把拒绝原因写得明明白白。&lt;/p&gt;
&lt;h3&gt;8.3 Fail2ban 把自己封了&lt;/h3&gt;
&lt;p&gt;表现：密码/密钥都没改，突然连不上，ping 得通、其他端口也通，唯独 SSH 超时或被拒。先换一个网络（比如手机热点）试登，能登进去就是原 IP 被封了。处理：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;fail2ban-client status sshd
fail2ban-client set sshd unbanip 你的公网IP
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后复盘为什么被封：多半是自己输错几次密码（还没关密码时）、或者客户端拿着错密钥反复重试。关掉密码登录后这种情况会大幅减少，因为密钥试错不经过密码失败计数。另外确认 Fail2ban 的封禁动作和你用的防火墙兼容，&lt;code&gt;fail2ban-client status sshd&lt;/code&gt; 里能正常列出 Banned IP 列表，说明封禁链路是通的。&lt;/p&gt;
&lt;h3&gt;8.4 新端口死活连不上、老端口却还在&lt;/h3&gt;
&lt;p&gt;典型的 socket 激活坑，回到第五节：检查 &lt;code&gt;ssh.socket&lt;/code&gt; 是否在监听老端口，给它写 &lt;code&gt;ListenStream&lt;/code&gt; override 或者干脆禁用 socket 激活改用 &lt;code&gt;ssh.service&lt;/code&gt;，&lt;code&gt;ss -tlnp&lt;/code&gt; 验证监听端口和配置一致为止。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇的动作按优先级收拢一下：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;纪律先行&lt;/strong&gt;：留老会话、&lt;code&gt;sshd -t&lt;/code&gt; 校验再 reload、确认云控制台救命通道可用——这三条决定了你出事时还有没有救。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;密钥登录是核心&lt;/strong&gt;：Ed25519 生成密钥、公钥上服务器、权限 700/600 卡死、验证密钥能登录之后再动密码开关。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;sshd 选项收口&lt;/strong&gt;：&lt;code&gt;PasswordAuthentication no&lt;/code&gt; 最重要，root 登录收紧、&lt;code&gt;MaxAuthTries&lt;/code&gt; 和 &lt;code&gt;LoginGraceTime&lt;/code&gt; 压一压、&lt;code&gt;AllowUsers&lt;/code&gt; 白名单能加就加。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;改端口是降噪&lt;/strong&gt;：改了记得防火墙和云安全组同步放行；Debian 上先查 socket 激活，别改了个寂寞。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fail2ban 收尾&lt;/strong&gt;：&lt;code&gt;jail.local&lt;/code&gt; 里管好 sshd jail，失败 5 次封 1 小时起步，自己被封会解封。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;做完这一套，你的 SSH 就从「每天被几千次敲门、全靠密码硬扛」变成「没有密码可撞、敲门声也被巡逻队赶走了」。下一篇我们处理另一道门：防火墙，把整台服务器的端口暴露面系统地收一遍。&lt;/p&gt;
</content:encoded></item><item><title>系统救援与启动排障</title><link>https://www.anexns.cloudns.org/posts/linux-system-rescue/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-system-rescue/</guid><description>机器起不来时别慌：启动流程速通、fstab 写错与磁盘满这两大死法、GRUB 进单用户与 Live 介质 chroot 修复，再用一份预防清单收束整个 Linux 系列。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h1&gt;系统救援与启动排障&lt;/h1&gt;
&lt;p&gt;这是本系列的最后一篇，讲的是一件谁都不想遇上、但迟早会遇上的事：&lt;strong&gt;服务器起不来了&lt;/strong&gt;。重启之后 SSH 连不上，面板上点重启也没用，屏幕（或者云厂商的控制台）上停着一堆看不懂的报错。这一刻最容易做的事是慌，最该做的事是按顺序排查。&lt;/p&gt;
&lt;p&gt;好消息是，Linux 起不来的原因翻来覆去就那么几类：启动配置文件写错、磁盘满了、内核升级翻车、文件系统损坏。本篇的主线就是这四类——先用一张启动流程图把「卡在哪一步」定位出来，再逐个给出修法：&lt;code&gt;fstab&lt;/code&gt; 写错怎么救、磁盘满怎么腾、怎么从 GRUB 进单用户模式、实在不行怎么用 Live 介质 &lt;code&gt;chroot&lt;/code&gt; 进去修。最后一节是一份预防清单，把整个系列讲过的纪律串起来——因为救援的最高境界，是根本用不上救援。&lt;/p&gt;
&lt;h2&gt;一、先立规矩：救援时的三条总原则&lt;/h2&gt;
&lt;p&gt;动手之前，先把三条原则刻在脑子里。救援现场最贵的学费，几乎都不是「不会修」，而是「修的时候又捅了新篓子」。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一，先看日志和报错，再动手。&lt;/strong&gt; 屏幕上滚过去的每一行字都是线索：卡在哪个阶段、哪个服务报了什么错、内核有没有 panic。先拍照或截图（云控制台一般有截图功能），再开始敲命令。凭感觉乱试的结果，是把一个小问题试成三个问题，最后连原始现场都没了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二，改任何关键文件之前先备份。&lt;/strong&gt; 这里说的关键文件包括 &lt;code&gt;/etc/fstab&lt;/code&gt;、网络配置、SSH 配置、GRUB 配置。备份动作只需要一条命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cp /etc/fstab /etc/fstab.bak.$(date +%F)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;十秒钟的事，能在你改错之后把系统一键还原回「只是起不来」而不是「彻底救不回」。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;救援时禁止不留备份直接改系统关键文件&amp;lt;/span&amp;gt;，这条没有例外。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三，云服务器先确认控制台通道可用。&lt;/strong&gt; 云上的机器没有显示器和键盘，你的双手就是厂商提供的 VNC 控制台、串口控制台或者救援模式入口。平时用不上，但真出事时这是唯一的门。买了新云服务器之后，花两分钟登录一次控制台确认能进、密码对——别等机器起不来那天，才发现控制台还要工单开通。&lt;/p&gt;
&lt;p&gt;把这三条记住，下面进入正题。&lt;/p&gt;
&lt;h2&gt;二、启动流程速通：先知道卡在哪一步&lt;/h2&gt;
&lt;p&gt;定位故障的第一步，是知道 Linux 的启动是一条什么样的流水线。整条链可以拆成四个阶段，每个阶段卡住时的表现完全不同，对照着看，故障范围立刻缩小一半。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;阶段&lt;/th&gt;
&lt;th&gt;负责什么&lt;/th&gt;
&lt;th&gt;卡住时的典型表现&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;固件（BIOS/UEFI）&lt;/td&gt;
&lt;td&gt;硬件自检、找到启动盘、加载引导程序&lt;/td&gt;
&lt;td&gt;黑屏、无任何 Linux 字样、提示找不到启动设备&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GRUB&lt;/td&gt;
&lt;td&gt;显示启动菜单、加载选定的内核与 initramfs&lt;/td&gt;
&lt;td&gt;停在 &lt;code&gt;grub&amp;gt;&lt;/code&gt; 或 &lt;code&gt;grub rescue&amp;gt;&lt;/code&gt; 提示符、菜单里找不到系统&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;内核 + initramfs&lt;/td&gt;
&lt;td&gt;内核初始化硬件、挂载根文件系统、移交控制权&lt;/td&gt;
&lt;td&gt;滚动一堆内核日志后停住、Kernel panic、掉进 initramfs 的 &lt;code&gt;(initramfs)&lt;/code&gt; shell&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;systemd&lt;/td&gt;
&lt;td&gt;按 target 拉起全部服务、挂载 fstab、开 SSH&lt;/td&gt;
&lt;td&gt;进了 emergency mode、某个服务反复失败、能 ping 通但 SSH 不通&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个判读要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;连 GRUB 菜单都没见到&lt;/strong&gt;，问题在固件或引导层面：启动盘顺序错了、引导记录坏了、或者（云上）系统盘根本没挂上。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;见到 GRUB 菜单、选完内核就黑屏或 panic&lt;/strong&gt;，问题多半在新内核本身，或者 initramfs 没生成好——这是内核升级翻车的典型长相，后面第七节专门讲。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;掉进 &lt;code&gt;(initramfs)&lt;/code&gt; 提示符&lt;/strong&gt;，说明内核起来了但挂不上根文件系统：根分区 UUID 对不上、文件系统损坏、或者 LVM/加密卷没解锁。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;能进系统但在 emergency mode 停住&lt;/strong&gt;，多半是 &lt;code&gt;fstab&lt;/code&gt; 里某块盘挂不上，或者某个关键服务启动失败——这是最常见也最容易修的一种。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;云服务器还有一个特殊点：很多厂商的控制台默认不显示 GRUB 菜单，或者菜单只闪 1 秒。遇到「控制台一片黑、但机器 ping 得通」时，先别断定系统死了，可能只是显示输出去了串口或者菜单已经过去了。&lt;/p&gt;
&lt;h2&gt;三、看启动日志：系统自己写的病历&lt;/h2&gt;
&lt;p&gt;只要还能进到任何一种 shell（正常系统、rescue 模式、emergency 模式都行），第一件事就是翻日志。&lt;code&gt;journalctl&lt;/code&gt; 是 systemd 的日志工具，启动排障有三个参数必须会：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 看本次启动的日志，只看错误级别以上的
journalctl -xb -p err

# 看上一次启动的日志（这次就是被上次的故障重启进来的）
journalctl -b -1 -p err

# 列出系统里留存了几次启动的记录
journalctl --list-boots
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;-x&lt;/code&gt; 会给日志条目附上解释说明，排障时很有用；&lt;code&gt;-b -1&lt;/code&gt; 是精髓——机器起不来被你强制重启之后，本次启动的日志里什么都没有，&lt;strong&gt;上一次卡死时的日志&lt;/strong&gt;才是案发现场。&lt;/p&gt;
&lt;p&gt;如果系统停在半路进不了 shell，还有两个 systemd 自带的避难所，名字很像，务必分清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;模式&lt;/th&gt;
&lt;th&gt;是什么&lt;/th&gt;
&lt;th&gt;能干什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;rescue 模式（rescue.target）&lt;/td&gt;
&lt;td&gt;单用户模式：根文件系统已挂载读写，基础服务就位，网络等服务大多没起&lt;/td&gt;
&lt;td&gt;改配置、修服务、查日志，日常救援的主力&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;emergency 模式（emergency.target）&lt;/td&gt;
&lt;td&gt;紧急模式：只挂载了根文件系统且常常是只读，连 journal 都可能不完整&lt;/td&gt;
&lt;td&gt;最后的落脚点，通常是系统自动掉进来的，先 remount 读写再动手&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;系统在启动失败时&lt;strong&gt;自动&lt;/strong&gt;把你扔进 emergency mode 并提示 &lt;code&gt;Give root password for maintenance&lt;/code&gt;，输入 root 密码就能进 shell——这不是系统坏了，这是它在向你求救，第五节马上就会用到。&lt;/p&gt;
&lt;h2&gt;四、死法一：fstab 写错，进了 emergency mode&lt;/h2&gt;
&lt;p&gt;这是新手和老手都会中的招：给服务器加了一块数据盘，往 &lt;code&gt;/etc/fstab&lt;/code&gt; 里写了一行，重启——起不来了。原理很简单：systemd 在启动时会严格按 &lt;code&gt;fstab&lt;/code&gt; 挂载所有文件系统，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;fstab 里任何一行挂载失败，启动就会中断并掉进 emergency mode&amp;lt;/span&amp;gt;，哪怕失败的只是一块无关紧要的数据盘。&lt;/p&gt;
&lt;p&gt;常见写错姿势有三种：设备名写错（&lt;code&gt;/dev/sdb1&lt;/code&gt; 重启后变成了 &lt;code&gt;/dev/sdc1&lt;/code&gt;）、UUID 抄错一位、文件系统类型填错。症状也高度一致：控制台上先刷 &lt;code&gt;A start job is running for /dev/disk/by-uuid/...&lt;/code&gt;，等一分半钟超时，然后提示进入 emergency mode。&lt;/p&gt;
&lt;p&gt;修复步骤如下。先用 root 密码进 emergency shell，然后：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 根文件系统在 emergency 模式下通常是只读的，先改成读写
mount -o remount,rw /

# 把 fstab 备份一份，再打开编辑
cp /etc/fstab /etc/fstab.bak
nano /etc/fstab
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把出问题的那一行&lt;strong&gt;先注释掉&lt;/strong&gt;（行首加 &lt;code&gt;#&lt;/code&gt;），存盘退出。然后不要急着重启，先验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 按当前 fstab 试挂一遍，有错会当场报出来
mount -a

# 验证没问题后退出 emergency shell 继续启动，或直接重启
exit
# 或
reboot
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;系统正常起来之后，再回头把那行配置改对：设备一律用 UUID 写（&lt;code&gt;blkid&lt;/code&gt; 查），不要写 &lt;code&gt;/dev/sdX&lt;/code&gt; 这种会漂移的名字。&lt;/p&gt;
&lt;p&gt;预防这一招只需要养成两个习惯。第一，&lt;strong&gt;每次改完 fstab，重启前必跑一次 &lt;code&gt;mount -a&lt;/code&gt;&lt;/strong&gt;，它按 fstab 全量试挂，报错当场可见，这时改回来毫无代价。第二，给非系统盘的那一行加上 &lt;code&gt;nofail&lt;/code&gt; 选项：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;UUID=xxxx-xxxx  /data  ext4  defaults,nofail  0  2
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;nofail&lt;/code&gt; 的意思是这块盘挂不上也别拦着系统启动——数据盘缺席总比整机躺平强。&lt;/p&gt;
&lt;p&gt;:::warning
改 fstab 之前先想清楚一件事：云服务器的系统盘在 fstab 里通常只有根分区一行，凡是自己后加的行，出事概率最高。改完不验证就重启，等于把排障现场从「工位上」搬到了「控制台里」。
:::&lt;/p&gt;
&lt;h2&gt;五、死法二：磁盘满，服务集体起不来&lt;/h2&gt;
&lt;p&gt;第二种死法不那么戏剧化，但更常见：磁盘在某个深夜被日志或缓存撑满，然后数据库起不来、Docker 起不来、SSH 登录卡半天、甚至连日志都写不进去——因为记录「磁盘满了」这件事本身也需要写日志。表现是系统能进、能 ping，但一堆服务状态是 failed，&lt;code&gt;journalctl -xb -p err&lt;/code&gt; 里满屏 &lt;code&gt;No space left on device&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;处理思路是先腾地方，再谈根治。找大户的命令在磁盘管理篇已经详细讲过，这里只给救援现场的最速路径：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 先看每个挂载点满到什么程度
df -h

# 从根目录往下逐层找最大的目录
du -xhd1 / | sort -h

# 日志是头号嫌疑犯，看 journal 占了多少
journalctl --disk-usage
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;应急清理时有明确的安全边界。&lt;strong&gt;可以放心清的&lt;/strong&gt;：过期的 journal 日志（&lt;code&gt;journalctl --vacuum-time=3d&lt;/code&gt; 只保留 3 天）、包管理器缓存（&lt;code&gt;apt clean&lt;/code&gt;）、&lt;code&gt;/tmp&lt;/code&gt; 里的陈旧临时文件、明确是自己业务产生的旧备份和旧日志归档。&lt;strong&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不能为了腾空间去删不认识的文件&amp;lt;/span&amp;gt;&lt;/strong&gt;，尤其是 &lt;code&gt;/var/lib&lt;/code&gt; 下数据库的原始数据文件、别人的业务目录——磁盘满是故障，把数据删了就是事故。&lt;/p&gt;
&lt;p&gt;腾出几个 GB 之后，把失败的服务拉起来并确认恢复：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl --failed
systemctl restart &amp;lt;服务名&amp;gt;
df -h
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;最后别忘了回头找根因：到底是日志没轮转、备份没清理还是业务文件无限增长。磁盘篇（/posts/linux-disk-management/）里讲的日志轮转与配额，才是这一节的治本部分——救援只是把你从坑里拉出来，不爬第二次得靠日常纪律。&lt;/p&gt;
&lt;h2&gt;六、从 GRUB 进单用户：没有密码也能修&lt;/h2&gt;
&lt;p&gt;如果系统进不去的原因是 root 密码忘了、SSH 配置改坏、或者某个服务把启动拖死，你需要绕过正常启动流程，直接以最高权限进系统。入口在 GRUB 菜单：开机时让菜单停住（云上要在控制台里抢那几秒，物理机按住 Shift 或狂按 Esc），选中启动项后按 &lt;code&gt;e&lt;/code&gt; 进入编辑界面。&lt;/p&gt;
&lt;p&gt;有两种改法，任选其一。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;姿势一：切到 rescue 目标。&lt;/strong&gt; 找到以 &lt;code&gt;linux&lt;/code&gt; 开头的那一行，在行尾加上：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemd.unit=rescue.target
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;按 Ctrl+X 或 F10 启动，系统会进单用户救援模式，要求输入 root 密码。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;姿势二：直接换 init。&lt;/strong&gt; 同样在 &lt;code&gt;linux&lt;/code&gt; 行尾，把参数改成：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;init=/bin/bash
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这种姿势连 systemd 都不启动，直接给你一个 root 的 bash，&lt;strong&gt;连密码都不问&lt;/strong&gt;——它适合连 root 密码都忘了的情况，代价是进去之后什么服务都没有，根文件系统还是只读的，第一条命令必须是：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mount -o remount,rw /
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改完密码或配置后，不能用普通方式重启（因为 PID 1 就是 bash 本身），要这样收尾：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sync
mount -o remount,ro /
reboot -f
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;init=/bin/bash&lt;/code&gt; 不问密码这件事是把双刃剑：你能用它救自己的机器，任何能碰到你控制台的人也能用它进你的系统。所以云控制台的账号密码、物理机房的门禁，和 root 密码是同一级的安全资产。救完之后，检查一遍 GRUB 是否需要设置密码保护，心里有数即可，别因噎废食把自己的救援通道堵死。
:::&lt;/p&gt;
&lt;p&gt;两种姿势的选择：记得 root 密码、只是想跳过坏服务进系统，用姿势一，环境完整好干活；密码忘了或者 systemd 本身出了问题，用姿势二，进去先 remount 读写再修。&lt;/p&gt;
&lt;h2&gt;七、内核翻车：新内核起不来，先回旧的&lt;/h2&gt;
&lt;p&gt;第三种死法通常发生在系统更新之后：&lt;code&gt;apt upgrade&lt;/code&gt; 装了新内核，重启，新内核 panic 或者直接黑屏。这种情况反而最好办，因为 Debian 在升级内核时&lt;strong&gt;默认保留旧内核&lt;/strong&gt;，GRUB 菜单里就能选回来。&lt;/p&gt;
&lt;p&gt;操作就三步：开机进 GRUB 菜单（云控制台里抢时间，必要时在 &lt;code&gt;/etc/default/grub&lt;/code&gt; 里把 &lt;code&gt;GRUB_TIMEOUT&lt;/code&gt; 改大一点，但那是事后的事），选「Advanced options for Debian GNU/Linux」，里面列着所有已安装的内核，选上一个版本号的旧内核启动。能正常进系统，就先确认了故障范围：&lt;strong&gt;坏的是新内核，不是你的数据和配置&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;进去之后的处理原则：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;先别删新内核，也先别急着再升级，让系统在旧内核上稳定跑着；&lt;/li&gt;
&lt;li&gt;查新内核的安装过程有没有报错（&lt;code&gt;dpkg -l | grep linux-image&lt;/code&gt;、看 &lt;code&gt;/var/log/apt/&lt;/code&gt; 的记录），常见原因是 initramfs 生成失败，&lt;code&gt;update-initramfs -u -k &amp;lt;版本号&amp;gt;&lt;/code&gt; 重新生成一次再试；&lt;/li&gt;
&lt;li&gt;如果决定固定使用旧内核，可以调整 GRUB 默认启动项，但这是临时措施，新内核的问题（比如某个驱动回归）该跟踪还得跟踪。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;反过来有一条铁律：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;在新内核没有成功启动并稳定运行之前，永远不要卸载旧内核&amp;lt;/span&amp;gt;。旧内核占不了多少磁盘，它是你升级翻车时唯一的回头路。真要清理老内核，也只清理比「当前在用」和「上一个可用」更老的那些。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 查看当前正在运行的内核
uname -r

# 查看所有已安装的内核
dpkg -l | grep linux-image

# 改完 GRUB 相关配置后，记得更新菜单
update-grub
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;八、终极手段：Live 介质 chroot&lt;/h2&gt;
&lt;p&gt;前面几招的前提都是「系统还能进到某种 shell」。如果连 GRUB 都坏了、根文件系统损坏到 initramfs 都挂不上，那就只剩最后一招：&lt;strong&gt;用另一套系统启动，把故障盘挂上来当数据盘修&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;物理机上这叫 Live USB 启动；云服务器上对应的是厂商提供的&lt;strong&gt;救援模式（Rescue Mode）&lt;/strong&gt;——本质完全一样：平台用一个临时系统（通常是内存里跑的 Linux）启动你的实例，你的系统盘则作为一块普通数据盘挂在旁边。阿里云、腾讯云、Vultr、Hetzner 等厂商都有这个功能，入口一般在实例的控制台里，开启后会给一个临时 root 密码。&lt;/p&gt;
&lt;p&gt;流程梗概如下。进入救援系统后：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 找到你的系统盘并挂载（设备名以 lsblk 实际输出为准）
lsblk
mount /dev/vda1 /mnt

# 如果根目录在 LVM 或单独的分区上，先激活卷组再挂载
# vgscan &amp;amp;&amp;amp; vgchange -ay

# 2. 如果有独立的 boot 分区，一并挂上
mount /dev/vda2 /mnt/boot   # 视实际分区情况而定，没有就跳过

# 3. 把救援系统的运行时目录 bind 进去，chroot 后才能正常用网络和设备
mount --bind /proc /mnt/proc
mount --bind /sys  /mnt/sys
mount --bind /dev  /mnt/dev

# 4. 切根进去——从现在起，你就在故障系统里了
chroot /mnt

# 5. 该修什么修什么：重装坏掉的包、改配置、重装引导
apt install --reinstall &amp;lt;坏掉的包&amp;gt;
update-grub
grub-install /dev/vda
exit
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;修完之后退出 chroot，卸载挂载，退出救援模式用正常方式启动实例，再去控制台确认能正常进系统。&lt;/p&gt;
&lt;p&gt;:::warning
chroot 救援里最容易翻车的点是挂错分区：救援系统里看到的设备名和实例正常启动时的设备名可能不一致。动手前用 &lt;code&gt;lsblk -f&lt;/code&gt; 看清每块盘的 UUID 和文件系统，拿 UUID 和你平时记录的系统盘信息对上号，再 mount。挂错盘修一通，轻则白忙，重则把好的那块盘改坏。
:::&lt;/p&gt;
&lt;p&gt;这一招门槛看着高，但它恰恰说明了一件事：只要盘上的数据还在、你手里有控制台和救援通道，Linux 几乎没有「救不回来」的死法。真正的死局只有一种——盘坏了且没备份。那不属于本篇的范畴，那是备份篇要解决的问题。&lt;/p&gt;
&lt;h2&gt;九、预防清单：把整个系列收成十条纪律&lt;/h2&gt;
&lt;p&gt;写到这里，这个系列从新机初始化一路讲到了系统救援。回头看，所有「起不来」的故事，源头都是某个日常动作里少做了一步。把分散在各篇的纪律汇总成一张清单，贴在你的运维笔记第一页：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;#&lt;/th&gt;
&lt;th&gt;纪律&lt;/th&gt;
&lt;th&gt;对应篇目&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;改 fstab 后重启前必跑 &lt;code&gt;mount -a&lt;/code&gt; 验证，非系统盘加 &lt;code&gt;nofail&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;本篇 / 磁盘篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;改 SSH、网络、防火墙配置时保留一个已登录的会话，新会话连得上再关旧的&lt;/td&gt;
&lt;td&gt;SSH 加固篇 / 防火墙篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;任何关键配置文件，改前先 &lt;code&gt;cp&lt;/code&gt; 一份带日期的备份&lt;/td&gt;
&lt;td&gt;本篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;新内核没稳定运行前不删旧内核&lt;/td&gt;
&lt;td&gt;本篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;磁盘使用率上监控告警，别等满了才知道&lt;/td&gt;
&lt;td&gt;监控篇 / 磁盘篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;日志开轮转，journal 设上限&lt;/td&gt;
&lt;td&gt;日志篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;云服务器到手先测一遍控制台与救援模式能不能进&lt;/td&gt;
&lt;td&gt;本篇 / 新机初始化篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;8&lt;/td&gt;
&lt;td&gt;关键机器做重大变更前先打快照&lt;/td&gt;
&lt;td&gt;备份篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;9&lt;/td&gt;
&lt;td&gt;备份要定期做恢复演练，没验证过的备份等于没备份&lt;/td&gt;
&lt;td&gt;备份篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;10&lt;/td&gt;
&lt;td&gt;每次故障处理完写三行复盘：原因、修法、防复发动作&lt;/td&gt;
&lt;td&gt;性能排障篇&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这十条里没有一条需要高深技术，全是习惯。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;运维的水平差距，大多不在会不会修，而在让不让故障有机会发生&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h2&gt;小结：完结篇&lt;/h2&gt;
&lt;p&gt;从第一篇新机初始化开始，这个系列走完了一个完整的闭环：一台服务器从裸机上架、SSH 加固、防火墙、systemd、磁盘、日志、监控、备份、性能排障、安全巡检，一路到日常管理的方方面面，最后回到这一篇——当所有防线都没拦住、机器真的起不来时，怎么把它救回来。&lt;/p&gt;
&lt;p&gt;最后把救援的心法压缩成三句，留给你贴在控制台旁边：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;先定位，后动手&lt;/strong&gt;：对照启动流程四阶段和上一次的启动日志，把故障圈进最小的范围；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;先保命，后治病&lt;/strong&gt;：备份再改、旧内核别删、控制台先确认——所有动作都留回头路；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;修好不是终点&lt;/strong&gt;：找到根因、补上预防动作，这次故障才算真正结案。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Linux 运维这套东西，学的时候是命令和配置，用的时候是纪律和心态。愿你的服务器永远用不上这一篇——如果用上了，愿你翻开它时足够冷静。&lt;/p&gt;
&lt;p&gt;—— Linux 服务器运维系列 · 全 23 篇，完结。&lt;/p&gt;
</content:encoded></item><item><title>systemd 服务管理实战</title><link>https://www.anexns.cloudns.org/posts/linux-systemd-services/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-systemd-services/</guid><description>Linux 上管服务的总开关：systemctl 核心命令、unit 文件逐段拆解、手写一个自己的服务并设为自启、用 timer 替代 cron 定时任务，以及给服务加资源限制与自动重启。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;上一篇把防火墙立好了，服务器算是「门窗关严」。但一台服务器真正干活靠的是服务：网站、数据库、代理、监控、定时清理脚本……这些东西谁来启动、谁来盯着、崩了谁来拉起来、开机谁先谁后，全归一个组件管——systemd。这一篇就把 systemd 吃透：先认清它是什么，再掌握 systemctl 的核心命令，然后逐段拆解一份真实的 unit 文件，亲手把一个脚本写成正经服务，最后用 timer 把 cron 换掉，并给服务加上资源限制与自动重启。学完这一篇，你在 Debian 上管任何服务都不用再到处搜命令了。&lt;/p&gt;
&lt;h2&gt;一、systemd 是什么：开机后的第一个进程&lt;/h2&gt;
&lt;p&gt;你按下电源，内核加载完，第一个被拉起来的用户态进程就是 systemd，它的 PID 永远是 1。之后所有的事——挂载文件系统、拉起网络、启动 SSH、启动你的应用——都由它按依赖顺序安排。它不只是一个「启动脚本的集合」，而是一整套系统与服务管理器：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;服务管理&lt;/strong&gt;：启动、停止、重启、崩溃自动拉起、依赖排序&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;日志管理&lt;/strong&gt;：配套的 journald 收集所有服务的输出（本系列日志篇会细讲）&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;定时任务&lt;/strong&gt;：timer 单元可以替代 cron，而且能看上次执行结果&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;资源控制&lt;/strong&gt;：底层用 cgroup 给每个服务限 CPU、内存&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;挂载与设备&lt;/strong&gt;：文件系统挂载、设备出现事件也归它管&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;unit：systemd 眼里的一切都是单元&lt;/h3&gt;
&lt;p&gt;systemd 管理的对象统称 &lt;strong&gt;unit（单元）&lt;/strong&gt;，每个 unit 对应一个配置文件，靠后缀区分类型：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;后缀&lt;/th&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;管什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.service&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;服务&lt;/td&gt;
&lt;td&gt;一个进程（或一组进程），本篇主角&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.timer&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;定时器&lt;/td&gt;
&lt;td&gt;到点触发一个 &lt;code&gt;.service&lt;/code&gt;，替代 cron&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.mount&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;挂载点&lt;/td&gt;
&lt;td&gt;一个文件系统挂载&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.socket&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;套接字&lt;/td&gt;
&lt;td&gt;按需拉起服务（有连接才启动）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.target&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;目标&lt;/td&gt;
&lt;td&gt;一组 unit 的集合，类似旧的运行级别&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.path&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;路径监控&lt;/td&gt;
&lt;td&gt;文件出现或变化时触发服务&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;unit 文件分布在三个目录，优先级从高到低：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;目录&lt;/th&gt;
&lt;th&gt;放什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/etc/systemd/system/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;管理员自己写的、改的，优先级最高&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/run/systemd/system/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;运行时生成的，重启即失&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/usr/lib/systemd/system/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;软件包自带的，别直接改&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
改包自带服务的行为，用 &lt;code&gt;systemctl edit&lt;/code&gt; 生成覆盖文件，或者在 &lt;code&gt;/etc/systemd/system/&lt;/code&gt; 放同名文件；&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;直接编辑 /usr/lib/systemd/system/ 下的文件，软件一升级你的修改就被覆盖没了&amp;lt;/span&amp;gt;。
:::&lt;/p&gt;
&lt;h3&gt;和 SysVinit、cron 是什么关系&lt;/h3&gt;
&lt;p&gt;老一代 Linux 用 SysVinit：一堆放在 &lt;code&gt;/etc/init.d/&lt;/code&gt; 的 shell 脚本，按运行级别顺序执行，服务之间谁先谁后靠文件名编号硬排，崩了也没人管。systemd 把这些全部收编：启动改为按依赖并行拉起，快得多；每个服务独立成 unit，状态、日志、资源都可查可控。&lt;/p&gt;
&lt;p&gt;和 cron 的关系是「替代但兼容」：cron 还能用，但 systemd timer 在可观测性上完胜——能查上次什么时候跑的、成功还是失败、输出全在 journal 里。本篇第八节会把一个每日清理脚本从 cron 迁到 timer。&lt;/p&gt;
&lt;p&gt;先记住一句核心结论：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;在 Debian 上管服务，只需要围着 systemctl、unit 文件和 journalctl 这三样转，其余都是细节。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;二、systemctl 生存命令：先把开关认全&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;systemctl&lt;/code&gt; 是 systemd 的总遥控器。下面这张表是日常运维的全部高频命令，建议先通读一遍，后面实战里会反复用到：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl start &amp;lt;服务&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;立即启动&lt;/td&gt;
&lt;td&gt;只管这一次&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl stop &amp;lt;服务&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;立即停止&lt;/td&gt;
&lt;td&gt;只管这一次&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl restart &amp;lt;服务&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;重启（先停后启）&lt;/td&gt;
&lt;td&gt;没在运行也能执行，等于直接启动&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl reload &amp;lt;服务&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;让服务重读配置，不重启进程&lt;/td&gt;
&lt;td&gt;服务本身要支持，如 Nginx、SSH&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl reload-or-restart &amp;lt;服务&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;能 reload 就 reload，否则 restart&lt;/td&gt;
&lt;td&gt;改配置后不确定用哪个时用它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl status &amp;lt;服务&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;看状态、最近日志、主进程 PID&lt;/td&gt;
&lt;td&gt;排障第一站&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl enable &amp;lt;服务&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;设为开机自启&lt;/td&gt;
&lt;td&gt;只登记，不立即启动&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl disable &amp;lt;服务&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;取消开机自启&lt;/td&gt;
&lt;td&gt;不影响当前运行状态&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl enable --now &amp;lt;服务&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;自启 + 立即启动&lt;/td&gt;
&lt;td&gt;最常用的组合&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl is-enabled &amp;lt;服务&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;查是否自启&lt;/td&gt;
&lt;td&gt;输出 enabled / disabled / static&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl is-active &amp;lt;服务&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;查是否在运行&lt;/td&gt;
&lt;td&gt;脚本里判断状态常用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl list-units --failed&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列出所有失败的 unit&lt;/td&gt;
&lt;td&gt;巡检必看&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl list-units --type=service&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列出全部服务 unit&lt;/td&gt;
&lt;td&gt;加 &lt;code&gt;--state=running&lt;/code&gt; 只看运行中&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl daemon-reload&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;重读 unit 文件&lt;/td&gt;
&lt;td&gt;改完 unit 必须执行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;systemctl cat &amp;lt;服务&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;打印 unit 文件（含覆盖合并结果）&lt;/td&gt;
&lt;td&gt;确认最终生效配置&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;enable 和 start 是两件完全不同的事&lt;/h3&gt;
&lt;p&gt;这是新手最容易混的一对，务必分清：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;start&lt;/code&gt; 管&lt;strong&gt;现在&lt;/strong&gt;：进程立刻跑起来，但重启机器后不会自动恢复&lt;/li&gt;
&lt;li&gt;&lt;code&gt;enable&lt;/code&gt; 管&lt;strong&gt;以后&lt;/strong&gt;：在开机目标里登记一笔，这次开机不会启动它&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;只 &lt;code&gt;start&lt;/code&gt; 没 &lt;code&gt;enable&lt;/code&gt;，机器一重启服务就没了；只 &lt;code&gt;enable&lt;/code&gt; 没 &lt;code&gt;start&lt;/code&gt;，要等下次开机才生效。所以装好一个新服务，标准动作是 &lt;code&gt;systemctl enable --now &amp;lt;服务&amp;gt;&lt;/code&gt;，一次到位。反过来，下线一个服务也要两步：先 &lt;code&gt;stop&lt;/code&gt; 再 &lt;code&gt;disable&lt;/code&gt;，漏掉 &lt;code&gt;disable&lt;/code&gt; 的话下次开机它还会爬起来。&lt;/p&gt;
&lt;p&gt;看状态是最常用的命令，先混个眼熟：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl status ssh
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;● ssh.service - OpenBSD Secure Shell server
     Loaded: loaded (/usr/lib/systemd/system/ssh.service; enabled; preset: enabled)
     Active: active (running) since Mon 2026-11-10 08:15:23 CST; 2h 14min ago
   Main PID: 812 (sshd)
      Tasks: 1 (limit: 114514)
     Memory: 3.8M
        CPU: 420ms
     CGroup: /system.slice/ssh.service
             └─812 &quot;sshd: /usr/sbin/sshd -D [listener] 0 of 10-100 startups&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;Loaded&lt;/code&gt; 一行告诉你 unit 文件在哪、是否自启；&lt;code&gt;Active&lt;/code&gt; 是运行状态和启动时间；下面还会带最近 10 行日志——很多时候故障原因直接就写在这里。&lt;/p&gt;
&lt;p&gt;巡检时先扫一眼有没有失败的 unit：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl list-units --failed
systemctl --failed        # 等价简写
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出为空（&lt;code&gt;0 loaded units listed&lt;/code&gt;）就是全绿。这一条也应该是你每次登录服务器后的肌肉记忆。&lt;/p&gt;
&lt;h2&gt;三、unit 文件逐段拆解&lt;/h2&gt;
&lt;p&gt;命令是皮，unit 文件才是骨。下面是一份真实可用的服务文件，我们逐段拆开看每个字段在说什么。假设场景：你有一个用 Python 写的 HTTP 接口程序，装在 &lt;code&gt;/opt/myapi/&lt;/code&gt;，要用它对外提供服务。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Unit]
Description=My API Service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=myapi
Group=myapi
WorkingDirectory=/opt/myapi
ExecStart=/opt/myapi/venv/bin/python -m myapi.main
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;[Unit] 段：身份与依赖&lt;/h3&gt;
&lt;p&gt;这一段描述「我是谁、我和谁有先后关系」，不涉及进程本身：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Description=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;一句话说明，&lt;code&gt;systemctl status&lt;/code&gt; 和开机日志里显示的就是它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;After=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;我要在这些 unit &lt;strong&gt;之后&lt;/strong&gt;启动（只定顺序，不定是否拉起）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Before=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;我要在这些 unit 之前启动&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Wants=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;我启动时，顺带把这些 unit 也拉起来；对方失败不连累我&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Requires=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;同上，但对方启动失败，我也跟着失败（强依赖）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Wants=network-online.target&lt;/code&gt; + &lt;code&gt;After=network-online.target&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;经典组合：等网络真正可用（拿到 IP）再启动&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;After&lt;/code&gt; 和 &lt;code&gt;Wants&lt;/code&gt; 最容易搞混，记住：&lt;strong&gt;After 只管排队顺序，不管拉不拉人；Wants 只管拉人，不管顺序。&lt;/strong&gt; 想表达「等网络好了再启动我」，两个必须一起写，缺一个都可能在开机时抢跑、连不上网。&lt;/p&gt;
&lt;p&gt;另外提醒：依赖的是 &lt;code&gt;network-online.target&lt;/code&gt;（网络已就绪）而不是 &lt;code&gt;network.target&lt;/code&gt;（网络服务已启动），一字之差，含义完全不同。数据库、远程挂载这类依赖同理。&lt;/p&gt;
&lt;h3&gt;[Service] 段：进程怎么跑&lt;/h3&gt;
&lt;p&gt;这是最长的一段，决定进程的启动方式、身份和待遇：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Type=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;启动类型，决定 systemd 怎么判断「服务已就绪」，下一节专讲&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ExecStart=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;启动命令，必须写&lt;strong&gt;绝对路径&lt;/strong&gt;，不支持 shell 语法（管道、重定向、变量展开都不行）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ExecReload=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;收到 reload 时执行的命令，如给主进程发 SIGHUP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;ExecStop=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;停止命令；不写则默认给主进程发 SIGTERM&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;User=&lt;/code&gt; / &lt;code&gt;Group=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;用哪个用户跑，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;能不用 root 就不要用 root 跑网络服务&amp;lt;/span&amp;gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;WorkingDirectory=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;进程的工作目录，相对路径、日志落点都受它影响&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Environment=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;设置环境变量，如 &lt;code&gt;Environment=PORT=8080&lt;/code&gt;，可写多行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;EnvironmentFile=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;从文件读环境变量，密钥类配置放这里并收紧文件权限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Restart=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;退出后是否自动重启，第六节专讲&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;RestartSec=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;重启前等几秒&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;StandardOutput=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;标准输出去哪，默认 &lt;code&gt;journal&lt;/code&gt;，即 &lt;code&gt;journalctl&lt;/code&gt; 能看&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;关于 &lt;code&gt;ExecStart&lt;/code&gt; 有两个高频坑：一是相对路径直接报 203/EXEC 错误（第十节细讲）；二是想当然地写 shell 命令，比如 &lt;code&gt;ExecStart=cd /opt/app &amp;amp;&amp;amp; ./run.sh&lt;/code&gt; 必然失败——&lt;code&gt;ExecStart&lt;/code&gt; 的第一个词就是可执行文件本身。要用 shell 特性，得显式写 &lt;code&gt;ExecStart=/bin/sh -c &apos;...&apos;&lt;/code&gt;，但更推荐把逻辑收进脚本文件再调用。&lt;/p&gt;
&lt;p&gt;环境变量还有个细节：写在 &lt;code&gt;Environment=&lt;/code&gt; 里的值在 unit 文件中是明文，&lt;code&gt;systemctl cat&lt;/code&gt; 人人可见。密码、Token 这类密钥不要写进 unit 文件，放进单独的 &lt;code&gt;EnvironmentFile&lt;/code&gt; 并把权限设成 &lt;code&gt;600&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;[Install] 段：自启登记处&lt;/h3&gt;
&lt;p&gt;这一段只有一个高频字段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Install]
WantedBy=multi-user.target
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;multi-user.target&lt;/code&gt; 是「正常多用户运行状态」这个目标，相当于图形界面之外的默认开机终点。&lt;code&gt;systemctl enable&lt;/code&gt; 干的事，就是按这一段的指示，在 &lt;code&gt;/etc/systemd/system/multi-user.target.wants/&lt;/code&gt; 下给你的 unit 建一个软链接。开机时 systemd 达成 &lt;code&gt;multi-user.target&lt;/code&gt;，顺带把 &lt;code&gt;.wants&lt;/code&gt; 目录里的 unit 全部拉起。&lt;/p&gt;
&lt;p&gt;所以：&lt;strong&gt;没有 [Install] 段、或者 WantedBy 写错，enable 要么报错要么登记到没人达成的目标上&lt;/strong&gt;——这正是「明明 enable 了却不开机自启」的头号原因（第十节还会碰到）。&lt;/p&gt;
&lt;p&gt;:::warning
unit 文件改完（包括新建）必须先 &lt;code&gt;systemctl daemon-reload&lt;/code&gt;，systemd 才认识新内容。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;跳过这一步直接 start，跑起来的还是旧配置，甚至直接报 Unit not found。&amp;lt;/span&amp;gt;
:::&lt;/p&gt;
&lt;h2&gt;四、实战：把一个脚本手写成正经服务&lt;/h2&gt;
&lt;p&gt;光看不练假把式。现在动手：把一个日志清理脚本做成服务。脚本本身很简单，扫 &lt;code&gt;/var/log/myapp/&lt;/code&gt; 下 7 天前的日志并删除：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo mkdir -p /usr/local/bin
sudo nano /usr/local/bin/clean-myapp-logs.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;#!/bin/bash
# 清理 myapp 7 天前的日志
find /var/log/myapp/ -type f -name &quot;*.log&quot; -mtime +7 -delete
echo &quot;cleanup done: $(date &apos;+%F %T&apos;)&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;sudo chmod +x /usr/local/bin/clean-myapp-logs.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第一步：写 unit 文件&lt;/h3&gt;
&lt;p&gt;管理员自写的 unit 一律放 &lt;code&gt;/etc/systemd/system/&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo nano /etc/systemd/system/clean-myapp-logs.service
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;[Unit]
Description=Clean myapp logs older than 7 days
After=local-fs.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/clean-myapp-logs.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这个脚本「跑完就结束」，所以 &lt;code&gt;Type=oneshot&lt;/code&gt;；它不需要开机自启，所以没有 &lt;code&gt;[Install]&lt;/code&gt; 段——它由后面的 timer 到点触发，这正是 timer 组合的标准形态。&lt;/p&gt;
&lt;h3&gt;第二步：再写一个常驻服务的例子&lt;/h3&gt;
&lt;p&gt;为了把「自启 + 崩溃自拉」也练到，再拿第三节的 API 服务落地。先建专用用户和目录（密钥文件顺手放好）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo useradd --system --home /opt/myapi --shell /usr/sbin/nologin myapi
sudo mkdir -p /opt/myapi
sudo chown myapi:myapi /opt/myapi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把程序放进 &lt;code&gt;/opt/myapi&lt;/code&gt; 后，写 unit：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo nano /etc/systemd/system/myapi.service
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;内容就是第三节拆解的那份，补上环境文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Unit]
Description=My API Service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=myapi
Group=myapi
WorkingDirectory=/opt/myapi
EnvironmentFile=/opt/myapi/myapi.env
ExecStart=/opt/myapi/venv/bin/python -m myapi.main
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;echo &apos;API_TOKEN=change-me&apos; | sudo tee /opt/myapi/myapi.env
sudo chmod 600 /opt/myapi/myapi.env
sudo chown myapi:myapi /opt/myapi/myapi.env
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;第三步：登记并启动&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl daemon-reload
sudo systemctl enable --now myapi
sudo systemctl status myapi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;status&lt;/code&gt; 显示 &lt;code&gt;active (running)&lt;/code&gt; 且 &lt;code&gt;Loaded&lt;/code&gt; 一行带 &lt;code&gt;enabled&lt;/code&gt;，就说明「现在在跑、开机也自启」两件事都齐了。&lt;/p&gt;
&lt;h3&gt;第四步：验证崩溃自拉&lt;/h3&gt;
&lt;p&gt;亲手把进程杀掉，看 systemd 会不会按 &lt;code&gt;Restart=on-failure&lt;/code&gt; 把它拉回来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 拿到主进程 PID 并杀掉
sudo kill -9 $(systemctl show -p MainPID --value myapi)
sleep 5
systemctl status myapi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;kill -9&lt;/code&gt; 是异常终止，属于 failure，几秒后 &lt;code&gt;status&lt;/code&gt; 里应该能看到一个新的 Main PID、启动时间刚刚刷新。再试一次优雅退出对照：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo kill -TERM $(systemctl show -p MainPID --value myapi)
systemctl is-active myapi   # 输出 inactive：正常退出不触发 on-failure
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这个对照实验能帮你真正理解下一节的重启策略：&lt;strong&gt;怎么死的，决定了要不要拉。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;手动触发一次清理服务，确认 oneshot 形态工作正常：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl start clean-myapp-logs
systemctl status clean-myapp-logs   # 应显示 inactive (dead)，且日志里有 cleanup done
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意：oneshot 跑完状态是 &lt;code&gt;inactive (dead)&lt;/code&gt;，这是&lt;strong&gt;成功&lt;/strong&gt;，不是故障——它的「完成态」就是退出。&lt;/p&gt;
&lt;h2&gt;五、Type 选型：告诉 systemd「什么算启动成功」&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;Type=&lt;/code&gt; 是 unit 里最需要动脑的一个字段。systemd 要靠它判断服务何时算「起来了」，好安排后续依赖它的服务启动。选错的典型症状是：服务明明在跑，&lt;code&gt;systemctl start&lt;/code&gt; 却卡住或超时；或者反过来，服务还没就绪，依赖它的服务就抢跑报错。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Type&lt;/th&gt;
&lt;th&gt;就绪判定&lt;/th&gt;
&lt;th&gt;适合什么&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;simple&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;进程拉起即算就绪&lt;/td&gt;
&lt;td&gt;绝大多数前台常驻程序（默认推荐）&lt;/td&gt;
&lt;td&gt;程序要以前台方式运行，不要自己 fork 到后台&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;exec&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;同上，但要等 exec 成功才算&lt;/td&gt;
&lt;td&gt;担心可执行文件不存在、权限不对时&lt;/td&gt;
&lt;td&gt;判定比 simple 更严一点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;forking&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;主进程 fork 后退出、子进程接管时算就绪&lt;/td&gt;
&lt;td&gt;传统自带 daemon 模式的老程序&lt;/td&gt;
&lt;td&gt;需配合 &lt;code&gt;PIDFile=&lt;/code&gt; 指明主进程&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;oneshot&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;进程退出且返回 0 才算完成&lt;/td&gt;
&lt;td&gt;一次性任务：清理、初始化、迁移脚本&lt;/td&gt;
&lt;td&gt;常配 timer，或配合 &lt;code&gt;RemainAfterExit=&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;notify&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;程序主动通过 sd_notify 上报 READY&lt;/td&gt;
&lt;td&gt;自己开发、集成了 systemd 通知的程序&lt;/td&gt;
&lt;td&gt;就绪判定最准确，但要程序支持&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;dbus&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;服务在 D-Bus 上注册了指定名字时算就绪&lt;/td&gt;
&lt;td&gt;系统级 D-Bus 服务&lt;/td&gt;
&lt;td&gt;一般用户很少写&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选型口诀：&lt;strong&gt;自己写的、常驻前台跑的，用 simple；跑完就走的，用 oneshot；老牌 daemon 只能 forking；其余先别碰。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;最常见的翻车是：程序默认会「自我后台化」（比如某些老牌服务不加参数就 fork 进后台），却配了 &lt;code&gt;Type=simple&lt;/code&gt;。systemd 看到主进程秒退，以为服务挂了，配了 &lt;code&gt;Restart&lt;/code&gt; 的话还会反复拉起，日志里刷一排 started 又 stopped。解法二选一：给程序加前台运行参数（多数现代程序都有，如 Nginx 的 &lt;code&gt;daemon off&lt;/code&gt;、sshd 的 &lt;code&gt;-D&lt;/code&gt;），或改用 &lt;code&gt;Type=forking&lt;/code&gt; 并写对 &lt;code&gt;PIDFile=&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;六、重启策略：崩了要拉，但不能疯拉&lt;/h2&gt;
&lt;p&gt;服务半夜崩掉没人管是事故，崩了以后每秒重启一万次把日志刷爆也是事故。重启策略就三个字段配合：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;常用值&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Restart=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;什么情况下重启&lt;/td&gt;
&lt;td&gt;&lt;code&gt;no&lt;/code&gt;（默认）/ &lt;code&gt;on-failure&lt;/code&gt; / &lt;code&gt;on-success&lt;/code&gt; / &lt;code&gt;always&lt;/code&gt; / &lt;code&gt;on-abnormal&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;RestartSec=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;重启前等待秒数&lt;/td&gt;
&lt;td&gt;&lt;code&gt;3&lt;/code&gt;、&lt;code&gt;5s&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;StartLimitIntervalSec=&lt;/code&gt; + &lt;code&gt;StartLimitBurst=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;一段时间内最多尝试启动几次&lt;/td&gt;
&lt;td&gt;如 &lt;code&gt;60&lt;/code&gt; 秒内 &lt;code&gt;5&lt;/code&gt; 次&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;Restart=&lt;/code&gt; 的几个值怎么分：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;on-failure&lt;/code&gt;：退出码非 0、被信号杀死、超时、看门狗触发时重启。&lt;strong&gt;这是绝大多数服务的正确选择。&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;always&lt;/code&gt;：不管怎么退出都重启，包括你手动 &lt;code&gt;kill -TERM&lt;/code&gt; 让它正常退出——刚才第四节的对照实验里，如果配的是 &lt;code&gt;always&lt;/code&gt;，TERM 之后它照样会爬起来。注意 &lt;code&gt;systemctl stop&lt;/code&gt; 是明确指令，永远有效，不受 &lt;code&gt;always&lt;/code&gt; 影响。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;on-success&lt;/code&gt;：只在正常退出时重启，场景很少。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;on-abnormal&lt;/code&gt;：只处理信号、超时这类「异常」终止，不看退出码。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;防疯拉靠的是 StartLimit 组合。注意这两个字段写在 &lt;strong&gt;[Unit] 段&lt;/strong&gt;，不是 [Service] 段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Unit]
Description=My API Service
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=60
StartLimitBurst=5

[Service]
Type=simple
ExecStart=/opt/myapi/venv/bin/python -m myapi.main
Restart=on-failure
RestartSec=3
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;含义：60 秒内启动尝试达到 5 次还起不来，systemd 就放弃，把 unit 标记为 failed，等你人工介入。这避免了「配置写错 → 无限重启 → 日志和 CPU 一起爆炸」。&lt;/p&gt;
&lt;p&gt;放弃之后怎么复位？修好问题，先清掉失败计数再启动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl reset-failed myapi
sudo systemctl start myapi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;还有一条容易被忽略的账：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Restart 只对「进程退出」生效，机器重启后服务能不能回来，看的是 enable 登记，两者是完全独立的两套机制。&amp;lt;/span&amp;gt;线上排障时先分清你面对的是哪一套出了问题，能少走一半弯路。&lt;/p&gt;
&lt;h2&gt;七、用 journalctl 看服务日志&lt;/h2&gt;
&lt;p&gt;服务输出默认全部进 journald，查日志的工具是 &lt;code&gt;journalctl&lt;/code&gt;，按服务查是最常见的用法：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;journalctl -u myapi&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;看 myapi 的全部日志（从旧到新）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;journalctl -u myapi -f&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;实时跟踪，相当于 tail -f&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;journalctl -u myapi -n 100&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只看最近 100 行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;journalctl -u myapi --since today&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;今天以来的日志&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;journalctl -u myapi --since &quot;2026-11-15 09:00&quot; --until &quot;2026-11-15 10:00&quot;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;精确时间段&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;journalctl -u myapi -p err&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只看 err 级别及更严重的&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;journalctl -u myapi -b&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;本次开机以来的（&lt;code&gt;-b -1&lt;/code&gt; 是上一次开机）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;journalctl -u myapi --no-pager&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不进分页器，脚本里用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;级别 &lt;code&gt;-p&lt;/code&gt; 从高到低是 &lt;code&gt;emerg / alert / crit / err / warning / notice / info / debug&lt;/code&gt;，写 &lt;code&gt;-p err&lt;/code&gt; 表示 err 及以上。排障时先用 &lt;code&gt;-p err&lt;/code&gt; 把噪音滤掉，往往一眼就看到病根。&lt;/p&gt;
&lt;p&gt;两个实用习惯：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;服务起不来时，先 &lt;code&gt;systemctl status&lt;/code&gt; 看尾部那 10 行，不够再 &lt;code&gt;journalctl -u&lt;/code&gt; 翻全量，顺序别反。&lt;/li&gt;
&lt;li&gt;重启服务后日志里会有一条分隔，&lt;code&gt;journalctl -u myapi --since &quot;1 min ago&quot;&lt;/code&gt; 能精准框住这次启动的输出。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;日志能存多久、占多大磁盘、怎么轮转清理，是另一整套话题，本系列另有专篇细讲：&lt;a href=&quot;/posts/linux-log-management/&quot;&gt;日志管理：journald 与日志轮转&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;八、timer 替代 cron：定时任务也要有状态&lt;/h2&gt;
&lt;p&gt;现在把第四节的清理服务接上定时器，让它每天凌晨 3 点半自动跑。timer 的形态是「一对文件」：&lt;code&gt;.service&lt;/code&gt; 描述干什么（已经写好），&lt;code&gt;.timer&lt;/code&gt; 描述什么时候干。同名配对是硬性要求：&lt;code&gt;clean-myapp-logs.timer&lt;/code&gt; 触发的就是 &lt;code&gt;clean-myapp-logs.service&lt;/code&gt;。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo nano /etc/systemd/system/clean-myapp-logs.timer
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;[Unit]
Description=Run log cleanup daily

[Timer]
OnCalendar=*-*-* 03:30:00
Persistent=true
RandomizedDelaySec=300

[Install]
WantedBy=timers.target
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐个看 [Timer] 段的字段：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OnCalendar=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;日历式触发时间，格式「星期 年-月-日 时:分:秒」，&lt;code&gt;*&lt;/code&gt; 为通配&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Persistent=true&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;错过的时间点在下次开机时补跑（关机期间错过凌晨任务，必开）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;RandomizedDelaySec=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;在触发点后随机延迟 0～N 秒，防一堆任务同一秒挤爆&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OnBootSec=&lt;/code&gt; / &lt;code&gt;OnUnitActiveSec=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;相对触发：开机后 N 分钟、距上次运行 N 小时（二选一逻辑，可与 OnCalendar 混写）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;OnCalendar&lt;/code&gt; 速查：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;写法&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;*-*-* 03:30:00&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每天 03:30&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Mon *-*-* 04:00:00&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每周一 04:00&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;*-*-01 05:00:00&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每月 1 号 05:00&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;hourly&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每小时整点（&lt;code&gt;*-*-* *:00:00&lt;/code&gt; 的简写）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;daily&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每天 00:00（&lt;code&gt;*-*-* 00:00:00&lt;/code&gt; 的简写）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;weekly&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每周一 00:00&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;monthly&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每月 1 号 00:00&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;写完别急着启用，先用工具验证你的时间表达式到底解析成了什么：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemd-analyze calendar &quot;*-*-* 03:30:00&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它会打印出规范化结果和下一次触发时间，人眼核对无误再启用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl daemon-reload
sudo systemctl enable --now clean-myapp-logs.timer
systemctl list-timers            # 看全部定时器
systemctl list-timers --all      # 包括还没触发过的
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;list-timers&lt;/code&gt; 的输出里有 NEXT（下次触发）、LAST（上次触发）、LEFT、PASSED 和它对应的 service，一眼看清每个任务的健康状况——这是 cron 永远给不了你的。&lt;/p&gt;
&lt;h3&gt;cron 与 timer 对比&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;cron&lt;/th&gt;
&lt;th&gt;systemd timer&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;配置形态&lt;/td&gt;
&lt;td&gt;一张总表 crontab&lt;/td&gt;
&lt;td&gt;一任务一对文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;上次执行结果&lt;/td&gt;
&lt;td&gt;无记录，要自己重定向日志&lt;/td&gt;
&lt;td&gt;&lt;code&gt;systemctl status&lt;/code&gt; 和 journal 全有&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;失败可见性&lt;/td&gt;
&lt;td&gt;静默失败，邮件经常没人看&lt;/td&gt;
&lt;td&gt;进 &lt;code&gt;--failed&lt;/code&gt; 列表，巡检可见&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;关机错过任务&lt;/td&gt;
&lt;td&gt;直接丢&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Persistent=true&lt;/code&gt; 开机补跑&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;随机延迟&lt;/td&gt;
&lt;td&gt;靠自己写 sleep&lt;/td&gt;
&lt;td&gt;&lt;code&gt;RandomizedDelaySec&lt;/code&gt; 原生支持&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;依赖与资源限制&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;可写 After、MemoryMax 等全套 unit 字段&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;上手成本&lt;/td&gt;
&lt;td&gt;低，语法简单&lt;/td&gt;
&lt;td&gt;略高，但换来可观测性&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;结论很明确：一次性图省事的任务 cron 还能凑合，&lt;strong&gt;正经长期运行的定时任务，尤其是清理、备份这类「悄悄失败就出大事」的，用 timer。&lt;/strong&gt;&lt;/p&gt;
&lt;h2&gt;九、给服务上笼头：资源限制&lt;/h2&gt;
&lt;p&gt;服务器就那么多内存，一个服务泄漏吃满内存，可能把整机拖进 OOM 连带无辜服务一起死。systemd 的 unit 可以直接给服务划 cgroup 限额，不用额外工具。在 [Service] 段加两行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Service]
Type=simple
ExecStart=/opt/myapi/venv/bin/python -m myapi.main
Restart=on-failure
RestartSec=3
MemoryMax=512M
CPUQuota=50%
&lt;/code&gt;&lt;/pre&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;MemoryMax=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;内存硬上限&lt;/td&gt;
&lt;td&gt;超过后该 cgroup 内的进程被 OOM 杀掉，保住整机&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;MemoryHigh=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;内存软上限&lt;/td&gt;
&lt;td&gt;超过先施压回收（更温和，建议先设这个试探）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;CPUQuota=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;CPU 配额&lt;/td&gt;
&lt;td&gt;&lt;code&gt;50%&lt;/code&gt; 表示最多用半个核；&lt;code&gt;200%&lt;/code&gt; 是两个核&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;TasksMax=&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;进程/线程数上限&lt;/td&gt;
&lt;td&gt;防 fork 炸弹类失控&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;注意 &lt;code&gt;MemoryMax&lt;/code&gt; 和 &lt;code&gt;MemoryHigh&lt;/code&gt; 的区别：&lt;code&gt;MemoryHigh&lt;/code&gt; 是「尽量别超，超了就拼命回收内存」；&lt;code&gt;MemoryMax&lt;/code&gt; 是「超了直接杀」。生产服务一般两个一起设：&lt;code&gt;MemoryHigh&lt;/code&gt; 略低先预警施压，&lt;code&gt;MemoryMax&lt;/code&gt; 兜底保命。&lt;/p&gt;
&lt;p&gt;改完照例 &lt;code&gt;daemon-reload&lt;/code&gt; 并重启服务，然后验证限额真的生效——不要只看配置文件，要看内核 cgroup 的实际值：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl daemon-reload
sudo systemctl restart myapi
systemctl show myapi -p MemoryMax -p CPUQuotaPerSecUSec
systemctl status myapi | grep -i memory
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;systemctl show&lt;/code&gt; 打印的是 systemd 认定的限额；更硬的证据是 &lt;code&gt;status&lt;/code&gt; 输出里 &lt;code&gt;Memory:&lt;/code&gt; 一行会带上上限（如 &lt;code&gt;Memory: 12.4M (max: 512.0M)&lt;/code&gt;），或者直接看进程状态页的资源行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl status myapi --no-pager | sed -n &apos;1,12p&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;临时改限额不想动文件，用 &lt;code&gt;systemctl set-property&lt;/code&gt;，立即生效但重启服务后失效（加 &lt;code&gt;--runtime&lt;/code&gt; 之外的默认写法会写入 drop-in 持久化，查文档按需选用）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl set-property myapi MemoryMax=1G
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
资源限制是把双刃剑：&lt;code&gt;MemoryMax&lt;/code&gt; 设得比服务正常峰值还低，服务会被反复 OOM 杀死再重启，表面看是「老崩」，根子是笼头太紧。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;上限要按实测峰值留足余量，别凭感觉拍数字。&amp;lt;/span&amp;gt;
:::&lt;/p&gt;
&lt;h2&gt;十、排障：服务起不来时的固定顺序&lt;/h2&gt;
&lt;p&gt;服务起不来不要乱试，systemd 的排障有固定套路，按顺序走，九成问题在前三步现形。&lt;/p&gt;
&lt;h3&gt;第一步：status 看现场&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;systemctl status myapi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;看三处：&lt;code&gt;Active&lt;/code&gt; 是 failed 还是 activating 死循环；&lt;code&gt;Main PID&lt;/code&gt; 后面括号里的退出原因（如 &lt;code&gt;code=exited, status=203/EXEC&lt;/code&gt;）；底部最近日志的报错原文。&lt;/p&gt;
&lt;h3&gt;第二步：journal 看全量输出&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;journalctl -u myapi -n 100 --no-pager
journalctl -u myapi -p err --since today --no-pager
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;status&lt;/code&gt; 只带最近 10 行，真正的报错经常在更前面。程序自己打的 traceback、缺文件、连不上数据库，都在这里。&lt;/p&gt;
&lt;h3&gt;第三步：cat 确认生效的配置&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;systemctl cat myapi
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;你改的文件和 systemd 实际加载的可能不是一份（drop-in 覆盖、工作目录里另有一份同名文件都会造成这种错觉）。以 &lt;code&gt;cat&lt;/code&gt; 的输出为准。&lt;/p&gt;
&lt;h3&gt;高频故障速查&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;症状&lt;/th&gt;
&lt;th&gt;常见原因&lt;/th&gt;
&lt;th&gt;解法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;status=203/EXEC&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;ExecStart 路径不存在、文件没执行权限、脚本缺 shebang、用了相对路径&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ls -l&lt;/code&gt; 核对路径，脚本 &lt;code&gt;chmod +x&lt;/code&gt; 并补 &lt;code&gt;#!/bin/bash&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;status=200/CHDIR&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;WorkingDirectory 不存在或 User 无权限进入&lt;/td&gt;
&lt;td&gt;建目录、改属主&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;status=217/USER&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;User= 写的用户不存在&lt;/td&gt;
&lt;td&gt;&lt;code&gt;id &amp;lt;用户名&amp;gt;&lt;/code&gt; 核对，先建用户&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Unit xxx could not be found&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;刚建/改完 unit 没 daemon-reload，或文件名与服务名对不上&lt;/td&gt;
&lt;td&gt;&lt;code&gt;systemctl daemon-reload&lt;/code&gt; 后重试&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;改了配置重启还是旧行为&lt;/td&gt;
&lt;td&gt;没 daemon-reload 就 restart，加载的仍是内存里的旧 unit&lt;/td&gt;
&lt;td&gt;先 reload，再 restart&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;服务能跑但不开机自启&lt;/td&gt;
&lt;td&gt;没 enable，或 unit 缺 [Install] 段，或 WantedBy 写错目标&lt;/td&gt;
&lt;td&gt;补 [Install] 段 &lt;code&gt;WantedBy=multi-user.target&lt;/code&gt;，再 &lt;code&gt;enable&lt;/code&gt; 并用 &lt;code&gt;is-enabled&lt;/code&gt; 验证&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;反复重启刷日志&lt;/td&gt;
&lt;td&gt;程序启动即崩，或 Type 选错（simple 配了自后台化程序）&lt;/td&gt;
&lt;td&gt;journal 看崩溃原因；程序加前台参数或改 forking + PIDFile&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;达到启动上限不再拉起&lt;/td&gt;
&lt;td&gt;StartLimit 触发，unit 被标记 failed&lt;/td&gt;
&lt;td&gt;修因后 &lt;code&gt;systemctl reset-failed&lt;/code&gt; 再 start&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;端口已被占用&lt;/td&gt;
&lt;td&gt;老进程没停干净或另一个服务在用同一端口&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ss -tlnp&lt;/code&gt; 找占用者&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;203/EXEC 值得单独说&lt;/h3&gt;
&lt;p&gt;203 是新手期出现率最高的退出码，含义是「ExecStart 指向的东西根本执行不起来」。按这个顺序查，基本不会落空：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 文件在不在
ls -l /opt/myapi/venv/bin/python
# 2. 是不是可执行
file /opt/myapi/venv/bin/python
# 3. 脚本的话，第一行有没有 shebang、是不是 Unix 换行
head -1 /usr/local/bin/clean-myapp-logs.sh
# 4. 以服务用户身份手动跑一遍，看真实报错
sudo -u myapi /opt/myapi/venv/bin/python -m myapi.main
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第 4 步尤其关键：以 root 身份手动跑没问题，不代表换成服务用户也没问题——权限、环境变量、工作目录都可能不同。用服务用户原样复现，才算数。&lt;/p&gt;
&lt;h3&gt;一个完整的排障剧本&lt;/h3&gt;
&lt;p&gt;现象：&lt;code&gt;myapi&lt;/code&gt; 显示 failed。按顺序走：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl status myapi
# Active: failed，Main PID 退出码 status=203/EXEC

journalctl -u myapi -n 20 --no-pager
# 日志：Failed to execute /opt/myapi/venv/bin/python: Permission denied

ls -l /opt/myapi/venv/bin/python
# 发现是普通文件，执行位丢失（拷贝代码时丢了权限）

chmod +x /opt/myapi/venv/bin/python
sudo systemctl reset-failed myapi
sudo systemctl start myapi
systemctl is-active myapi   # active，收工
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;从 failed 到收工没猜一次，全靠 status 给方向、journal 给实锤。这就是 systemd 排障的正确节奏。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇把 systemd 的核心面过了一遍，最后收束成几条能带走的结论：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;systemd 是 PID 1 的总管，管服务只围着三样东西转：&lt;strong&gt;systemctl 命令、unit 文件、journalctl 日志&lt;/strong&gt;。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;start&lt;/code&gt; 管现在、&lt;code&gt;enable&lt;/code&gt; 管开机，两回事；新服务的标准动作是 &lt;code&gt;enable --now&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;unit 文件三段各司其职：[Unit] 管身份与依赖（After 管顺序、Wants 管拉起，要一起写）、[Service] 管进程怎么跑、[Install] 管自启登记（缺了它 enable 等于白登）。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;Type&lt;/code&gt; 按程序形态选：常驻前台用 simple，一次性任务用 oneshot，老 daemon 才用 forking。&lt;/li&gt;
&lt;li&gt;重启策略用 &lt;code&gt;Restart=on-failure&lt;/code&gt; + &lt;code&gt;RestartSec&lt;/code&gt; + [Unit] 段的 StartLimit 防疯拉；它管崩溃恢复，管不了开机自启。&lt;/li&gt;
&lt;li&gt;定时任务优先 timer：一对文件、能补跑、能查状态、能限资源，全面压过 cron。&lt;/li&gt;
&lt;li&gt;资源限制写进 unit 即可（MemoryMax / CPUQuota），但上限要按实测留余量。&lt;/li&gt;
&lt;li&gt;排障固定顺序：&lt;strong&gt;status 看现场 → journal 看全量 → cat 对配置&lt;/strong&gt;，203/EXEC 先查路径与权限。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;下一篇我们处理日志本身：journald 的日志怎么查、怎么限大小、怎么轮转，见 &lt;a href=&quot;/posts/linux-log-management/&quot;&gt;日志管理：journald 与日志轮转&lt;/a&gt;。&lt;/p&gt;
</content:encoded></item><item><title>tcpdump 抓包入门</title><link>https://www.anexns.cloudns.org/posts/linux-tcpdump-basics/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-tcpdump-basics/</guid><description>排障的最后一招是亲眼看包：tcpdump 的过滤表达式、抓 DNS 与 HTTP 的实战、存成 pcap 拖回 Wireshark 细看，以及抓不到包时的三个原因。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;日志说请求发出去了，&lt;code&gt;ss&lt;/code&gt; 显示连接卡在 SYN-SENT，对端运维却说&quot;我们这边什么都没收到&quot;。这种各执一词的局面，靠猜是猜不出结果的——到底是包没发出去、发出去了对端没回、还是回了被本机扔掉，只有把网卡上真实流过的包抓下来看一眼才算数。这就是 tcpdump 的位置：它不推测、不美化，只把经过网卡的每一个包原样摊给你看。&lt;/p&gt;
&lt;p&gt;本篇是 Linux 系列的第 20 篇，也是网络排障链条的最后一环。上一篇 &lt;a href=&quot;/posts/linux-network-troubleshooting/&quot;&gt;网络命令与排障&lt;/a&gt; 讲了怎么用 &lt;code&gt;ip&lt;/code&gt;、&lt;code&gt;ss&lt;/code&gt;、&lt;code&gt;curl&lt;/code&gt;、&lt;code&gt;dig&lt;/code&gt; 一层层缩小范围；当那些工具给出的结论互相矛盾时，就轮到抓包来一锤定音。本篇主线是：先讲清抓包能回答什么问题，再过最小命令与输出解读，然后是过滤表达式这套核心语法，最后落到抓 DNS、抓 TCP 握手两个实战，以及把包存成文件拖回本地细看的工作流。&lt;/p&gt;
&lt;p&gt;先立一条规矩：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;抓包之前先想清楚你要验证哪个假设&amp;lt;/span&amp;gt;。是想确认请求包到底发没发出？还是确认对端回没回？还是确认回来的是 RST 还是正常响应？没有假设地在生产机上漫无目的抓一把，得到的只会是几万行看不懂的输出，外加一个迅速膨胀的抓包文件。&lt;/p&gt;
&lt;h2&gt;一、定位：抓包到底能看什么&lt;/h2&gt;
&lt;p&gt;先把 tcpdump 能回答的问题和不能回答的问题分清，免得用错地方。&lt;/p&gt;
&lt;p&gt;日志是应用自己写的，它只能证明&quot;应用以为自己发了请求&quot;；&lt;code&gt;ss&lt;/code&gt; 显示的是内核维护的连接状态，它能告诉你连接停在哪一步，却说不清那一步的包在网线上是什么样。抓包看的是网卡收发的原始帧，它能回答的是这类问题：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;SYN 包到底有没有从本机发出去，发给了哪个 IP、哪个端口&lt;/li&gt;
&lt;li&gt;对端有没有回包，回的是 SYN+ACK 还是 RST&lt;/li&gt;
&lt;li&gt;DNS 查询到底问的是哪个服务器，对方答的又是什么&lt;/li&gt;
&lt;li&gt;一个请求发出去之后，隔了多久才收到回应——是网络慢，还是对端处理慢&lt;/li&gt;
&lt;li&gt;重传多不多，连接是不是在反复丢包中挣扎&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;它不能回答的问题也很明确：包的&lt;strong&gt;内容&lt;/strong&gt;如果是加密的，它看不见（第八节细说）；对端机器内部发生了什么，它也看不见——它只能证明&quot;包到没到网线这一层&quot;。所以抓包的正确用法是配合假设做验证：先用上一篇的方法把问题缩到&quot;怀疑包根本没到对端&quot;，再抓包确认，而不是一上来就抓。&lt;/p&gt;
&lt;h2&gt;二、准备：安装、权限与选网卡&lt;/h2&gt;
&lt;p&gt;tcpdump 在大多数发行版里可以直接装：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo apt install tcpdump     # Debian / Ubuntu
sudo dnf install tcpdump     # RHEL 系
tcpdump --version            # 确认装好
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;抓包要读网卡的原始流量，所以必须用 root 权限跑，普通用户执行会直接报权限错误，这不是故障，是设计如此：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo tcpdump -i eth0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;选网卡是第一个容易踩的点。先列出所有可抓的接口：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo tcpdump -D
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出类似 &lt;code&gt;1.eth0&lt;/code&gt;、&lt;code&gt;2.lo&lt;/code&gt;、&lt;code&gt;3.any&lt;/code&gt;。几个接口的区别要分清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;接口&lt;/th&gt;
&lt;th&gt;抓什么&lt;/th&gt;
&lt;th&gt;适用场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;eth0&lt;/code&gt; 等具体网卡&lt;/td&gt;
&lt;td&gt;只抓这块网卡进出的包&lt;/td&gt;
&lt;td&gt;已确定流量走哪块网卡时，最干净&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;lo&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;本机回环流量（127.0.0.1 互访）&lt;/td&gt;
&lt;td&gt;服务调本机另一个服务时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;any&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;所有网卡的包一起抓&lt;/td&gt;
&lt;td&gt;不确定流量走哪块网卡时先用它定位&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;新手建议先从 &lt;code&gt;-i any&lt;/code&gt; 入手，确认流量在哪块网卡上之后，再换到具体网卡抓一份干净的。但要注意 &lt;code&gt;any&lt;/code&gt; 抓到的包在链路层信息上和真实网卡略有差别，做精细分析时以具体网卡为准。&lt;/p&gt;
&lt;h2&gt;三、最小命令与输出解读&lt;/h2&gt;
&lt;p&gt;先跑一条最小命令，只抓 4 个包就停：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo tcpdump -i any -nn -c 4
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;不加任何过滤时，它会把所有包都打出来，屏幕滚动极快，&lt;code&gt;-c 4&lt;/code&gt; 限量是必需的。一行典型输出长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;14:03:21.482913 IP 192.168.1.10.52314 &amp;gt; 203.0.113.25.443: Flags [S], seq 3811223841, length 0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐段拆开读，这是后面所有分析的基础：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;示例&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;时间戳&lt;/td&gt;
&lt;td&gt;&lt;code&gt;14:03:21.482913&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;包经过网卡的时刻，精确到微秒，比对时序全靠它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;协议&lt;/td&gt;
&lt;td&gt;&lt;code&gt;IP&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;网络层协议，IPv6 时显示 &lt;code&gt;IP6&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;源地址.端口&lt;/td&gt;
&lt;td&gt;&lt;code&gt;192.168.1.10.52314&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;谁发的；点号后面是源端口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;目的地址.端口&lt;/td&gt;
&lt;td&gt;&lt;code&gt;203.0.113.25.443&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;发给谁；&lt;code&gt;&amp;gt;&lt;/code&gt; 的方向就是包的方向&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;标志位&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Flags [S]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;TCP 标志，握手分析全看它，下一节详解&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;序号&lt;/td&gt;
&lt;td&gt;&lt;code&gt;seq 3811223841&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;TCP 序列号，看重传与丢包时用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;长度&lt;/td&gt;
&lt;td&gt;&lt;code&gt;length 0&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;这个包带的数据长度，0 表示纯控制包（如握手包）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;标志位是读 TCP 包的核心，先把字母对照记住：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;标志&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;什么时候出现&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;S&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;SYN，发起连接&lt;/td&gt;
&lt;td&gt;三次握手的第一步&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;S.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;SYN+ACK（&lt;code&gt;.&lt;/code&gt; 代表 ACK）&lt;/td&gt;
&lt;td&gt;握手的第二步，对端同意&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;ACK，纯确认&lt;/td&gt;
&lt;td&gt;握手第三步，以及连接中的确认包&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;P.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;PSH+ACK，带数据推送&lt;/td&gt;
&lt;td&gt;真正传数据的包&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;F.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;FIN+ACK，请求关闭&lt;/td&gt;
&lt;td&gt;正常断开连接时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;R.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;RST，强制断开&lt;/td&gt;
&lt;td&gt;对端拒绝或异常终止，排障时高度警惕&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;四、过滤表达式：抓包的真正门槛&lt;/h2&gt;
&lt;p&gt;不加过滤的抓包在生产机上等于大海捞针。tcpdump 的过滤表达式（BPF 语法）才是它真正的核心技能，学会组合这几个原语，绝大多数场景都够用。&lt;/p&gt;
&lt;p&gt;基本原语：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;host 203.0.113.25              # 源或目的 IP 是它（双向）
src host 192.168.1.10          # 只看源是它的
dst host 203.0.113.25          # 只看目的是它的
port 53                        # 源或目的端口是 53（双向）
dst port 443                   # 只看目的端口 443
portrange 8000-9000            # 端口范围
tcp                              # 只看 TCP
udp                              # 只看 UDP
icmp                             # 只看 ICMP（ping 的包）
net 203.0.113.0/24             # 整个网段
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;组合靠 &lt;code&gt;and&lt;/code&gt;、&lt;code&gt;or&lt;/code&gt;、&lt;code&gt;not&lt;/code&gt;（也可以写 &lt;code&gt;&amp;amp;&amp;amp;&lt;/code&gt;、&lt;code&gt;||&lt;/code&gt;、&lt;code&gt;!&lt;/code&gt;），复杂组合加括号。注意表达式里带空格和括号时，整条表达式要用引号包住，免得被 Shell 拆开：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 只看本机与某台服务器之间的 HTTPS 流量
sudo tcpdump -i any -nn &apos;host 203.0.113.25 and port 443&apos;

# 排除自己的 SSH 会话，否则抓包输出会把 SSH 流量也灌进来
sudo tcpdump -i any -nn &apos;not port 22&apos;

# 看某台主机除 22 以外的全部 TCP
sudo tcpdump -i any -nn &apos;host 203.0.113.25 and tcp and not port 22&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;常用组合速查：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;想看什么&lt;/th&gt;
&lt;th&gt;过滤表达式&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;与某主机的全部往来&lt;/td&gt;
&lt;td&gt;&lt;code&gt;host 203.0.113.25&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;某主机的 DNS 查询&lt;/td&gt;
&lt;td&gt;&lt;code&gt;host 203.0.113.53 and port 53&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;某服务的入站请求&lt;/td&gt;
&lt;td&gt;&lt;code&gt;dst port 80&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;某客户端访问某服务&lt;/td&gt;
&lt;td&gt;&lt;code&gt;src host 192.168.1.10 and dst port 443&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;只看握手与断开（无数据包）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;tcp[tcpflags] &amp;amp; (tcp-syn|tcp-fin|tcp-rst) != 0&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;排除 SSH 与监控噪声&lt;/td&gt;
&lt;td&gt;&lt;code&gt;not port 22 and not port 10050&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;最后一条按标志位过滤的写法属于进阶语法，不必背，知道有这回事、需要时查出来用即可。日常排障里 &lt;code&gt;host + port + 协议&lt;/code&gt; 三件套的组合，已经能覆盖九成场景。&lt;/p&gt;
&lt;h2&gt;五、输出控制：让结果可读&lt;/h2&gt;
&lt;p&gt;过滤解决了&quot;抓哪些&quot;，输出参数解决&quot;怎么看&quot;。几个高频参数：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-nn&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不解析&lt;/td&gt;
&lt;td&gt;主机名和端口名都不做反查，直接显示 IP 和端口数字；不加的话 tcpdump 会去反查 DNS，又慢又干扰，排障时必加&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-v&lt;/code&gt; / &lt;code&gt;-vv&lt;/code&gt; / &lt;code&gt;-vvv&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;详细程度递增&lt;/td&gt;
&lt;td&gt;多打 TTL、校验和、TCP 选项等细节，按需开&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-c N&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;限量&lt;/td&gt;
&lt;td&gt;抓满 N 个包自动停，防止跑飞&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-A&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;ASCII 显示内容&lt;/td&gt;
&lt;td&gt;把包内数据按文本打出来，看 HTTP 这类明文协议用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-X&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;十六进制＋ASCII 并排&lt;/td&gt;
&lt;td&gt;看二进制协议时用，日常较少&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-l&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;行缓冲&lt;/td&gt;
&lt;td&gt;输出重定向到文件或管道时实时刷出&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--time-stamp-precision=nano&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;纳秒时间戳&lt;/td&gt;
&lt;td&gt;做精细时序分析时才需要&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一个实用的日常组合是：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo tcpdump -i any -nn -c 100 &apos;host 203.0.113.25 and port 443&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;先限定一百个包看看形态，确认过滤写对了，再决定要不要放开了抓或者存文件。&lt;/p&gt;
&lt;h2&gt;六、实战一：抓 DNS，看解析到底问了谁&lt;/h2&gt;
&lt;p&gt;场景：服务器上某域名解析结果不对，或者解析时快时慢。上一篇用 &lt;code&gt;dig&lt;/code&gt; 能看到&quot;问某个服务器得到什么答案&quot;，抓包则能看到应用&lt;strong&gt;实际&lt;/strong&gt;发出的查询——应用用的解析服务器、查询有没有发出、回应到底回没回，一清二楚。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo tcpdump -i any -nn port 53
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后在另一个终端触发一次解析（&lt;code&gt;ping&lt;/code&gt; 一个域名或 &lt;code&gt;dig example.com&lt;/code&gt;），抓包窗口会出现成对的输出：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;14:05:01.102233 IP 192.168.1.10.53122 &amp;gt; 192.168.1.1.53: 40231+ A? example.com. (29)
14:05:01.109845 IP 192.168.1.1.53 &amp;gt; 192.168.1.10.53122: 40231 1/0/0 A 203.0.113.80 (45)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;读法：第一行是本机向 &lt;code&gt;192.168.1.1&lt;/code&gt; 的 53 端口发出查询，&lt;code&gt;A?&lt;/code&gt; 表示问 A 记录，后面的数字是查询 ID；第二行是对方的回应，同一个 ID，&lt;code&gt;1/0/0&lt;/code&gt; 表示 1 条答案记录，答案是 &lt;code&gt;203.0.113.80&lt;/code&gt;。两行时间戳相减，约 7 毫秒，就是这次解析的真实耗时。&lt;/p&gt;
&lt;p&gt;三种典型结论一眼可辨：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;只有查询没有回应&lt;/strong&gt;：包发出去了，对方没答。要么上游 DNS 服务器有问题，要么中间防火墙把回包拦了——问题不在本机应用。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;查询发往的服务器和你以为的不一样&lt;/strong&gt;：比如你以为系统用的是公共 DNS，包却发给了路由器地址，说明 &lt;code&gt;/etc/resolv.conf&lt;/code&gt; 或应用自带的解析配置和你的认知不一致。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;回应里答案和预期不同&lt;/strong&gt;：解析链路本身没毛病，是权威数据或缓存的问题，换方向去查记录本身。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
抓 DNS 时如果看到查询根本没有发出，先别怀疑网络——更常见的是应用走了自己的缓存，或者用了 DoH（加密 DNS）压根不走 53 端口。抓不到 53 端口的包，不等于没有发生解析。
:::&lt;/p&gt;
&lt;h2&gt;七、实战二：抓 TCP 握手，看连接卡在哪一步&lt;/h2&gt;
&lt;p&gt;场景：客户端连某服务超时，&lt;code&gt;ss&lt;/code&gt; 里看到一堆 SYN-SENT。到底是请求没发出去，还是对端不理？抓发起端的包：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo tcpdump -i any -nn &apos;host 203.0.113.25 and port 443&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后触发一次连接（&lt;code&gt;curl https://203.0.113.25/&lt;/code&gt; 或让应用重试一次）。健康的握手是三行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;14:07:11.001 IP 192.168.1.10.52400 &amp;gt; 203.0.113.25.443: Flags [S], seq 1000, length 0
14:07:11.038 IP 203.0.113.25.443 &amp;gt; 192.168.1.10.52400: Flags [S.], seq 5000, ack 1001, length 0
14:07:11.038 IP 192.168.1.10.52400 &amp;gt; 203.0.113.25.443: Flags [.], ack 5001, length 0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;S&lt;/code&gt; 出去、&lt;code&gt;S.&lt;/code&gt; 回来、&lt;code&gt;.&lt;/code&gt; 确认，连接建立，之后才是 &lt;code&gt;P.&lt;/code&gt; 的数据包。对照异常形态看，结论非常硬：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;抓到的形态&lt;/th&gt;
&lt;th&gt;结论&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;只有一串 &lt;code&gt;S&lt;/code&gt;，间隔越来越长地重复，没有任何回包&lt;/td&gt;
&lt;td&gt;SYN 发出去了但石沉大海：对端不可达、中间被防火墙静默丢弃，或回程路由不通。本机应用没问题&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;S&lt;/code&gt; 出去，立刻回来一个 &lt;code&gt;R.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;对端主机在，但那个端口没人监听（或被防火墙以拒绝方式拦截）。去查对端服务起没起、端口对不对&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;S.&lt;/code&gt; 正常回来，但本机没发第三步 &lt;code&gt;.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;极少见，多半是本机防火墙规则把入站回包拦了，查本机 iptables/nftables&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;握手正常，数据包阶段大量重传&lt;/td&gt;
&lt;td&gt;连接能建但质量差，丢包或 MTU 问题，换方向查链路质量&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;注意第一种形态里 SYN 会重复出现，那是 TCP 的重传机制在按指数退避重试——这恰恰证明本机一直在努力发，锅不在应用层。把这三行（或这一串）截图发给对端运维，比十句&quot;我们这边发出去了&quot;都有说服力。&lt;/p&gt;
&lt;h2&gt;八、HTTPS 的边界：加密流量能看什么&lt;/h2&gt;
&lt;p&gt;必须先泼一盆冷水：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;HTTPS 的内容是加密的，tcpdump 抓到也看不见明文&amp;lt;/span&amp;gt;，谁要是说能直接抓出 HTTPS 里的请求内容，那是另一套需要私钥或中间人的玩法，不在入门范围。&lt;/p&gt;
&lt;p&gt;但&quot;看不见内容&quot;不等于&quot;没用&quot;。TLS 流量能看的元信息仍然很多：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;连接建没建起来（握手包在不在、TLS 握手有没有完成）&lt;/li&gt;
&lt;li&gt;目标 IP 与端口、连接时长、总流量大小&lt;/li&gt;
&lt;li&gt;TLS 握手初期的 ClientHello 里带有 SNI，也就是你访问的域名——这一段在加密开始之前，是明文可见的，用 &lt;code&gt;-A&lt;/code&gt; 或存包到 Wireshark 里能看到&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;所以排 HTTPS 的故障，抓包能回答&quot;连没连上、连的谁、卡在握手哪一步&quot;，回答不了&quot;请求参数对不对&quot;。后者要去看应用日志或在服务端侧解决，两者别混淆。&lt;/p&gt;
&lt;h2&gt;九、存包细看：pcap 与 Wireshark 工作流&lt;/h2&gt;
&lt;p&gt;终端里刷屏看包只适合快速验证。稍微复杂一点的分析，正确姿势是把包存成 pcap 文件，拖回本地用 Wireshark 慢慢看——有过滤高亮、流量图、追踪单个连接的完整视图，效率完全不是一个量级。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 抓 200 个包存文件，Ctrl+C 也可随时停
sudo tcpdump -i any -nn -c 200 -w /tmp/dns.pcap &apos;port 53&apos;

# 在服务器上直接读回这个文件
sudo tcpdump -r /tmp/dns.pcap -nn

# 拉回本地（在你的电脑上执行）
scp user@server:/tmp/dns.pcap ./
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后用 Wireshark 打开 &lt;code&gt;dns.pcap&lt;/code&gt;，在显示过滤器里用 &lt;code&gt;dns&lt;/code&gt;、&lt;code&gt;tcp.port == 443&lt;/code&gt;、&lt;code&gt;tcp.flags.reset == 1&lt;/code&gt; 这类表达式筛，比在终端里翻屏舒服得多。&lt;/p&gt;
&lt;p&gt;长时间抓包要防文件失控，可以按大小轮转：&lt;code&gt;-C 100&lt;/code&gt; 表示每个文件 100 MB 换一个，&lt;code&gt;-W 5&lt;/code&gt; 表示最多保留 5 个滚动覆盖。两者一起用，磁盘占用就有硬上限：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo tcpdump -i eth0 -nn -C 100 -W 5 -w /tmp/cap.pcap &apos;port 443&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
在生产机上&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不加过滤、不加限量地抓包是最危险的用法&amp;lt;/span&amp;gt;：流量大的机器几秒钟就能写出几个 GB 的文件，把磁盘打满，进而把真正的业务拖垮。抓之前先把过滤表达式写窄，再加 &lt;code&gt;-c&lt;/code&gt; 或 &lt;code&gt;-C/-W&lt;/code&gt; 限量，这两步不能省。
:::&lt;/p&gt;
&lt;h2&gt;十、纪律与排障&lt;/h2&gt;
&lt;p&gt;纪律先说清。抓包抓到的是真实业务流量，里面可能有别人的请求内容和敏感数据，所以只抓与当前故障直接相关的流量、只在你有权限分析的机器上抓、分析完及时删掉 pcap 文件。这不是客套，是职业边界。&lt;/p&gt;
&lt;p&gt;再说抓包本身的排障——最常见的问题是&quot;我明明抓了，怎么一个包都没有&quot;。按概率排，就三个原因：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;网卡选错了&lt;/strong&gt;。流量走 &lt;code&gt;eth1&lt;/code&gt; 你抓了 &lt;code&gt;eth0&lt;/code&gt;，或者服务走的是回环你抓了物理网卡。先用 &lt;code&gt;-i any&lt;/code&gt; 验证流量存在，再缩小到具体网卡。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;流量根本没经过本机&lt;/strong&gt;。比如你在服务端抓包，但客户端连的是另一台机器；或者流量走了容器网桥、隧道接口，物理网卡上只有加密后的外层包。先确认这台机器在流量路径上，再谈抓包。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;被自己的过滤表达式排除了&lt;/strong&gt;。&lt;code&gt;and&lt;/code&gt; 写多了条件互相矛盾、IP 写错一位、端口写反了方向，都会让结果为空。排查方法是逐段放宽：先只留 &lt;code&gt;host&lt;/code&gt;，确认有包，再一段段把条件加回去，加到哪段没包了，哪段就是写错的。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;另外两种&quot;抓到了但不对&quot;的情况也提一句：抓到的时间戳和日志对不上，多半是服务器时区或时钟问题，先 &lt;code&gt;timedatectl&lt;/code&gt; 确认；抓包里看到大量校验和错误（Wireshark 里会标红），在物理网卡上多半是网卡的 checksum offload 没卸载到抓包路径导致的假象，不是真丢包，别被它带偏。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;tcpdump 的价值是看网线上的真相：包发没发、对端回没回、回的是什么，专治日志与状态互相矛盾的扯皮局&lt;/li&gt;
&lt;li&gt;抓之前先定假设，抓的时候过滤写窄、数量设限，顺序反了只会淹没在输出里&lt;/li&gt;
&lt;li&gt;读包先认六个标志位：&lt;code&gt;S&lt;/code&gt; 发起、&lt;code&gt;S.&lt;/code&gt; 同意、&lt;code&gt;.&lt;/code&gt; 确认、&lt;code&gt;P.&lt;/code&gt; 数据、&lt;code&gt;F.&lt;/code&gt; 关闭、&lt;code&gt;R.&lt;/code&gt; 拒绝，握手三行就能定性大多数连接故障&lt;/li&gt;
&lt;li&gt;DNS 抓包看问答配对与耗时；握手抓包看形态：只有 SYN 是不通，回 RST 是端口没人，握手正常数据重传是链路质量&lt;/li&gt;
&lt;li&gt;HTTPS 只能看元信息（目标、时序、SNI），内容看不见，别在这上面浪费时间&lt;/li&gt;
&lt;li&gt;复杂分析别硬看终端：&lt;code&gt;-w&lt;/code&gt; 存 pcap，拖回 Wireshark 才是正经工作流，轮转参数给文件大小上保险&lt;/li&gt;
&lt;li&gt;抓不到包先查三件事：网卡选错、流量没经过本机、过滤把自己想要的包排除了&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>文本处理三剑客：grep、sed、awk</title><link>https://www.anexns.cloudns.org/posts/linux-text-processing/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-text-processing/</guid><description>在日志与配置里大海捞针的本事：grep 定位、sed 批量改、awk 做统计，配上管道组合的三个运维实战——统计访问 IP、批量改配置、提取错误行。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;服务器上绝大多数信息都是文本：日志是文本，配置是文本，命令的输出也是文本。运维干久了你会发现，每天真正在做的事，一大半是「从一大堆文本里把有用的那几行捞出来」，或者「把一批文件里的某个值统一改掉」。干这两件事的工具很多，但绕来绕去，最后沉淀下来的就是这三个：grep、sed、awk，江湖人称「三剑客」。&lt;/p&gt;
&lt;p&gt;这篇不打算把它们写成手册——手册有 man 页，而且写得比谁都全。这篇只讲运维场景里真正高频的那部分：grep 怎么把行定位出来，sed 怎么安全地批量改文件，awk 怎么把字段拆出来做统计，最后用三个完整实战把它们和管道串起来。学完这一篇，配合前面的&lt;a href=&quot;/posts/linux-log-management/&quot;&gt;日志管理篇&lt;/a&gt;，你在服务器上翻日志、改配置、做统计基本就不求人了。&lt;/p&gt;
&lt;h2&gt;先分工：谁找、谁改、谁算&lt;/h2&gt;
&lt;p&gt;三剑客经常被一起提，但它们的活儿分得很清。先把分工记住，后面选工具就不会纠结：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;工具&lt;/th&gt;
&lt;th&gt;一句话定位&lt;/th&gt;
&lt;th&gt;擅长&lt;/th&gt;
&lt;th&gt;不擅长&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;grep&lt;/td&gt;
&lt;td&gt;找&lt;/td&gt;
&lt;td&gt;按内容把符合条件的&lt;strong&gt;行&lt;/strong&gt;筛出来&lt;/td&gt;
&lt;td&gt;改文件、做计算&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;sed&lt;/td&gt;
&lt;td&gt;改&lt;/td&gt;
&lt;td&gt;按行批量替换、删除、插入文本&lt;/td&gt;
&lt;td&gt;跨字段统计、复杂逻辑&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;awk&lt;/td&gt;
&lt;td&gt;算&lt;/td&gt;
&lt;td&gt;把行拆成&lt;strong&gt;字段&lt;/strong&gt;，统计、求和、格式化输出&lt;/td&gt;
&lt;td&gt;原地改文件（默认只输出）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一个粗略的心智模型：数据是一条河，grep 是渔网，只捞符合特征的鱼；sed 是流水线上的加工台，东西过一遍就变个样；awk 是会计，把每条记录拆开记账，最后能出报表。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;三者的边界就是：按行筛选用 grep，按行修改用 sed，按列计算用 awk。&amp;lt;/span&amp;gt;实际工作中它们很少单独出现，往往是一条管道里各干一段，这正是 Unix 的设计哲学——每个工具只做一件事，然后组合起来。&lt;/p&gt;
&lt;h2&gt;grep：先把行捞出来&lt;/h2&gt;
&lt;p&gt;grep 的名字来自编辑器命令 g/re/p（global regular expression print），干的事一句话：&lt;strong&gt;输出所有包含指定模式的行&lt;/strong&gt;。最基础的用法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;grep &quot;error&quot; /var/log/app.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这会打印 app.log 里所有包含 error 的行。就这么简单，但实战中真正好用的是一批选项。&lt;/p&gt;
&lt;h3&gt;常用选项速查&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;选项&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;典型场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;-i&lt;/td&gt;
&lt;td&gt;忽略大小写&lt;/td&gt;
&lt;td&gt;日志里 Error/ERROR/error 混写时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;-v&lt;/td&gt;
&lt;td&gt;反选，输出&lt;strong&gt;不&lt;/strong&gt;包含的行&lt;/td&gt;
&lt;td&gt;把已知噪音过滤掉看剩下的&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;-n&lt;/td&gt;
&lt;td&gt;显示行号&lt;/td&gt;
&lt;td&gt;定位后还要去编辑器里改那一行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;-c&lt;/td&gt;
&lt;td&gt;只输出匹配的行数&lt;/td&gt;
&lt;td&gt;先看看量级，再决定怎么处理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;-r / -R&lt;/td&gt;
&lt;td&gt;递归搜索整个目录&lt;/td&gt;
&lt;td&gt;在一堆配置里找某个值是谁配的&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;-l&lt;/td&gt;
&lt;td&gt;只列出包含匹配的&lt;strong&gt;文件名&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;先圈范围，再逐个处理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;-A n&lt;/td&gt;
&lt;td&gt;连带输出匹配行&lt;strong&gt;后面&lt;/strong&gt; n 行&lt;/td&gt;
&lt;td&gt;看报错之后的堆栈&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;-B n&lt;/td&gt;
&lt;td&gt;连带输出匹配行&lt;strong&gt;前面&lt;/strong&gt; n 行&lt;/td&gt;
&lt;td&gt;看报错之前的上下文&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;-C n&lt;/td&gt;
&lt;td&gt;前后各 n 行（等于 -A n -B n）&lt;/td&gt;
&lt;td&gt;最常用的上下文查看方式&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;-o&lt;/td&gt;
&lt;td&gt;只输出匹配到的部分，不输出整行&lt;/td&gt;
&lt;td&gt;提取 IP、邮箱这类片段&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;-a&lt;/td&gt;
&lt;td&gt;把二进制文件当文本处理&lt;/td&gt;
&lt;td&gt;grep 说 &quot;Binary file matches&quot; 时&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个例子感受一下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 忽略大小写数一下今天有多少条错误
grep -ci &quot;error&quot; /var/log/app.log

# 看某次报错的完整上下文（前后各 5 行）
grep -C 5 &quot;OutOfMemory&quot; /var/log/app.log

# 在整个配置目录里找谁写了 8080 这个端口
grep -rn &quot;8080&quot; /etc/myapp/

# 排除掉健康检查的噪音，只看真实请求
grep -v &quot;healthcheck&quot; /var/log/nginx/access.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;还有个小习惯：让 grep 把匹配部分标红，肉眼扫起来快很多。很多发行版默认已经 alias 好了，没有的话自己加：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;alias grep=&apos;grep --color=auto&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把这行写进 &lt;code&gt;~/.bashrc&lt;/code&gt; 就长期生效。注意 &lt;code&gt;--color=auto&lt;/code&gt; 只在输出到终端时上色，管道传给别的命令时自动关掉，不会污染数据，放心用。&lt;/p&gt;
&lt;h3&gt;模式不只是固定字符串&lt;/h3&gt;
&lt;p&gt;grep 的模式支持正则表达式。用 &lt;code&gt;-E&lt;/code&gt; 开启扩展正则（等价于老命令 egrep），就能写「或」「重复」这类模式：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 同时找 error 和 fatal 两种行
grep -Ei &quot;error|fatal&quot; /var/log/app.log

# 找以数字开头的行
grep -E &quot;^[0-9]&quot; data.txt

# 找包含 IP 形态的行（粗筛，够用）
grep -E &quot;[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+&quot; access.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;扩展正则里最常用的元字符就这么几个，后面正则一节统一交代。先记住一点：模式要用引号包起来，否则里面的 &lt;code&gt;|&lt;/code&gt;、&lt;code&gt;*&lt;/code&gt; 会被 Shell 先截胡解释，查出来的结果莫名其妙。&lt;/p&gt;
&lt;h2&gt;正则最小集：够用就停&lt;/h2&gt;
&lt;p&gt;三剑客共用正则表达式这门「语言」，但不需要你把正则学成一门课。运维日常里 95% 的场景，下面这个最小集就够了：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;写法&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;例子&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;^&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;行首&lt;/td&gt;
&lt;td&gt;&lt;code&gt;^Error&lt;/code&gt; 只匹配行首的 Error&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;$&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;行尾&lt;/td&gt;
&lt;td&gt;&lt;code&gt;fail$&lt;/code&gt; 匹配以 fail 结尾的行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;任意一个字符&lt;/td&gt;
&lt;td&gt;&lt;code&gt;a.c&lt;/code&gt; 能匹配 abc、aXc&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;*&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;前面的字符出现 0 次或多次&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ab*&lt;/code&gt; 匹配 a、ab、abb&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;+&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;前面的字符出现 1 次或多次（需 -E）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;[0-9]+&lt;/code&gt; 匹配一串数字&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;[]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;字符集，匹配其中任意一个&lt;/td&gt;
&lt;td&gt;&lt;code&gt;[0-9]&lt;/code&gt; 一个数字，&lt;code&gt;[a-z]&lt;/code&gt; 一个小写字母&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;[^]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;取反字符集&lt;/td&gt;
&lt;td&gt;&lt;code&gt;[^0-9]&lt;/code&gt; 一个非数字字符&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;|&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;或（grep -E 里直接写 &lt;code&gt;|&lt;/code&gt;）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;error|warn&lt;/code&gt; 二选一&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\b&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;单词边界&lt;/td&gt;
&lt;td&gt;&lt;code&gt;\broot\b&lt;/code&gt; 只匹配独立的 root 这个词&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;关于 &lt;code&gt;\d&lt;/code&gt; 要特别说明一句：&lt;strong&gt;grep 和 sed 的正则里没有 &lt;code&gt;\d&lt;/code&gt; 这个写法&lt;/strong&gt;。&lt;code&gt;\d&lt;/code&gt; 是 Perl 风格正则的简写，想表示数字就老老实实写 &lt;code&gt;[0-9]&lt;/code&gt;；表示空白用 &lt;code&gt;[[:space:]]&lt;/code&gt; 或直接写空格和 &lt;code&gt;\t&lt;/code&gt;。很多人在这儿栽过跟头——从网上抄来的 &lt;code&gt;\d+&lt;/code&gt; 在 grep 里要么报错要么匹配不到东西，还以为是数据的问题。用 grep 时需要 &lt;code&gt;\d&lt;/code&gt; 语义，可以加 &lt;code&gt;-P&lt;/code&gt; 让它走 Perl 正则引擎：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;grep -P &quot;\d+\.\d+\.\d+\.\d+&quot; access.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;但 &lt;code&gt;-P&lt;/code&gt; 不是所有环境都有（精简系统、容器镜像里可能缺），脚本里要跨机器跑的话，还是 &lt;code&gt;[0-9]&lt;/code&gt; 最稳妥。&lt;/p&gt;
&lt;p&gt;还有一个新手最容易混淆的点：正则里的 &lt;code&gt;.&lt;/code&gt; 是「任意字符」，想匹配真正的点号（比如 IP 里的点）要写 &lt;code&gt;\.&lt;/code&gt;。&lt;code&gt;192.168.1.1&lt;/code&gt; 这个模式里的点能匹配任意字符，所以它连 &lt;code&gt;192x168y1z1&lt;/code&gt; 也能匹配上——日常粗筛无所谓，要精确就写成 &lt;code&gt;192\.168\.1\.1&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;sed：按行批量加工&lt;/h2&gt;
&lt;p&gt;sed 是 stream editor（流编辑器）：文本像水一样从它面前流过，它按规则加工后输出。最核心的命令是 &lt;code&gt;s&lt;/code&gt; 替换：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sed &apos;s/旧内容/新内容/&apos; file.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意：这样只是把加工结果&lt;strong&gt;打印到屏幕&lt;/strong&gt;，原文件不动。先看效果、确认无误，再考虑写回，这是用 sed 的基本纪律，后面会专门强调。&lt;/p&gt;
&lt;h3&gt;替换的细节：范围与标志&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;s&lt;/code&gt; 命令的完整形态是 &lt;code&gt;s/模式/替换/标志&lt;/code&gt;，常用的标志：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 默认只换每行第一个匹配，想全换要加 g（global）
sed &apos;s/localhost/127.0.0.1/g&apos; hosts.txt

# 只换每行第 2 个匹配
sed &apos;s/:/-/2&apos; data.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;替换之前往往要先圈定「对哪些行下手」，这叫地址定界，两种方式：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 按行号：第 3 行到第 5 行
sed &apos;3,5s/old/new/g&apos; file.txt

# 按模式：只改包含 [server] 的那一行附近……更常用的是直接定位包含特征的行
sed &apos;/^port/s/8080/9090/&apos; app.conf

# 组合：从匹配 START 的行到匹配 END 的行之间都改
sed &apos;/START/,/END/s/old/new/g&apos; file.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;除了替换，另一个高频动作是删除 &lt;code&gt;d&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 删掉空行
sed &apos;/^$/d&apos; file.txt

# 删掉注释行
sed &apos;/^[[:space:]]*#/d&apos; app.conf

# 删掉第 10 行到第 20 行
sed &apos;10,20d&apos; file.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;分隔符冲突：换个分隔符就行&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;s&lt;/code&gt; 命令里 &lt;code&gt;/&lt;/code&gt; 只是习惯用的分隔符，不是规定。替换内容本身带斜杠时——比如改路径——继续用 &lt;code&gt;/&lt;/code&gt; 就得写一堆转义，丑且易错：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 难读的写法
sed &apos;s/\/var\/www\/html/\/srv\/www/g&apos; nginx.conf

# 换成 # 作分隔符，清爽
sed &apos;s#/var/www/html#/srv/www#g&apos; nginx.conf
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;分隔符可以是几乎任意字符，&lt;code&gt;#&lt;/code&gt;、&lt;code&gt;|&lt;/code&gt;、&lt;code&gt;:&lt;/code&gt; 都常见。处理路径、URL 时默认换成 &lt;code&gt;#&lt;/code&gt;，是老运维的肌肉记忆。&lt;/p&gt;
&lt;h3&gt;原地修改：-i 必须带备份&lt;/h3&gt;
&lt;p&gt;确认替换效果没问题后，用 &lt;code&gt;-i&lt;/code&gt; 把结果写回原文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sed -i &apos;s/8080/9090/g&apos; app.conf
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;sed -i&lt;/code&gt; 是直接改源文件的，命令写错没有撤销键。养成铁律：&lt;strong&gt;永远写成 &lt;code&gt;sed -i.bak&lt;/code&gt; 先留一份带 .bak 后缀的备份&lt;/strong&gt;，确认改对了再删备份；批量改之前，先用不带 &lt;code&gt;-i&lt;/code&gt; 的版本把输出打到屏幕上验一遍再执行。
:::&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 安全姿势：改完留下 app.conf.bak
sed -i.bak &apos;s/8080/9090/g&apos; app.conf

# 验证没问题后清理备份
rm app.conf.bak
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;GNU sed（Linux 上的）和 BSD sed（macOS 上的）在 &lt;code&gt;-i&lt;/code&gt; 的语法上有差异：macOS 上 &lt;code&gt;-i&lt;/code&gt; 后面必须跟后缀参数，&lt;code&gt;sed -i &apos;&apos; &apos;s/.../.../&apos;&lt;/code&gt; 才是 BSD 写法。在 Linux 服务器上写脚本不用管这事，但同一条命令想在自己 Mac 上也跑通时要留意。&lt;/p&gt;
&lt;h2&gt;awk：把行拆开算账&lt;/h2&gt;
&lt;p&gt;grep 和 sed 都是「整行」视角，awk 不一样：它把每一行按分隔符拆成若干&lt;strong&gt;字段&lt;/strong&gt;，你可以直接引用第几个字段做判断和计算。这是它做统计的根基。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 打印每行的第 1 个字段（默认按空白分隔：空格、制表符）
awk &apos;{print $1}&apos; access.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;字段的引用方式：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;写法&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;$0&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;整行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;$1&lt;/code&gt;、&lt;code&gt;$2&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;第 1、第 2 个字段&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;$NF&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;最后一个字段（NF 是字段总数）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;$(NF-1)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;倒数第二个字段&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;NR&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;当前是第几行（Number of Record）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;FNR&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;当前文件内的行号（处理多文件时与 NR 区分）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;$NF&lt;/code&gt; 特别实用：日志格式里前面字段数不固定时，从尾巴数往往更稳。比如取每行最后一个字段做统计，比数清楚前面有多少列靠谱得多。&lt;/p&gt;
&lt;h3&gt;指定分隔符 -F&lt;/h3&gt;
&lt;p&gt;字段默认按空白切，遇到逗号、冒号分隔的数据要用 &lt;code&gt;-F&lt;/code&gt; 指定：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# /etc/passwd 是冒号分隔，打印用户名和它的 shell
awk -F: &apos;{print $1, $7}&apos; /etc/passwd

# CSV 文件取第 3 列
awk -F, &apos;{print $3}&apos; data.csv

# 分隔符可以是多个字符或正则
awk -F&apos;[: ]+&apos; &apos;{print $2}&apos; mixed.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出时 &lt;code&gt;print $1, $7&lt;/code&gt; 里的逗号会让两个字段之间以空格（准确说是 OFS，输出字段分隔符）连接；写成 &lt;code&gt;print $1 $7&lt;/code&gt; 则直接拼在一起，中间什么都没有。这个区别在拼路径、拼命令时经常用到。&lt;/p&gt;
&lt;h3&gt;模式 + 动作：awk 的骨架&lt;/h3&gt;
&lt;p&gt;awk 程序的基本结构是「模式 {动作}」：模式决定哪些行执行动作，模式省略就是每一行都执行。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 只处理第 3 列大于 100 的行
awk &apos;$3 &amp;gt; 100 {print $1, $3}&apos; data.txt

# 只处理包含 ERROR 的行（模式可以是正则）
awk &apos;/ERROR/ {print $1}&apos; app.log

# 组合条件：状态码是 500 且路径带 /api
awk &apos;$9 == 500 &amp;amp;&amp;amp; $7 ~ /api/ {print $7}&apos; access.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个特殊模式要记住：&lt;code&gt;BEGIN&lt;/code&gt; 在处理任何数据之前执行（常用来打印表头、初始化变量），&lt;code&gt;END&lt;/code&gt; 在全部数据处理完之后执行（打印汇总结果）。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;awk &apos;BEGIN {print &quot;开始统计&quot;} {count++} END {print &quot;总行数:&quot;, count}&apos; app.log
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;求和与计数：两个万能模式&lt;/h3&gt;
&lt;p&gt;awk 做统计，翻来覆去就是两个套路。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;计数模式&lt;/strong&gt;——用数组当计数器：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 统计每个状态码出现了多少次
awk &apos;{cnt[$9]++} END {for (code in cnt) print code, cnt[code]}&apos; access.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里 &lt;code&gt;cnt[$9]++&lt;/code&gt; 的意思是：以第 9 个字段（状态码）为下标的数组元素加一。END 里用 for 循环把数组遍历出来。注意遍历顺序是无序的，要排序就接管道给 sort，后面实战里会看到。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;求和模式&lt;/strong&gt;——用普通变量累加：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 把第 10 列（响应字节数）全部加起来，算总流量
awk &apos;{sum += $10} END {print sum}&apos; access.log

# 带条件求和：只算状态码 200 的流量
awk &apos;$9 == 200 {sum += $10} END {print sum}&apos; access.log
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;管道组合：sort、uniq 与三剑客&lt;/h2&gt;
&lt;p&gt;三剑客很少单打独斗。把它们串起来的胶水是管道 &lt;code&gt;|&lt;/code&gt;，而管道里出镜率最高的配角是这三个：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;工具&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;关键选项&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;sort&lt;/td&gt;
&lt;td&gt;排序&lt;/td&gt;
&lt;td&gt;-n 按数字排、-r 逆序、-k 指定按哪列排、-t 指定列分隔符&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;uniq&lt;/td&gt;
&lt;td&gt;去重（需先排序）&lt;/td&gt;
&lt;td&gt;-c 在每行前加上出现次数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;wc&lt;/td&gt;
&lt;td&gt;计数&lt;/td&gt;
&lt;td&gt;-l 数行数、-w 数词数、-c 数字节数&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;其中最经典的组合是 &lt;code&gt;sort | uniq -c | sort -nr&lt;/code&gt;：先排序让相同行挨在一起，uniq -c 数出每种出现几次，再按数字逆序排，出现最多的自然冒到最前面。&lt;strong&gt;任何「统计 TOP N」的需求，骨架都是这一串&lt;/strong&gt;，区别只在喂给它的数据是什么。uniq 有个脾气：它只合并&lt;strong&gt;相邻&lt;/strong&gt;的重复行，所以前面必须先 sort，漏了这一步，去重和计数都会出错，这是新手最常见的翻车点之一。&lt;/p&gt;
&lt;h2&gt;实战一：统计访问日志 IP TOP 10&lt;/h2&gt;
&lt;p&gt;需求：Nginx 访问日志被打了，想看看来源 IP 都是谁，揪出请求量异常的那个。&lt;/p&gt;
&lt;p&gt;Nginx 默认 combined 日志格式里，第 1 个字段就是客户端 IP。所以流程是：awk 取第 1 列 → sort 让相同 IP 挨到一起 → uniq -c 计数 → sort -nr 按次数倒序 → head 取前 10：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;awk &apos;{print $1}&apos; /var/log/nginx/access.log \
  | sort \
  | uniq -c \
  | sort -nr \
  | head -10
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐段拆开看：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code&gt;awk &apos;{print $1}&apos;&lt;/code&gt;：把每行的 IP 单独抽出来，现在数据是一长列 IP；&lt;/li&gt;
&lt;li&gt;第一个 &lt;code&gt;sort&lt;/code&gt;：纯粹为 uniq 做准备，让相同 IP 相邻；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;uniq -c&lt;/code&gt;：输出变成「次数 IP」两列；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;sort -nr&lt;/code&gt;：&lt;code&gt;-n&lt;/code&gt; 按数字大小排（不加 -n 的话 &quot;100&quot; 会排在 &quot;99&quot; 前面，因为是按字符串比的），&lt;code&gt;-r&lt;/code&gt; 倒序，大数在前；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;head -10&lt;/code&gt;：只要前十名。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;输出长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;  15234 203.0.113.45
   8912 198.51.100.7
   3201 192.0.2.88
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第一名的请求量如果断层领先，大概率就是它了。这个骨架换个字段就能复用：把 &lt;code&gt;$1&lt;/code&gt; 换成 &lt;code&gt;$7&lt;/code&gt; 是请求路径 TOP，换成 &lt;code&gt;$9&lt;/code&gt; 是状态码分布，换成 &lt;code&gt;$12&lt;/code&gt;（User-Agent 字段，需注意带空格的字段切分问题）是客户端分布。关于访问日志各字段的含义和日志轮转，&lt;a href=&quot;/posts/linux-log-management/&quot;&gt;日志管理篇&lt;/a&gt;里有详细交代，可以对照着看。&lt;/p&gt;
&lt;h2&gt;实战二：批量改一批配置里的某个值&lt;/h2&gt;
&lt;p&gt;需求：&lt;code&gt;/etc/myapp/&lt;/code&gt; 下有十几个配置文件，里面的数据库地址全要从旧 IP 换成新 IP。手工逐个打开改，又慢又容易漏。正确姿势是三步走：&lt;strong&gt;先圈、再改、后核&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;第一步，用 grep 的 &lt;code&gt;-rl&lt;/code&gt; 先圈出到底哪些文件包含旧值（&lt;code&gt;-r&lt;/code&gt; 递归，&lt;code&gt;-l&lt;/code&gt; 只列文件名）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;grep -rl &quot;192.168.1.10&quot; /etc/myapp/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出是一个文件清单。先看这份清单合不合理——有没有混进不该改的文件（比如某个 .md 说明文档里也提到了旧 IP，那就不该动它）。&lt;/p&gt;
&lt;p&gt;第二步，对清单里的文件逐个执行 sed 替换。把 grep 的结果通过管道喂给 xargs：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;grep -rl &quot;192.168.1.10&quot; /etc/myapp/ \
  | xargs sed -i.bak &apos;s/192\.168\.1\.10/10.0.0.20/g&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意两个细节：模式里的点写成了 &lt;code&gt;\.&lt;/code&gt;，因为在正则里 &lt;code&gt;.&lt;/code&gt; 是任意字符，不转义的话 &lt;code&gt;192x168y1z10&lt;/code&gt; 也会被误伤；&lt;code&gt;-i.bak&lt;/code&gt; 给每个被改的文件都留了备份，真改错了还能整体回滚。&lt;/p&gt;
&lt;p&gt;第三步，复核。用 grep 确认旧值已经绝迹、新值处处到位：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 应该没有任何输出
grep -rn &quot;192\.168\.1\.10&quot; /etc/myapp/

# 应该能看到每个文件都换上了新值
grep -rn &quot;10\.0\.0\.20&quot; /etc/myapp/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;复核通过后再清理备份：&lt;code&gt;rm /etc/myapp/*.bak&lt;/code&gt;（路径按实际清单来）。&lt;/p&gt;
&lt;p&gt;:::warning
批量替换最怕的是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;被替换的字符串在别处还有别的含义&amp;lt;/span&amp;gt;——比如把端口 80 全局换成 8080，可能顺手把超时时间 80、版本号里的 80 一起改了。替换前先 &lt;code&gt;grep -n&lt;/code&gt; 把所有匹配行打出来逐行看一遍，确认每一处都该改，再动手。范围越大，这一步越不能省。
:::&lt;/p&gt;
&lt;h2&gt;实战三：提取某时段的错误行并计数&lt;/h2&gt;
&lt;p&gt;需求：应用日志是带时间戳的，想统计昨晚 22 点到 23 点之间 ERROR 出现了多少次、都是哪些。&lt;/p&gt;
&lt;p&gt;日志行长这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;2026-11-14 22:15:03 ERROR 数据库连接超时
2026-11-14 22:15:04 INFO  重试第 1 次
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;思路分两段：先用 grep 把 ERROR 行筛出来（缩小数据量），再用 awk 按时间字段过滤。第 2 个字段是时间 &lt;code&gt;22:15:03&lt;/code&gt;，字符串比较就能判断时段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;grep &quot;ERROR&quot; /var/log/app.log \
  | awk &apos;$2 &amp;gt;= &quot;22:00:00&quot; &amp;amp;&amp;amp; $2 &amp;lt; &quot;23:00:00&quot;&apos; \
  | wc -l
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里用的是字符串比较：时间格式是固定宽度的 &lt;code&gt;HH:MM:SS&lt;/code&gt;，字典序和时间先后恰好一致，所以字符串比大小没问题。但如果日志里的时间写成 &lt;code&gt;9:05:03&lt;/code&gt; 这种不补零的格式，字符串比较就会翻车（&quot;9&quot; 大于 &quot;22&quot;），遇到这种日志先确认格式再套这个方法。&lt;/p&gt;
&lt;p&gt;只要计数用 &lt;code&gt;wc -l&lt;/code&gt; 收尾即可；想同时看到具体内容，把 &lt;code&gt;wc -l&lt;/code&gt; 去掉；想按错误类型再分组统计，就再接 awk 计数：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;grep &quot;ERROR&quot; /var/log/app.log \
  | awk &apos;$2 &amp;gt;= &quot;22:00:00&quot; &amp;amp;&amp;amp; $2 &amp;lt; &quot;23:00:00&quot; {print $4}&apos; \
  | sort | uniq -c | sort -nr
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;（&lt;code&gt;$4&lt;/code&gt; 是示例日志里错误信息的位置，实际字段按你家日志格式数。）一条命令下来，「那个时段哪类错误最多」一目了然。这正是三剑客组合的典型形态：grep 负责粗筛，awk 负责精筛和拆字段，sort/uniq 负责汇总。&lt;/p&gt;
&lt;h2&gt;排障：三个高频翻车点&lt;/h2&gt;
&lt;h3&gt;sed 改完文件变空了&lt;/h3&gt;
&lt;p&gt;现象：执行完 sed -i，文件大小变成 0，内容全没了。&lt;/p&gt;
&lt;p&gt;常见原因是命令写错了还带上了重定向，比如把加工结果 &lt;code&gt;&amp;gt;&lt;/code&gt; 覆盖回原文件、而 sed 又因为语法错误没有输出，Shell 先把文件清空了，sed 却什么都没写进去。还有一种是 &lt;code&gt;-i&lt;/code&gt; 和脚本的写法在不同 sed 版本下解析不一致。&lt;/p&gt;
&lt;p&gt;预防就三条，都是前面强调过的纪律：第一，先不带 &lt;code&gt;-i&lt;/code&gt; 跑一遍看输出，输出为空或明显不对就停下查命令；第二，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;永远用 &lt;code&gt;-i.bak&lt;/code&gt; 留备份&amp;lt;/span&amp;gt;，文件真被改坏，把 .bak 拷回来就完事；第三，不要用 &lt;code&gt;sed &apos;...&apos; file &amp;gt; file&lt;/code&gt; 这种自己覆盖自己的写法，Shell 的重定向会在命令执行前就把文件截断，这是个经典陷阱。&lt;/p&gt;
&lt;h3&gt;grep 明明有内容却查不到&lt;/h3&gt;
&lt;p&gt;第一种情况是大小写：日志里写的是 &lt;code&gt;Error&lt;/code&gt;，你搜的是 &lt;code&gt;error&lt;/code&gt;，grep 默认区分大小写。拿不准就加 &lt;code&gt;-i&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;第二种情况更隐蔽：grep 输出一句 &lt;code&gt;Binary file /var/log/app.log matches&lt;/code&gt;，只告诉你「有」，不给具体行。这是因为文件里混进了不可打印字符（程序往日志里写了二进制数据、或者日志文件本身有损坏），grep 把它判定为二进制文件。加 &lt;code&gt;-a&lt;/code&gt; 强制当文本处理即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;grep -a &quot;ERROR&quot; /var/log/app.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第三种情况是模式被 Shell 吃了：&lt;code&gt;grep ERROR* log&lt;/code&gt; 里没加引号，&lt;code&gt;*&lt;/code&gt; 被 Shell 展开成当前目录的文件名列表，grep 实际搜的根本不是你想的那个模式。模式一律加引号，这是没有例外的习惯。&lt;/p&gt;
&lt;h3&gt;awk 字段对不上&lt;/h3&gt;
&lt;p&gt;现象：&lt;code&gt;print $7&lt;/code&gt; 打出来的东西明显不是想要的那一列，或者干脆是空的。&lt;/p&gt;
&lt;p&gt;根子基本在分隔符。默认按空白切分时，&lt;strong&gt;连续的空格、制表符会被合并成一个分隔&lt;/strong&gt;，这通常是好事；但如果数据里某个字段本身包含空格（比如日志里带空格的时间戳、User-Agent），按空白切出来的列数就会比预期多，后面所有列全部错位。排查方法是先把 &lt;code&gt;$0&lt;/code&gt; 和 &lt;code&gt;NF&lt;/code&gt; 一起打出来看看：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;awk &apos;{print NF, $0}&apos; data.txt | head
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;先确认每行到底被切成了几列，再决定取第几列。如果数据是逗号、冒号分隔而你忘了加 &lt;code&gt;-F&lt;/code&gt;，awk 会把整行当成一个字段，&lt;code&gt;$2&lt;/code&gt; 以后全是空的——这是最常见的对不上，检查命令里 &lt;code&gt;-F&lt;/code&gt; 写了没有、分隔符写对没有，往往就解决了。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇的东西收束成几句话：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;分工先行：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;grep 按行筛选、sed 按行修改、awk 按列计算&amp;lt;/span&amp;gt;，选工具不纠结；&lt;/li&gt;
&lt;li&gt;grep 的 &lt;code&gt;-C&lt;/code&gt; 看上下文、&lt;code&gt;-r&lt;/code&gt; 扫目录、&lt;code&gt;-a&lt;/code&gt; 对付被误判的二进制文件，是日常最顺手的三个选项；&lt;/li&gt;
&lt;li&gt;正则只记最小集：&lt;code&gt;^ $ . * + []&lt;/code&gt; 加上「点要转义、数字写 &lt;code&gt;[0-9]&lt;/code&gt;」，覆盖绝大多数场景；&lt;/li&gt;
&lt;li&gt;sed 的安全纪律是先看输出再落盘，&lt;code&gt;-i&lt;/code&gt; 必带 &lt;code&gt;.bak&lt;/code&gt; 备份，分隔符冲突就换分隔符；&lt;/li&gt;
&lt;li&gt;awk 记住 &lt;code&gt;$NF&lt;/code&gt;、&lt;code&gt;-F&lt;/code&gt;、模式加动作、END 里做汇总，计数和求和两个套路能拼出绝大部分统计需求；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;sort | uniq -c | sort -nr&lt;/code&gt; 是所有 TOP N 统计的通用骨架，实战里的 IP 排行、错误分布都是它的变体；&lt;/li&gt;
&lt;li&gt;批量改文件走「grep 圈范围 → sed 带备份改 → grep 复核」的三步流程，稳字当头。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;三剑客的命令细节远不止这些，但日常运维里反复用的就是这一篇覆盖的部分。剩下的，等你在实际场景里遇到了，再去翻 man 页对应的那一节——带着问题查手册，效率比通读一遍高得多。&lt;/p&gt;
</content:encoded></item><item><title>时间同步与时区：chrony 实战</title><link>https://www.anexns.cloudns.org/posts/linux-time-sync/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-time-sync/</guid><description>服务器时间不准，证书、日志、定时任务全会跟着乱：timedatectl 管时区、chrony 管对时，讲清 NTP 的取舍、偏差的查法与大偏差的修法。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;服务器上有一样东西，平时谁都不会多看一眼，出了问题却能让整台机器处处翻车——那就是时间。证书突然报过期、两台机器的日志怎么都对不上、定时任务在奇怪的时刻触发、登录令牌莫名其妙被判无效，追到最后，根源常常是同一个：这台机器的时钟不准，或者时区设错了。&lt;/p&gt;
&lt;p&gt;这一篇把时间这件事彻底讲清：先分清系统时间和硬件时钟、UTC 和本地时间这两组概念，再用 &lt;code&gt;timedatectl&lt;/code&gt; 把时区和同步状态管起来，然后对比 systemd-timesyncd、chrony、ntpd 三种对时方案，最后落到 chrony 的完整实战——怎么看偏差、怎么看时间源质量、小偏差怎么慢慢修正、大偏差怎么一次性步进纠正。时间这件事配好一次，之后很多年都不用再管它，但配错一次，它会在最意想不到的地方反复咬你。&lt;/p&gt;
&lt;h2&gt;一、时间为什么是基础设施&lt;/h2&gt;
&lt;p&gt;很多人觉得时间不准几秒无所谓。放在个人电脑上确实无所谓，放在服务器上，它是很多机制的隐含前提，前提一塌，上面全乱。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;TLS 证书校验对时间的要求。&lt;/strong&gt; 证书有生效时间和到期时间，客户端校验时会拿本机时间去比对。机器时间快了，证书会被判「尚未生效」；慢了，会被判「已经过期」。最典型的翻车现场：新装的机器时间差了几天，&lt;code&gt;curl&lt;/code&gt; 任何 HTTPS 站点都报证书错误，&lt;code&gt;apt update&lt;/code&gt; 连不上源，查了半天网络和证书，最后发现是时钟的锅。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;日志跨机器对不齐没法排障。&lt;/strong&gt; 一次请求经过负载均衡、应用服务器、数据库三台机器，出故障时要把三份日志按时间拼起来还原现场。如果三台机器各差几秒甚至几分钟，日志顺序全是错的，你会得出完全错误的结论。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;多机排障的前提，是所有机器的时钟先对齐。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;定时任务与令牌有效期。&lt;/strong&gt; cron 是按系统时钟触发的，时间错了，备份任务就可能在业务高峰跑起来。而各类令牌、签名、一次性验证码都带有效期窗口，签名的校验逻辑会拿「请求里的时间戳」和「服务器当前时间」比对，偏差超过窗口就直接拒绝——时间差五分钟，API 签名永远验不过，这种问题排查起来极其折磨人。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;数据库时间戳。&lt;/strong&gt; 用 &lt;code&gt;now()&lt;/code&gt; 之类函数写入的时间戳、按时间排序的记录、主从复制的位点，全都建立在时钟可信的基础上。时间一旦回拨或跳变，轻则数据顺序错乱，重则触发应用层各种诡异的边界条件。&lt;/p&gt;
&lt;p&gt;所以时间同步不是「锦上添花」，是和网络、磁盘同一级别的基础设施。下面先把两个最基础的概念分清，后面所有命令都建立在它们之上。&lt;/p&gt;
&lt;h2&gt;二、两个时间先分清：系统时间、硬件时钟与 UTC&lt;/h2&gt;
&lt;p&gt;一台机器里其实有两个时钟，混淆它们是很多时间问题的起点。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;时钟&lt;/th&gt;
&lt;th&gt;是什么&lt;/th&gt;
&lt;th&gt;断电后&lt;/th&gt;
&lt;th&gt;谁在用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;系统时间（System Clock）&lt;/td&gt;
&lt;td&gt;内核维护的软件时钟，开机时从硬件时钟读入，运行中靠晶振推进&lt;/td&gt;
&lt;td&gt;消失，靠重新读入&lt;/td&gt;
&lt;td&gt;所有进程、日志、文件时间戳&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;硬件时钟（RTC）&lt;/td&gt;
&lt;td&gt;主板上的实时时钟芯片，靠纽扣电池供电，关机也在走&lt;/td&gt;
&lt;td&gt;继续走&lt;/td&gt;
&lt;td&gt;开机时给系统时间提供初始值&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;系统时间是我们平时说的「服务器时间」，&lt;code&gt;date&lt;/code&gt; 命令看的就是它。硬件时钟平时没人管，但它走时精度很差，一天差几秒很常见；开机时系统时间以它为起点，如果这台机器长期不开 NTP 同步，偏差就是从这里一路积累的。&lt;/p&gt;
&lt;p&gt;第二个要分清的是&lt;strong&gt;时间的存储约定&lt;/strong&gt;：系统内部统一用 UTC（协调世界时）计数，所谓时区，只是显示时做的一次加减换算。硬件时钟里存的到底是 UTC 还是本地时间，不同系统约定不同：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Linux 默认认为硬件时钟存的是 UTC，开机读入后按时区换算显示；&lt;/li&gt;
&lt;li&gt;Windows 默认认为硬件时钟存的是本地时间。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;双系统机器的时间打架就是这么来的：Windows 把本地时间写进硬件时钟，Linux 开机按 UTC 读出来再加一次时区偏移，时间立刻错几个小时。纯 Linux 服务器没有这个困扰，但要记住一条：&lt;strong&gt;排查时间问题时，先确认偏差到底出在「时钟本身不准」还是「时区换算错了」&lt;/strong&gt;，这是两个完全不同的故障，后文排障还会回到这一点。&lt;/p&gt;
&lt;h2&gt;三、timedatectl 全套：先把状态看明白&lt;/h2&gt;
&lt;p&gt;Debian 上管理时间和时区的统一入口是 &lt;code&gt;timedatectl&lt;/code&gt;，它是 systemd 的一部分，不用额外安装。任何时间操作之前，先不带参数跑一次，看清当前状态：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;timedatectl
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出大致长这样，逐行读懂它，后面所有判断都有依据：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;               Local time: Sat 2026-11-15 10:24:31 CST
           Universal time: Sat 2026-11-15 02:24:31 UTC
                 RTC time: Sat 2026-11-15 02:24:31
                Time zone: Asia/Shanghai (CST, +0800)
System clock synchronized: yes
              NTP service: active
          RTC in local TZ: no
&lt;/code&gt;&lt;/pre&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;行&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;关注点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Local time&lt;/td&gt;
&lt;td&gt;按当前时区换算出的本地时间&lt;/td&gt;
&lt;td&gt;和你手表对一下，这是最终表现&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Universal time&lt;/td&gt;
&lt;td&gt;UTC 时间&lt;/td&gt;
&lt;td&gt;应与 Local time 相差正好一个时区偏移&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;RTC time&lt;/td&gt;
&lt;td&gt;硬件时钟当前值&lt;/td&gt;
&lt;td&gt;默认按 UTC 显示&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Time zone&lt;/td&gt;
&lt;td&gt;当前时区及偏移&lt;/td&gt;
&lt;td&gt;服务器上最常见的错就是这一行不对&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;System clock synchronized&lt;/td&gt;
&lt;td&gt;系统时钟是否已与 NTP 同步&lt;/td&gt;
&lt;td&gt;&lt;code&gt;no&lt;/code&gt; 说明对时根本没生效&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;NTP service&lt;/td&gt;
&lt;td&gt;NTP 同步服务是否在跑&lt;/td&gt;
&lt;td&gt;&lt;code&gt;active&lt;/code&gt; 才是正常状态&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;RTC in local TZ&lt;/td&gt;
&lt;td&gt;硬件时钟是否按本地时间存储&lt;/td&gt;
&lt;td&gt;Linux 服务器应为 &lt;code&gt;no&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;设置时区用 &lt;code&gt;set-timezone&lt;/code&gt;，先列出可选时区确认写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 列出所有时区（很长，可配合 grep 过滤）
timedatectl list-timezones | grep -i shanghai

# 设置时区
sudo timedatectl set-timezone Asia/Shanghai

# 再次确认
timedatectl
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改完立即生效，不用重启任何服务，正在运行的进程会在下次读取时间时拿到新时区。有一类老程序会缓存时区，保险起见关键服务可以重启一次。&lt;/p&gt;
&lt;p&gt;:::warning
时区改错是最隐蔽的时间故障：时钟本身分秒不差，但所有日志、报表、定时任务整体偏移八小时。改时区后务必用 &lt;code&gt;date&lt;/code&gt; 和另一台正常机器交叉核对一遍，不要改完就走。
:::&lt;/p&gt;
&lt;p&gt;还要记住，&lt;code&gt;timedatectl&lt;/code&gt; 也能开关 NTP 同步：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 打开/关闭 NTP 同步（控制的是底层同步服务是否启用）
sudo timedatectl set-ntp true
timedatectl set-ntp false
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;但它只是个开关，真正干活的是背后的同步服务。用哪个服务同步，就是下一节的选型问题。&lt;/p&gt;
&lt;h2&gt;四、同步方案对比：timesyncd、chrony 与 ntpd&lt;/h2&gt;
&lt;p&gt;Debian 上常见的 NTP 实现有三个，先把定位分清再选：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方案&lt;/th&gt;
&lt;th&gt;定位&lt;/th&gt;
&lt;th&gt;大偏差修正&lt;/th&gt;
&lt;th&gt;断网表现&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;systemd-timesyncd&lt;/td&gt;
&lt;td&gt;systemd 自带的轻量客户端&lt;/td&gt;
&lt;td&gt;慢，只能渐进调整&lt;/td&gt;
&lt;td&gt;断网期间不做任何处理，重连后慢慢追&lt;/td&gt;
&lt;td&gt;偏差要求不严的普通机器，开箱即用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;chrony&lt;/td&gt;
&lt;td&gt;现代全功能实现，现行主流推荐&lt;/td&gt;
&lt;td&gt;快，支持开机快速步进纠偏&lt;/td&gt;
&lt;td&gt;记录漂移率，断网也能按漂移模型继续修正&lt;/td&gt;
&lt;td&gt;绝大多数服务器，尤其是虚拟机、笔记本、网络不稳的环境&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ntpd（ntpsec / 经典 ntp）&lt;/td&gt;
&lt;td&gt;老牌全功能守护进程&lt;/td&gt;
&lt;td&gt;中等，超阈值会直接退出需人工介入&lt;/td&gt;
&lt;td&gt;持续运行，靠多个源投票&lt;/td&gt;
&lt;td&gt;存量系统、需要当 NTP 服务器对外提供对时的场景&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;systemd-timesyncd 胜在零配置：Debian 默认就带着，&lt;code&gt;timedatectl&lt;/code&gt; 里那行 &lt;code&gt;NTP service: active&lt;/code&gt; 在很多机器上指的就是它。但它只是个「够用」的客户端：同步频率低、修正偏差靠缓慢微调、断网期间完全躺平，对时钟精度有要求、或者机器经常休眠迁移的环境就不够看了。&lt;/p&gt;
&lt;p&gt;chrony 是现在各大发行版的默认推荐，它的设计就是针对现代环境的：虚拟机时钟漂移大、网络时断时续、机器频繁开关机。它的杀手锏有两个：一是能测出本机时钟的&lt;strong&gt;漂移率&lt;/strong&gt;（一天快几秒这种规律），断网时按这个模型继续校正；二是开机时发现大偏差可以直接步进对齐，不用慢慢磨。&lt;/p&gt;
&lt;p&gt;ntpd 是历史最久的实现，功能全、还能对外当时间服务器，但对现代单机场景来说偏重，且遇到超大偏差时守护进程会直接退出，在无人值守的服务器上反而是个坑。除非有明确的历史包袱或对外提供对时服务的需求，新机器没必要再选它。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;结论先行：新部署的 Debian 服务器，直接装 chrony，一步到位。&amp;lt;/span&amp;gt;下面就以 chrony 为主线走完实战。&lt;/p&gt;
&lt;h2&gt;五、chrony 实战：安装、配置与状态解读&lt;/h2&gt;
&lt;h3&gt;5.1 安装与启用&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;sudo apt update
sudo apt install -y chrony

# 启用并设为开机自启
sudo systemctl enable --now chrony

# 确认服务状态
systemctl status chrony
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意一个细节：chrony 和 systemd-timesyncd 不能同时跑。安装 chrony 的包时，包管理通常会处理好冲突，但装完最好确认一遍 timesyncd 已经停掉，避免两个服务抢着调时钟：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;systemctl status systemd-timesyncd
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;显示 inactive 或根本不存在，就是对的。&lt;/p&gt;
&lt;h3&gt;5.2 配置文件：时间源池怎么写&lt;/h3&gt;
&lt;p&gt;chrony 的配置文件在 &lt;code&gt;/etc/chrony/chrony.conf&lt;/code&gt;，核心就是指定向谁对时。Debian 默认给了一组 &lt;code&gt;pool&lt;/code&gt; 配置，&lt;code&gt;pool&lt;/code&gt; 的含义是「一个地址背后对应一组服务器，自动挑质量好的用」，比写死单个 &lt;code&gt;server&lt;/code&gt; 更稳：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 使用公共 NTP 池（Debian 默认即类似写法）
pool 2.debian.pool.ntp.org iburst

# 也可以换成国内可达性更好的公共时间源，按需选用其一即可
# pool ntp.aliyun.com iburst
# pool time.cloudflare.com iburst
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;每行末尾的 &lt;code&gt;iburst&lt;/code&gt; 是个关键选项：服务启动时先快速连发几个包，几秒内就把初始偏差测出来完成第一次同步，而不是慢慢等轮询周期。服务器场景建议保留。&lt;/p&gt;
&lt;p&gt;改完配置重启服务生效：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl restart chrony
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;5.3 chronyc tracking：偏差到底有多少&lt;/h3&gt;
&lt;p&gt;判断一台机器时间准不准，看这个命令就够了：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;chronyc tracking
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;典型输出：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Reference ID    : A29FC801 (162.159.200.1)
Stratum         : 3
Ref time (UTC)  : Sat Nov 15 02:24:20 2026
System time     : 0.000183204 seconds fast of NTP time
Last offset     : +0.000142857 seconds
RMS offset      : 0.000291030 seconds
Frequency       : 7.215 ppm slow
Residual freq   : +0.004 ppm
Skew            : 0.082 ppm
Root delay      : 0.021408730 seconds
Root dispersion : 0.004102285 seconds
Update interval : 64.3 seconds
Leap status     : Normal
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐行读关键几项：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;怎么看&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Reference ID&lt;/td&gt;
&lt;td&gt;当前选用的时间源&lt;/td&gt;
&lt;td&gt;后面的地址就是在跟谁对时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Stratum&lt;/td&gt;
&lt;td&gt;层级，离标准时钟的跳数&lt;/td&gt;
&lt;td&gt;数字越小越上游，普通客户端 2–4 都正常&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;System time&lt;/td&gt;
&lt;td&gt;系统时钟相对 NTP 时间的偏差&lt;/td&gt;
&lt;td&gt;最重要的一行，&lt;code&gt;fast&lt;/code&gt; 是快、&lt;code&gt;slow&lt;/code&gt; 是慢，正常同步后应在毫秒级&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Last offset / RMS offset&lt;/td&gt;
&lt;td&gt;上次测得偏差 / 偏差的均方根&lt;/td&gt;
&lt;td&gt;看趋势是否稳定收敛&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Frequency&lt;/td&gt;
&lt;td&gt;本机时钟的漂移率&lt;/td&gt;
&lt;td&gt;单位 ppm，比如 7 ppm 约等于一天差 0.6 秒，这是 chrony 学出来的本机晶振规律&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Leap status&lt;/td&gt;
&lt;td&gt;闰秒状态&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Normal&lt;/code&gt; 即正常&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;System time&lt;/code&gt; 这一行如果显示偏差在零点几毫秒，说明同步健康；如果显示差了几秒甚至几分钟，或者命令直接报错说未同步，就要往下查时间源了。&lt;/p&gt;
&lt;h3&gt;5.4 chronyc sources：时间源质量怎么样&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;chronyc sources -v
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出类似：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;MS Name/IP address         Stratum Poll Reach LastRx Last sample
===============================================================================
^- time.cloudflare.com         3   6   377    32   +182us[ +210us] +/-  11ms
^* ntp.aliyun.com              2   6   377    28   -96us[ -124us] +/-  24ms
^- 162.159.200.123             3   6   377    45   +301us[ +301us] +/-  15ms
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;每行开头的符号最重要：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;符号&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;^*&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;当前正在使用的同步源&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;^+&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;质量合格的候选源，参与偏差计算&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;^-&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;已连上但暂未被选用的源&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;^?&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;连不上或还没拿到有效数据&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;^x&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;被判定为错误时间的源（falseticker）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;Reach&lt;/code&gt; 一列是八进制表示的最近八次探测成功记录，&lt;code&gt;377&lt;/code&gt; 表示八次全成功；如果是 &lt;code&gt;0&lt;/code&gt; 或很小，说明这个源根本连不通，多半是网络或防火墙问题。想看更细的统计（每个源的偏差分布、抖动），用 &lt;code&gt;chronyc sourcestats&lt;/code&gt; 瞄一眼即可，日常运维记住 &lt;code&gt;tracking&lt;/code&gt; 和 &lt;code&gt;sources&lt;/code&gt; 两个命令已经覆盖绝大多数场景。&lt;/p&gt;
&lt;h2&gt;六、手动纠偏：小偏差慢调，大偏差步进&lt;/h2&gt;
&lt;p&gt;正常情况下 chrony 会自己把偏差磨平，不需要人工干预。但新装的机器、长期关机的机器、从快照恢复的虚拟机，初始偏差可能大到离谱，这时要分情况处理。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;偏差几秒以内&lt;/strong&gt;：什么都不用做。chrony 默认用「微调时钟频率」的方式渐进修正——把时钟临时调快或调慢一点点，让偏差在不知不觉中归零。整个过程时间单调前进，不会出现跳变，对上层应用完全无感。这也是生产环境的默认期望行为。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;偏差几分钟到几小时&lt;/strong&gt;：渐进修正要磨非常久，而且在磨平之前，这台机器的证书、日志全是错的。这时用 &lt;code&gt;makestep&lt;/code&gt; 让 chrony 立即步进对齐：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 立即把时钟步进到正确时间（一次性跳变）
sudo chronyc makestep

# 再看一眼偏差，应已回到毫秒级
chronyc tracking
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;配置文件里还可以写 &lt;code&gt;makestep 1.0 3&lt;/code&gt;，含义是「启动后的前 3 次更新中，如果偏差超过 1 秒就直接步进」，很多发行版默认配置里已经有这一行，专门用来解决开机初始大偏差。&lt;/p&gt;
&lt;p&gt;:::warning
步进纠偏意味着时钟会瞬间跳变，往回跳（时间回拨）尤其危险：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;时间回拨可能让依赖时间戳排序的程序出现乱序、让已生成的唯一 ID 冲突、让数据库和分布式系统出现难以复现的诡异错误。&amp;lt;/span&amp;gt;生产环境要做大步进纠偏，先停掉关键业务、选低峰期操作，不要在业务跑着的时候直接 &lt;code&gt;makestep&lt;/code&gt; 一把梭。
:::&lt;/p&gt;
&lt;p&gt;反过来说，如果发现某台生产机时间差了几个小时，也不要图省事慢慢等它自己磨——偏差存在期间证书和令牌类故障会持续发生。正确姿势是评估影响、挑窗口、停服务、步进纠偏、验证、再启服务，一次处理干净。&lt;/p&gt;
&lt;h2&gt;七、时区纪律：服务器到底该用哪个时区&lt;/h2&gt;
&lt;p&gt;时区选择上有两个流派：服务器统一 UTC，或者用所在地本地时区。没有绝对对错，但要有纪律，不能一台一个样。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方案&lt;/th&gt;
&lt;th&gt;好处&lt;/th&gt;
&lt;th&gt;代价&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;全部统一 UTC&lt;/td&gt;
&lt;td&gt;跨机器、跨地区比对日志零换算；没有夏令时切换的坑；和云厂商、容器生态的默认一致&lt;/td&gt;
&lt;td&gt;人看日志时要心算时差；本地业务的「每天零点」类需求要在应用层处理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;用本地时区（如 Asia/Shanghai）&lt;/td&gt;
&lt;td&gt;日志时间与人的直觉一致；cron 的「凌晨三点」就是本地凌晨三点&lt;/td&gt;
&lt;td&gt;机器一多、地域一杂，对照时间全靠手动换算；涉及夏令时的地区每年有两次时间跳变&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;本篇的主张是：&lt;strong&gt;机器数量多、或者有跨机排障需求，就统一 UTC 存储与运行，展示层再按用户所在地转换&lt;/strong&gt;；只有一两台机器、且只服务本地业务，用本地时区图省事也完全可以。关键不在选哪个，在于&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;全队选同一个，且写进装机规范&amp;lt;/span&amp;gt;，最怕的是十台机器三种时区，排障时先花二十分钟对表。&lt;/p&gt;
&lt;p&gt;还有一个连带关系必须知道：&lt;strong&gt;cron 是按系统时区跑的&lt;/strong&gt;。你把时区从 Asia/Shanghai 改成 UTC，原来写「凌晨 3 点执行」的任务就会变成北京时间上午 11 点执行，备份跑到业务高峰上。改时区之前，先盘一遍机器上的定时任务会受什么影响。cron 与 systemd timer 的完整写法和这类坑，见定时任务篇：/posts/linux-cron-timers/ 。&lt;/p&gt;
&lt;p&gt;顺带一提，改时区不影响已经写下的日志文件里的时间戳文本，老日志该是什么时区还是什么时区，对照新旧日志时记得这个断点在哪一刻。&lt;/p&gt;
&lt;h2&gt;八、容器与虚拟机的时间：一句带过&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;容器共享宿主机的系统时钟&lt;/strong&gt;，容器里改不了时间，也不需要单独对时——宿主机准，容器就准。容器内能改的只有时区显示（通过 &lt;code&gt;TZ&lt;/code&gt; 环境变量或挂载 &lt;code&gt;/etc/localtime&lt;/code&gt;），发现容器日志时间差八小时，先查时区配置，别去容器里找 NTP 服务。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;虚拟机的时间漂移比物理机严重得多&lt;/strong&gt;，尤其是快照恢复、热迁移、长时间暂停之后，时钟可能瞬间差出几分钟到几小时。这正是 chrony 适合虚拟环境的原因：它对大偏差和漂移的建模处理都比 timesyncd 强。虚拟机里不要同时开宿主平台的时间同步工具（比如虚拟机增强工具自带的对时）和 chrony，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;两个对时机制同时调一个时钟会互相打架&amp;lt;/span&amp;gt;，选一个，关掉另一个。&lt;/p&gt;
&lt;h2&gt;九、排障：时间不对时按这个顺序查&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;症状一：同步一直不生效。&lt;/strong&gt; &lt;code&gt;timedatectl&lt;/code&gt; 显示 &lt;code&gt;System clock synchronized: no&lt;/code&gt;，或 &lt;code&gt;chronyc tracking&lt;/code&gt; 里偏差居高不下。按顺序查：服务在不在跑（&lt;code&gt;systemctl status chrony&lt;/code&gt;）；源连不连得通（&lt;code&gt;chronyc sources&lt;/code&gt;，&lt;code&gt;Reach&lt;/code&gt; 为 0 就是网络不通，重点查出方向 UDP 123 端口是否被防火墙拦）；是不是虚拟化平台的对时工具在抢时钟（见上一节，关掉一个）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;症状二：偏差越走越大。&lt;/strong&gt; 同步明明在跑，偏差却缓慢增长。这通常是时钟源质量差或本机晶振漂移过于离谱：看 &lt;code&gt;chronyc tracking&lt;/code&gt; 的 &lt;code&gt;Frequency&lt;/code&gt;，数值异常大说明硬件时钟底子太差；看 &lt;code&gt;sources&lt;/code&gt; 里选中的源是不是延迟高、抖动大的远端源，换一组更近的源池往往立刻好转。虚拟机还要怀疑宿主机本身负载过高导致客户机时钟推进不均匀，这不是客户机里能根治的问题，要反馈到虚拟化层。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;症状三：日志时间对不上，但 &lt;code&gt;date&lt;/code&gt; 看着是对的。&lt;/strong&gt; 这是两类故障的混合体，必须分开查：先查&lt;strong&gt;同步&lt;/strong&gt;——和另一台可信机器同时跑 &lt;code&gt;date -u&lt;/code&gt; 比对 UTC 时间，排除时钟本身不准；再查&lt;strong&gt;时区&lt;/strong&gt;——逐台 &lt;code&gt;timedatectl&lt;/code&gt; 看 &lt;code&gt;Time zone&lt;/code&gt; 是否一致，很多时候是某台机器时区被单独改过，或者某个应用自己带了时区配置覆盖了系统设置。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把「时刻不对」和「显示不对」混为一谈，是时间排障最常见的弯路。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;症状四：改了时区，定时任务全乱了。&lt;/strong&gt; 见第七节，cron 按系统时区解释执行时间，改时区等于整体平移所有任务。解法是把任务时间按新时区重新换算写回，或者时区别动、在应用层处理显示。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇的要点收束成几条：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;时间是基础设施：证书、日志、令牌、数据库都建立在时钟可信之上，别等翻车了才想起它。&lt;/li&gt;
&lt;li&gt;先分清概念：系统时间与硬件时钟是两回事；时钟不准和时区错位是两类故障，排查时分开验证。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;timedatectl&lt;/code&gt; 是总入口：看状态逐行读，设时区一条命令，但改时区前先盘点 cron 的连带影响。&lt;/li&gt;
&lt;li&gt;选型不用纠结：新机器直接上 chrony，timesyncd 只适合要求不高的场景，老 ntpd 没有历史包袱就不必选。&lt;/li&gt;
&lt;li&gt;看状态记两个命令：&lt;code&gt;chronyc tracking&lt;/code&gt; 看偏差，&lt;code&gt;chronyc sources&lt;/code&gt; 看源质量，&lt;code&gt;Reach&lt;/code&gt; 为 0 就是连不通。&lt;/li&gt;
&lt;li&gt;纠偏分大小：小偏差让 chrony 慢慢磨，大偏差用 &lt;code&gt;makestep&lt;/code&gt; 步进，但生产环境步进前先停关键业务，时间回拨的乱序风险真实存在。&lt;/li&gt;
&lt;li&gt;时区要有纪律：全队统一一个标准写进规范，容器查时区配置、虚拟机只留一个对时机制。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;下一篇进入内核参数与系统限制的调优：sysctl 常用项、文件句柄与 ulimit、Swap 配置，把系统的这些「出厂设置」按服务器的实际用途调一遍。&lt;/p&gt;
</content:encoded></item><item><title>Linux 用户与权限管理</title><link>https://www.anexns.cloudns.org/posts/linux-user-permissions/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/linux-user-permissions/</guid><description>账号、用户组、sudo 与文件权限一次讲透：rwx 权限位与数字表示、属主属组、特殊权限位与 ACL，以及权限明明对了却还是进不去目录的经典排查。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h1&gt;Linux 用户与权限管理&lt;/h1&gt;
&lt;p&gt;&lt;code&gt;Permission denied&lt;/code&gt; 大概是每个 Linux 用户都撞见过的报错。它出现的时候，问题几乎从来不是&quot;系统坏了&quot;，而是权限模型在按规则办事——只是规则没搞清之前，它看起来像在故意为难你。&lt;/p&gt;
&lt;p&gt;本文的主线是把这套模型从头捋一遍：先讲清&quot;谁&quot;——账号和用户组是怎么存的、怎么管的；再讲清&quot;能干什么&quot;——普通用户怎么通过 sudo 借到管理员权限，一个文件又是怎么用 rwx 三段权限决定谁能读、谁能写、谁能执行的；最后补上特殊权限位与 ACL 这两个进阶工具，并专门留一节排查&quot;权限明明配对了，却还是进不去&quot;的经典场景。看完这一篇，&lt;code&gt;ls -l&lt;/code&gt; 输出的每一位都应该能读懂，遇到权限报错也能自己定位到是哪一段出了问题。&lt;/p&gt;
&lt;h2&gt;一、账号体系：/etc/passwd 与 /etc/shadow&lt;/h2&gt;
&lt;p&gt;Linux 的账号信息不在数据库里，就是两个文本文件。搞懂它们，后面所有命令都只是对这两个文件的增删改查。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;/etc/passwd&lt;/code&gt; 每一行是一个账号，用冒号分成 7 段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;anex:x:1000:1000:Anex,,,:/home/anex:/bin/bash
&lt;/code&gt;&lt;/pre&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;示例&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;登录名&lt;/td&gt;
&lt;td&gt;anex&lt;/td&gt;
&lt;td&gt;登录时输入的用户名&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;密码占位&lt;/td&gt;
&lt;td&gt;x&lt;/td&gt;
&lt;td&gt;老年代这里放密码哈希，现在统一写 x，真正的哈希在 shadow 里&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;UID&lt;/td&gt;
&lt;td&gt;1000&lt;/td&gt;
&lt;td&gt;用户 ID，系统认的是这个数字，不是名字&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GID&lt;/td&gt;
&lt;td&gt;1000&lt;/td&gt;
&lt;td&gt;主用户组的 ID&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;注释&lt;/td&gt;
&lt;td&gt;Anex,,,&lt;/td&gt;
&lt;td&gt;全名、电话等备注信息，可以为空&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;家目录&lt;/td&gt;
&lt;td&gt;/home/anex&lt;/td&gt;
&lt;td&gt;登录后默认进入的目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;登录 Shell&lt;/td&gt;
&lt;td&gt;/bin/bash&lt;/td&gt;
&lt;td&gt;登录后启动的 Shell，写 &lt;code&gt;/usr/sbin/nologin&lt;/code&gt; 表示禁止登录&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;真正的密码哈希存在 &lt;code&gt;/etc/shadow&lt;/code&gt; 里，这个文件只有 root 能读。它每行 9 段，日常需要认识前两段和过期相关的几段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;anex:$y$j9T$....:20000:0:99999:7:::
&lt;/code&gt;&lt;/pre&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;登录名&lt;/td&gt;
&lt;td&gt;与 passwd 对应&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;密码哈希&lt;/td&gt;
&lt;td&gt;以 &lt;code&gt;$&lt;/code&gt; 开头的是哈希；&lt;code&gt;!&lt;/code&gt; 或 &lt;code&gt;*&lt;/code&gt; 开头表示账号被锁定/无密码登录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;上次改密&lt;/td&gt;
&lt;td&gt;距 1970-01-01 的天数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;最小间隔&lt;/td&gt;
&lt;td&gt;两次改密之间至少隔多少天，0 为不限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;最大有效期&lt;/td&gt;
&lt;td&gt;密码多少天后过期，99999 约等于永不过期&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;警告天数&lt;/td&gt;
&lt;td&gt;过期前多少天开始提醒&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;宽限天数&lt;/td&gt;
&lt;td&gt;过期后还能登录几天，空为不限制&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;账号过期&lt;/td&gt;
&lt;td&gt;账号本身的到期天数，空为永不过期&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;保留&lt;/td&gt;
&lt;td&gt;暂未使用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;UID 的划分值得记住。Debian 的约定是：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;UID 区间&lt;/th&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;0&lt;/td&gt;
&lt;td&gt;永远是 root，不论登录名叫什么&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1–99&lt;/td&gt;
&lt;td&gt;系统预留的静态系统用户&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;100–999&lt;/td&gt;
&lt;td&gt;软件包安装时动态创建的系统用户（如 www-data、mysql）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1000 起&lt;/td&gt;
&lt;td&gt;普通用户，第一个新建用户就是 1000&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;这里有个关键认知：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;内核判断权限只认 UID 数字，用户名只是给人看的别名&amp;lt;/span&amp;gt;。所以判断&quot;谁是管理员&quot;看的不是名字像不像 root，而是 UID 是不是 0。&lt;/p&gt;
&lt;p&gt;root（UID 0）不受普通权限检查的约束，几乎能读写任何文件。正因为如此，日常操作不应该直接用 root 登录干活，而应该用普通账号 + sudo 临时提权——sudo 的用法在第四节细讲。系统用户（比如 www-data）则是给服务进程用的，它们的 Shell 通常是 &lt;code&gt;nologin&lt;/code&gt;，不允许交互登录，这本身就是一层安全设计：就算服务被攻破，攻击者也拿不到一个能登录的 Shell。&lt;/p&gt;
&lt;h2&gt;二、用户管理全套命令&lt;/h2&gt;
&lt;p&gt;管理用户的命令就四个：&lt;code&gt;useradd&lt;/code&gt;、&lt;code&gt;usermod&lt;/code&gt;、&lt;code&gt;userdel&lt;/code&gt;、&lt;code&gt;passwd&lt;/code&gt;，外加查身份的 &lt;code&gt;id&lt;/code&gt; 和 &lt;code&gt;groups&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;2.1 新建用户：useradd&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 新建用户 anex：-m 创建家目录，-s 指定 Shell，-G 附加到 sudo 组
sudo useradd -m -s /bin/bash -G sudo anex

# 给新用户设置密码（交互式输入两遍）
sudo passwd anex
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Debian 上 &lt;code&gt;useradd&lt;/code&gt; 有两个容易踩的点：第一，不加 &lt;code&gt;-m&lt;/code&gt; 不会创建家目录，用户登录后会飘在根目录；第二，&lt;code&gt;useradd&lt;/code&gt; 不带参数时默认 Shell 取决于 &lt;code&gt;/etc/default/useradd&lt;/code&gt; 的配置，可能不是 bash。所以建人用的账号时，&lt;code&gt;-m -s /bin/bash&lt;/code&gt; 这组参数建议养成肌肉记忆。&lt;/p&gt;
&lt;p&gt;Debian 还提供了一个交互式的 &lt;code&gt;adduser&lt;/code&gt;，一步步问密码和用户信息，适合偶尔手动建号：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo adduser anex
sudo adduser anex sudo   # 把 anex 加入 sudo 组
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个工具建的账号完全等价，&lt;code&gt;adduser&lt;/code&gt; 本质上是把 &lt;code&gt;useradd&lt;/code&gt; 的常用选项包装成了问答式流程。脚本里批量建号用 &lt;code&gt;useradd&lt;/code&gt;，手动建号用哪个顺手都行。&lt;/p&gt;
&lt;h3&gt;2.2 修改用户：usermod&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 改登录名
sudo usermod -l newname oldname

# 改家目录并把文件一起搬过去（-m 配合 -d）
sudo usermod -d /data/anex -m anex

# 换登录 Shell
sudo usermod -s /bin/zsh anex

# 锁定 / 解锁账号（禁止/恢复密码登录）
sudo usermod -L anex
sudo usermod -U anex
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;2.3 删除用户：userdel&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 只删账号，保留家目录（默认行为）
sudo userdel anex

# 连家目录和邮件一起删
sudo userdel -r anex
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;删人之前先想清楚：这个用户的文件散落在系统各处，只删账号的话，这些文件的属主会变成一个没有名字的 UID 数字。离职交接场景下，更稳妥的做法是先用 &lt;code&gt;usermod -L&lt;/code&gt; 锁定账号、观察一段时间，确认没有服务在用这个身份跑，再考虑删除。&lt;/p&gt;
&lt;h3&gt;2.4 密码管理：passwd&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;passwd              # 改自己的密码
sudo passwd anex    # root 给别人改密码，不需要知道旧密码
sudo passwd -l anex # 锁定密码（效果同 usermod -L）
sudo passwd -u anex # 解锁
sudo passwd -S anex # 查看密码状态：L 锁定 / P 有密码 / NP 无密码
sudo chage -l anex  # 查看密码的过期策略详情
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;2.5 查身份：id 与 groups&lt;/h3&gt;
&lt;p&gt;排查权限问题时，第一件事永远是确认&quot;我现在是谁、属于哪些组&quot;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;$ id anex
uid=1000(anex) gid=1000(anex) groups=1000(anex),27(sudo),1001(dev)

$ groups anex
anex : anex sudo dev
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;id&lt;/code&gt; 的输出把后面所有权限判断的输入都给齐了：UID、主组 GID、全部附加组。记住一点：&lt;strong&gt;修改组员关系后，已经登录的会话不会自动生效&lt;/strong&gt;，必须重新登录（或用 &lt;code&gt;newgrp&lt;/code&gt; 切换主组），&lt;code&gt;id&lt;/code&gt; 的输出才会更新。很多&quot;我明明把他加进组了却还是没权限&quot;的抱怨，根源就在这里。&lt;/p&gt;
&lt;h2&gt;三、用户组：主组与附加组&lt;/h2&gt;
&lt;p&gt;每个用户有一个&lt;strong&gt;主组&lt;/strong&gt;（primary group，记在 &lt;code&gt;/etc/passwd&lt;/code&gt; 的 GID 字段里）和若干个&lt;strong&gt;附加组&lt;/strong&gt;（supplementary groups，记在 &lt;code&gt;/etc/group&lt;/code&gt; 里）。用户新建文件时，文件属组默认是主组；判断文件权限时，用户所属的&lt;strong&gt;所有&lt;/strong&gt;组（主组 + 附加组）都会参与匹配。&lt;/p&gt;
&lt;p&gt;组的日常操作：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo groupadd dev          # 新建组 dev
sudo groupdel dev          # 删除组（组内还有人以它为主组时删不掉）
getent group dev           # 查看组与成员名单
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把用户加入附加组只有一条命令，但它藏着本系列最著名的坑之一：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 正确：-a 表示 append，追加
sudo usermod -aG dev anex
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;code&gt;usermod -G&lt;/code&gt; 缺了 &lt;code&gt;-a&lt;/code&gt; 时是&quot;替换&quot;而不是&quot;追加&quot;：用户原有的全部附加组会被清掉，只剩下这次写的那一个。&amp;lt;/span&amp;gt;不少人就是这样把同事从 sudo 组里&quot;顺手&quot;踢出去的，还浑然不觉，直到对方下次用 sudo 时才爆雷。记死：改附加组，&lt;code&gt;-aG&lt;/code&gt; 永远连在一起写。&lt;/p&gt;
&lt;p&gt;组最典型的协作用法是共享目录：建一个组，把协作者都加进去，再把目录属组设为这个组并配上组权限（第五、八节细讲），就实现了&quot;组内人人可读写、组外免进&quot;的共享空间，比逐个给人开 ACL 简单得多。&lt;/p&gt;
&lt;h2&gt;四、sudo：普通用户怎么借 root 权限&lt;/h2&gt;
&lt;p&gt;sudo 的作用是让普通用户&lt;strong&gt;以 root 身份执行单条命令&lt;/strong&gt;，而不是变成 root。它比直接发 root 密码强在三点：每个人用自己的密码、每条命令都有日志、出问题能单独收回某个人的权限。&lt;/p&gt;
&lt;h3&gt;4.1 给用户 sudo 权限的正规做法&lt;/h3&gt;
&lt;p&gt;Debian 上最省事也最正规的做法，是把用户加入 &lt;code&gt;sudo&lt;/code&gt; 组：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo usermod -aG sudo anex
# 重新登录后生效，验证：
sudo whoami   # 输出 root 即成功
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果需要更细的授权（比如只允许某人重启某个服务），就单独写一条 sudoers 规则。用 root 执行 &lt;code&gt;visudo&lt;/code&gt;，或者在 &lt;code&gt;/etc/sudoers.d/&lt;/code&gt; 下新建一个文件再用 &lt;code&gt;visudo -f&lt;/code&gt; 编辑它：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo visudo -f /etc/sudoers.d/anex-ops
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;# 允许 anex 免密重启和查看 nginx，其余命令仍需密码
anex ALL=(root) NOPASSWD: /usr/bin/systemctl restart nginx, /usr/bin/systemctl status nginx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;sudoers 一行的结构是：&lt;code&gt;用户 主机=(以谁的身份) 命令列表&lt;/code&gt;。&lt;code&gt;ALL=(root)&lt;/code&gt; 表示在任意主机上以 root 身份执行。&lt;/p&gt;
&lt;p&gt;两条纪律必须强调：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;编辑 sudoers 永远用 visudo，不要直接用文本编辑器改&amp;lt;/span&amp;gt;。visudo 会在保存时做语法检查，写错了会拦下来；直接改一旦写错语法，sudo 会整体拒绝工作，所有人都提不了权。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;NOPASSWD&lt;/code&gt; 要克制。它意味着拿到这个账号的人（或冒充这个账号的进程）可以直接无密码执行这些命令。给只读查询、状态查看类命令开 NOPASSWD 问题不大；给编辑器、Shell、&lt;code&gt;systemctl&lt;/code&gt; 这类能&quot;逃逸&quot;出更多权限的命令开 NOPASSWD，约等于把 root 直接送人。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;4.2 sudo 的日志在哪&lt;/h3&gt;
&lt;p&gt;每条 sudo 命令都会被记录。Debian 上看两个地方：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 认证日志：谁在什么时候执行了什么命令
sudo grep sudo /var/log/auth.log | tail

# systemd 日志
sudo journalctl _COMM=sudo --since today
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;日志里会留下执行人、所在终端、当前目录和完整命令。这正是 sudo 相对&quot;大家共用 root 密码&quot;的核心优势：出了事能追溯到人。&lt;/p&gt;
&lt;h2&gt;五、文件权限模型：rwx 三段权限&lt;/h2&gt;
&lt;h3&gt;5.1 读懂 ls -l&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;$ ls -l /home/anex
drwxr-xr--  2 anex dev  4096 Nov 15 10:00 docs
-rw-r-----  1 anex dev  1280 Nov 15 09:30 notes.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;权限部分一共 10 个字符，拆开看：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;d rwx r-x r--
↑ ↑   ↑   ↑
│ │   │   └─ 其他人（others）的权限
│ │   └───── 属组（group）的权限
│ └───────── 属主（user/owner）的权限
└─────────── 文件类型：- 普通文件、d 目录、l 链接
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;系统判断某个用户能不能操作这个文件时，顺序是固定的：先看他是不是属主，是就用第一段；不是再看他是否在属组里，是就用第二段；都不沾边就用第三段。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;三段只取命中的那一段，不叠加&amp;lt;/span&amp;gt;——这意味着完全可能出现&quot;属主权限比其他人还低&quot;的配置，比如文件是 &lt;code&gt;---r--r--&lt;/code&gt; 时，属主自己反而读不了，别人却能读。这不是 bug，是规则。&lt;/p&gt;
&lt;h3&gt;5.2 rwx 对文件和对目录，含义完全不同&lt;/h3&gt;
&lt;p&gt;这是初学者最容易混淆的一点：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;权限&lt;/th&gt;
&lt;th&gt;对普通文件&lt;/th&gt;
&lt;th&gt;对目录&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;r（读）&lt;/td&gt;
&lt;td&gt;能看文件内容&lt;/td&gt;
&lt;td&gt;能列出目录里有哪些文件名（&lt;code&gt;ls&lt;/code&gt;）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;w（写）&lt;/td&gt;
&lt;td&gt;能修改文件内容&lt;/td&gt;
&lt;td&gt;能在目录里新建、删除、重命名文件（哪怕文件本身不属于你）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;x（执行）&lt;/td&gt;
&lt;td&gt;能把文件当程序运行&lt;/td&gt;
&lt;td&gt;能&quot;进入&quot;目录（&lt;code&gt;cd&lt;/code&gt;），并访问其中已知文件名的文件&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;特别注意目录的 w 和 x：能不能删掉目录里的一个文件，看的是&lt;strong&gt;对目录有没有 w&lt;/strong&gt;，与文件本身的权限无关。而目录没有 x 时，哪怕你知道里面有个文件叫什么名字、那个文件本身是 777，也照样打不开——这一条是第九节排障的核心。&lt;/p&gt;
&lt;h3&gt;5.3 数字表示法：755 / 644 / 600 的来历&lt;/h3&gt;
&lt;p&gt;每段权限用一个八进制数字表示：r = 4、w = 2、x = 1，相加即得。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;数字&lt;/th&gt;
&lt;th&gt;权限&lt;/th&gt;
&lt;th&gt;典型用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;rwx&lt;/td&gt;
&lt;td&gt;私人脚本、目录的标准位&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;rw-&lt;/td&gt;
&lt;td&gt;普通文件的标准位&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;r-x&lt;/td&gt;
&lt;td&gt;对外开放但不可改的目录/程序&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;r--&lt;/td&gt;
&lt;td&gt;只读文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0&lt;/td&gt;
&lt;td&gt;---&lt;/td&gt;
&lt;td&gt;完全禁止&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;三个数字连起来就是常见的组合：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;组合&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;常见对象&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;755&lt;/td&gt;
&lt;td&gt;属主全权，组和其他人只读+执行&lt;/td&gt;
&lt;td&gt;目录、可执行程序&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;644&lt;/td&gt;
&lt;td&gt;属主可读写，其他人只读&lt;/td&gt;
&lt;td&gt;普通文件、网页文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;600&lt;/td&gt;
&lt;td&gt;只有属主能读写&lt;/td&gt;
&lt;td&gt;私钥、含密码的配置文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;700&lt;/td&gt;
&lt;td&gt;只有属主能进&lt;/td&gt;
&lt;td&gt;私人目录（如 &lt;code&gt;~/.ssh&lt;/code&gt; 必须是 700 或更严）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;640&lt;/td&gt;
&lt;td&gt;属主读写、组只读&lt;/td&gt;
&lt;td&gt;服务与运维组共享的配置文件&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;5.4 chmod 两种写法&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 数字法：一步到位，适合心里有明确目标权限时
chmod 644 notes.txt
chmod 600 ~/.ssh/id_ed25519

# 符号法：在现有权限上增减，适合微调
chmod u+x deploy.sh        # 给属主加执行位
chmod g-w shared.txt       # 去掉组的写权限
chmod o= public.txt        # 其他人的权限清空
chmod a+r readme.md        # 所有人加读权限（a = all）
chmod -R u=rwX,go=rX /srv/site  # 递归；大写 X 只给目录和已可执行文件加 x
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;符号法里的 &lt;code&gt;X&lt;/code&gt;（大写）值得单独记住：它表示&quot;只对目录、以及已经有执行位的文件设置 x&quot;。批量处理一整棵目录树时用它，可以避免把普通文本文件也全标成可执行。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;code&gt;chmod -R 777&lt;/code&gt; 是新手最爱用、危害最大的&quot;万能药&quot;。它把私钥、配置文件、脚本一股脑对全系统任何用户开放读写执行，不仅是安全事故，还会直接把服务弄坏：比如 SSH 会因为私钥权限过宽而拒绝使用它、sshd 会因为配置权限问题拒绝启动。遇到 Permission denied，先按第九节的方法定位是哪一段权限缺失，再精准补那一段。
:::&lt;/p&gt;
&lt;h2&gt;六、属主与属组：chown / chgrp&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;sudo chown anex file.txt          # 只改属主
sudo chown anex:dev file.txt      # 同时改属主和属组
sudo chown :dev file.txt          # 只改属组（chgrp dev file.txt 等价）
sudo chown -R anex:dev /srv/app   # 递归改一整棵目录树
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;最常见的场景是：用 root 或 sudo 往某个目录里放了文件，结果属主是 root，服务进程（以普通用户身份跑）读不了。把属主改成服务用户即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo chown -R www-data:www-data /var/www/html
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
递归 chown 前先确认路径写对了。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;对 &lt;code&gt;/&lt;/code&gt;、&lt;code&gt;/etc&lt;/code&gt;、&lt;code&gt;/usr&lt;/code&gt; 这类系统路径执行递归 chown/chmod，会瞬间破坏大量系统文件的归属关系&amp;lt;/span&amp;gt;，轻则服务起不来，重则只能重装。真需要递归处理时，先用 &lt;code&gt;ls&lt;/code&gt; 核对目标目录、再把命令敲全，养成&quot;先看后改&quot;的习惯。
:::&lt;/p&gt;
&lt;p&gt;顺带一提：普通用户只能把自己拥有的文件的属组改成自己所属的组，改属主是 root 的专属操作——&lt;code&gt;chown&lt;/code&gt; 基本总是要配 sudo 用的。&lt;/p&gt;
&lt;h2&gt;七、umask：新建文件的默认权限从哪来&lt;/h2&gt;
&lt;p&gt;为什么新建文件总是 644、新建目录总是 755？这是 umask（权限掩码）在起作用。&lt;/p&gt;
&lt;p&gt;系统给新建对象的&quot;满格&quot;权限是：文件 666、目录 777。umask 表示&quot;要从满格里扣掉的位&quot;，最终权限 = 满格 − umask（按位扣除）。Debian 默认 umask 是 &lt;code&gt;0022&lt;/code&gt;：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对象&lt;/th&gt;
&lt;th&gt;满格&lt;/th&gt;
&lt;th&gt;扣掉 022 后&lt;/th&gt;
&lt;th&gt;结果&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;文件&lt;/td&gt;
&lt;td&gt;666&lt;/td&gt;
&lt;td&gt;去掉组和其他人的 w&lt;/td&gt;
&lt;td&gt;644&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;目录&lt;/td&gt;
&lt;td&gt;777&lt;/td&gt;
&lt;td&gt;去掉组和其他人的 w&lt;/td&gt;
&lt;td&gt;755&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;pre&gt;&lt;code&gt;umask          # 查看当前掩码
umask 027      # 临时收紧：新建文件 640、目录 750（只对当前 Shell 会话生效）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意文件满格是 666 而不是 777：系统默认不给任何新建文件执行位，这是刻意的安全设计——执行权限必须由人显式地 &lt;code&gt;chmod +x&lt;/code&gt; 给出，不该自动出现。umask 的持久化配置在 &lt;code&gt;~/.profile&lt;/code&gt; 或 &lt;code&gt;/etc/login.defs&lt;/code&gt;（&lt;code&gt;UMask&lt;/code&gt; 项），服务器场景下把默认 umask 收紧到 027 是很常见的加固动作。&lt;/p&gt;
&lt;h2&gt;八、特殊权限位：setuid、setgid、粘滞位&lt;/h2&gt;
&lt;p&gt;在三段 rwx 之外，还有三个特殊位，它们出现在权限串里时，会把对应段的 x 替换成 s 或 t：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;特殊位&lt;/th&gt;
&lt;th&gt;数字&lt;/th&gt;
&lt;th&gt;显示&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;典型例子&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;setuid&lt;/td&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;属主段 x 变 s&lt;/td&gt;
&lt;td&gt;执行该程序时，临时以&lt;strong&gt;文件属主&lt;/strong&gt;的身份运行&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/usr/bin/passwd&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;setgid&lt;/td&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;属组段 x 变 s&lt;/td&gt;
&lt;td&gt;对程序：以属组身份运行；对目录：新建文件自动继承目录的属组&lt;/td&gt;
&lt;td&gt;共享目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;粘滞位&lt;/td&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;其他人段 x 变 t&lt;/td&gt;
&lt;td&gt;目录内文件只有属主能删&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/tmp&lt;/code&gt;（1777）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;数字表示时在原来的三位前面加一位：&lt;code&gt;4755&lt;/code&gt;、&lt;code&gt;2775&lt;/code&gt;、&lt;code&gt;1777&lt;/code&gt;。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# /tmp 为什么人人能写、却删不掉别人的文件？因为粘滞位：
$ ls -ld /tmp
drwxrwxrwt  12 root root  4096 Nov 15 10:00 /tmp

# 共享目录的正确打开方式：属组 dev + setgid，新文件自动归 dev 组
sudo chgrp dev /srv/shared
sudo chmod 2775 /srv/shared
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;setgid 用在共享目录上非常关键：没有它，谁新建的文件就归谁的主组，协作者经常打不开；有了它，文件属组统一继承为共享组，配合 2775 的组权限，协作才真正顺畅。&lt;/p&gt;
&lt;p&gt;setuid 则要慎用：给一个普通程序加 setuid root，等于让任何人执行它时都握有 root 权限，程序本身但凡有一点漏洞就是提权通道。日常运维中你几乎不需要手动设置 setuid，系统自带的那几个（passwd、sudo、mount 等）都是经过审计的。&lt;/p&gt;
&lt;h2&gt;九、ACL：给某一个人开例外&lt;/h2&gt;
&lt;p&gt;三段权限有个表达不了的需求：&quot;这个文件只想额外让小王一个人能读，其他人都不行。&quot;为小王单建一个组显得小题大做，这正是 ACL（访问控制列表）的用武之地。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 查看 ACL（普通权限之外的条目）
getfacl report.txt

# 给用户 wang 单独加读权限
setfacl -m u:wang:r-- report.txt

# 给组 ops 单独加读写
setfacl -m g:ops:rw- report.txt

# 删掉某条 ACL
setfacl -x u:wang report.txt

# 清除全部扩展 ACL（回到只有三段权限）
setfacl -b report.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;带 ACL 的文件，&lt;code&gt;ls -l&lt;/code&gt; 权限串末尾会多一个 &lt;code&gt;+&lt;/code&gt; 号：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-rw-r--r--+  1 anex dev  2048 Nov 15 10:00 report.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;还有两个细节要知道：其一，ACL 里有个叫 mask（掩码）的条目，它限定命名用户和属组条目的&lt;strong&gt;有效&lt;/strong&gt;权限上限，&lt;code&gt;getfacl&lt;/code&gt; 输出里会以 &lt;code&gt;effective:&lt;/code&gt; 标注实际生效的权限——用 &lt;code&gt;chmod&lt;/code&gt; 改属组段时，改的其实就是 mask，这一点经常让初学者困惑。其二，给目录设置默认 ACL（&lt;code&gt;setfacl -d -m u:wang:r-- dir&lt;/code&gt;）后，目录内新建的文件会自动继承这条 ACL，适合长期共享的目录。ACL 是&quot;例外机制&quot;，能用组解决的协作需求优先用组，ACL 只用来处理零星的个案，否则时间一长没人说得清一个文件到底谁能访问。&lt;/p&gt;
&lt;h2&gt;十、排障：三个经典场景&lt;/h2&gt;
&lt;h3&gt;场景一：文件权限是对的，还是 Permission denied&lt;/h3&gt;
&lt;p&gt;这是最经典的一类：文件本身明明给了读权限，程序却报打不开。原因在第五节埋过伏笔——&lt;strong&gt;访问一个文件，需要对它的每一级父目录都有 x 权限&lt;/strong&gt;。任何一级缺了 x，就像走廊里有一道门锁着，房间本身开着门也没用。&lt;/p&gt;
&lt;p&gt;逐级排查有现成的工具 &lt;code&gt;namei&lt;/code&gt;，它会把路径每一层的权限列出来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;$ namei -l /srv/app/data/config.yaml
f: /srv/app/data/config.yaml
drwxr-xr-x root root /
drwxr-xr-x root root srv
drwx------ root root app        ← 断点在这里：app 目录是 700，别人进不来
drwxr-xr-x app  app  data
-rw-r--r-- app  app  config.yaml
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;从上往下一层层看，哪一层的属主/属组/其他人段里轮到你时没有 x，就是堵点。修复时给那一级目录补 x 即可（&lt;code&gt;chmod o+x&lt;/code&gt; 或把目录属组改成服务用户所在的组再 &lt;code&gt;chmod g+x&lt;/code&gt;），不要图省事对整条路径递归 777。&lt;/p&gt;
&lt;h3&gt;场景二：sudo 提示 &quot;is not in the sudoers file&quot;&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;anex is not in the sudoers file. This incident will be reported.
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;意思是这个用户既不在 sudo 组、也没有单独的 sudoers 条目。解决办法是让一个已有 sudo 权限的人（或 root 本人）执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo usermod -aG sudo anex
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后该用户&lt;strong&gt;重新登录&lt;/strong&gt;再试。如果这台机器上已经没有任何能 sudo 的账号了，就只能走单用户/救援模式重置，代价大得多——所以服务器上至少保留两个有 sudo 权限的账号，是个便宜的保险。&lt;/p&gt;
&lt;h3&gt;场景三：把自己锁在 sudo 之外，怎么预防&lt;/h3&gt;
&lt;p&gt;sudoers 写错语法、或者手滑把自己的组改没了，都可能让唯一的管理员失去提权能力。预防靠三个习惯：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;改 sudoers 只用 &lt;code&gt;visudo&lt;/code&gt;，它会在保存前拦截语法错误。&lt;/li&gt;
&lt;li&gt;改动前先保留一个已登录的 root 会话（比如先开一个终端执行 &lt;code&gt;sudo -i&lt;/code&gt; 放着），改完后&lt;strong&gt;在另一个新终端里验证 sudo 能用&lt;/strong&gt;，确认无误再关旧会话。&lt;/li&gt;
&lt;li&gt;用 &lt;code&gt;usermod&lt;/code&gt; 改组时默念 &lt;code&gt;-aG&lt;/code&gt;，别把自己的 sudo 组替换掉。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;真锁死了也不是绝路：Debian 可以在 GRUB 启动菜单里编辑内核参数进入恢复模式（recovery mode），或用安装镜像挂载根分区后修复 &lt;code&gt;/etc/sudoers&lt;/code&gt; 与 &lt;code&gt;/etc/group&lt;/code&gt;。但这些都属于&quot;事后抢救&quot;，成本远高于事前留一个 root 会话。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;账号信息就是 &lt;code&gt;/etc/passwd&lt;/code&gt; + &lt;code&gt;/etc/shadow&lt;/code&gt; 两个文件；系统认 UID 不认名字，UID 0 即 root。&lt;/li&gt;
&lt;li&gt;建用户用 &lt;code&gt;useradd -m -s /bin/bash&lt;/code&gt;；改附加组永远用 &lt;code&gt;usermod -aG&lt;/code&gt;，丢了 &lt;code&gt;-a&lt;/code&gt; 会清掉原有组；改组后要重新登录才生效。&lt;/li&gt;
&lt;li&gt;sudo 的正规授权是加 sudo 组或写 &lt;code&gt;/etc/sudoers.d/&lt;/code&gt; 条目，改配置只用 &lt;code&gt;visudo&lt;/code&gt;，NOPASSWD 只给低风险命令。&lt;/li&gt;
&lt;li&gt;文件权限三段只取命中段：属主、属组、其他人；rwx 对文件和目录含义不同，目录的 x 管进入、w 管增删文件。&lt;/li&gt;
&lt;li&gt;常用组合记牢：目录 755、普通文件 644、私密文件 600；新建文件的默认权限由 umask 从 666/777 里扣出来。&lt;/li&gt;
&lt;li&gt;共享目录的标准解是&quot;属组 + setgid（2775）&quot;；零星例外用 ACL；权限报错先用 &lt;code&gt;namei -l&lt;/code&gt; 逐级找缺 x 的那一层，而不是无脑 777。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>MySQL 常用命令与操作实战</title><link>https://www.anexns.cloudns.org/posts/mysql-commands-guide/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/mysql-commands-guide/</guid><description>把 mysql 命令行客户端用顺手：连接与状态查看、库表结构管理、数据导入导出、事务与会话控制、SHOW 家族速查表，一篇覆盖日常运维 90% 的操作场景。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;这一篇的定位：你的 MySQL 日常工具箱&lt;/h2&gt;
&lt;p&gt;环境装好了（&lt;a href=&quot;/posts/mysql-install-config/&quot;&gt;MySQL 安装与初始配置&lt;/a&gt;）、账号分好了（&lt;a href=&quot;/posts/mysql-users-security/&quot;&gt;MySQL 用户权限与安全管理&lt;/a&gt;），剩下的就是天天要敲的命令。这一篇不讲原理，只讲操作：按「连接 → 看状态 → 管结构 → 导数据 → 控事务」的顺序，把高频命令一次理清。SQL 语法本身不熟的，先补 &lt;a href=&quot;/posts/sql-basics-crud/&quot;&gt;SQL 基础速成&lt;/a&gt; 再回来看。&lt;/p&gt;
&lt;h2&gt;连接与退出：先把姿势摆对&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;# 本机 socket 连接（同机运维最常用）
mysql -uroot -p

# TCP 连接远程或 Docker 映射端口
mysql -h 127.0.0.1 -P 3306 -uapp_rw -p appdb

# 连接后直接执行一条 SQL 就退出，适合写脚本
mysql -h 127.0.0.1 -uroot -p -e &quot;SHOW PROCESSLIST;&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个容易忽略的点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;-p&lt;/code&gt; 后面不要直接跟密码写在命令行里，会留在 shell 历史和进程列表中；交互输入或使用登录路径（&lt;code&gt;mysql_config_editor&lt;/code&gt;）更稳妥。&lt;/li&gt;
&lt;li&gt;进错库不用重连，客户端内 &lt;code&gt;USE appdb;&lt;/code&gt; 即可切换。&lt;/li&gt;
&lt;li&gt;退出用 &lt;code&gt;exit&lt;/code&gt; 或 &lt;code&gt;quit&lt;/code&gt;，Ctrl+C 在新版客户端里是中断当前输入行，别误以为卡死。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;连接后第一件事，看清自己是谁、连的哪台：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SELECT USER(), CURRENT_USER(), @@hostname, @@port, VERSION();
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;USER()&lt;/code&gt; 是你声称的身份，&lt;code&gt;CURRENT_USER()&lt;/code&gt; 是实际命中的账号——排权限问题时看后者，这个区别在上一篇已经强调过。&lt;/p&gt;
&lt;h2&gt;看状态：SHOW 家族速查&lt;/h2&gt;
&lt;p&gt;MySQL 运维的一半信息来自 &lt;code&gt;SHOW&lt;/code&gt; 命令，先给一张速查表：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;命令&lt;/th&gt;
&lt;th&gt;看什么&lt;/th&gt;
&lt;th&gt;高频场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SHOW DATABASES;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;全部库&lt;/td&gt;
&lt;td&gt;接手新实例先盘点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SHOW TABLES;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;当前库的表&lt;/td&gt;
&lt;td&gt;确认表是否存在&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SHOW CREATE TABLE orders\G&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;完整建表语句&lt;/td&gt;
&lt;td&gt;对比结构、复制表定义&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SHOW FULL PROCESSLIST;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;正在执行的连接与 SQL&lt;/td&gt;
&lt;td&gt;排查卡顿、锁等待第一现场&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SHOW STATUS LIKE &apos;Threads%&apos;;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;连接与线程计数&lt;/td&gt;
&lt;td&gt;判断是否快打满连接数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SHOW VARIABLES LIKE &apos;max_connections&apos;;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;参数当前值&lt;/td&gt;
&lt;td&gt;确认配置是否生效&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SHOW ENGINE INNODB STATUS\G&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;InnoDB 全景：事务、锁、死锁&lt;/td&gt;
&lt;td&gt;死锁与锁等待分析&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SHOW MASTER STATUS;&lt;/code&gt; / &lt;code&gt;SHOW REPLICA STATUS\G&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;主从复制状态&lt;/td&gt;
&lt;td&gt;复制中断排查&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SHOW GRANTS FOR &apos;u&apos;@&apos;h&apos;;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;某账号权限&lt;/td&gt;
&lt;td&gt;授权后复核&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SHOW WARNINGS;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;上一条语句的警告&lt;/td&gt;
&lt;td&gt;SQL 执行「成功但有警告」时必看&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;输出太长时记住两个技巧：语句结尾用 &lt;code&gt;\G&lt;/code&gt; 代替 &lt;code&gt;;&lt;/code&gt; 可以纵向排版（看长行字段必备）；客户端内 &lt;code&gt;pager less&lt;/code&gt; 可以分页翻看。&lt;/p&gt;
&lt;h2&gt;管理库表结构&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;-- 建库建表（字符集显式写明，原因见安装篇）
CREATE DATABASE shop CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
USE shop;

CREATE TABLE orders (
    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    user_id BIGINT NOT NULL,
    amount DECIMAL(10, 2) NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT &apos;pending&apos;,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    KEY idx_user (user_id)
) ENGINE = InnoDB;

-- 看结构
DESC orders;
SHOW INDEX FROM orders;

-- 改结构
ALTER TABLE orders ADD COLUMN remark VARCHAR(255) NULL AFTER status;
ALTER TABLE orders MODIFY COLUMN remark VARCHAR(500) NULL;
ALTER TABLE orders ADD INDEX idx_created (created_at);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;ALTER TABLE&lt;/code&gt; 在大表上可能是分钟级甚至小时级操作，且老版本会锁表。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;生产环境改结构前先确认表行数与业务低峰期&amp;lt;/span&amp;gt;，千万行级的大表优先考虑在线 DDL 工具（如 gh-ost、pt-online-schema-change）或 &lt;code&gt;ALGORITHM=INSTANT&lt;/code&gt; 是否适用，不要在业务高峰直接敲回车。
:::&lt;/p&gt;
&lt;p&gt;删除操作单独提醒一句：&lt;code&gt;DROP TABLE&lt;/code&gt;、&lt;code&gt;TRUNCATE TABLE&lt;/code&gt; 都不可回滚，执行前先确认当前库：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SELECT DATABASE();
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;在错误的库里执行 DROP 是运维事故的经典开场&amp;lt;/span&amp;gt;，养成先 &lt;code&gt;SELECT DATABASE()&lt;/code&gt; 再动手的肌肉记忆。&lt;/p&gt;
&lt;h2&gt;数据导入与导出&lt;/h2&gt;
&lt;h3&gt;逻辑导出：mysqldump&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 导出整个库（含建表与数据）
mysqldump -h 127.0.0.1 -uroot -p --single-transaction --routines --triggers shop &amp;gt; shop_backup.sql

# 只导出结构不要数据
mysqldump -h 127.0.0.1 -uroot -p --no-data shop &amp;gt; shop_schema.sql

# 只导出某几张表的数据
mysqldump -h 127.0.0.1 -uroot -p --single-transaction shop orders order_items &amp;gt; orders.sql
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--single-transaction&lt;/code&gt; 让 InnoDB 在一致性快照下导出，不锁表，是线上导出的标配参数。导入就是反向灌入：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mysql -h 127.0.0.1 -uroot -p shop &amp;lt; shop_backup.sql
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;完整的备份策略（全量、增量、binlog 时间点恢复）不在这里展开，系列里有专篇 &lt;a href=&quot;/posts/database-backup-restore/&quot;&gt;数据库备份与恢复全攻略&lt;/a&gt;。&lt;/p&gt;
&lt;h3&gt;表格数据：CSV 互通&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;-- 导出为 CSV（需要 FILE 权限，且受 secure_file_priv 目录限制）
SELECT id, user_id, amount FROM orders
INTO OUTFILE &apos;/var/lib/mysql-files/orders.csv&apos;
FIELDS TERMINATED BY &apos;,&apos; OPTIONALLY ENCLOSED BY &apos;&quot;&apos;
LINES TERMINATED BY &apos;\n&apos;;

-- 导入 CSV
LOAD DATA INFILE &apos;/var/lib/mysql-files/orders.csv&apos;
INTO TABLE orders
FIELDS TERMINATED BY &apos;,&apos; OPTIONALLY ENCLOSED BY &apos;&quot;&apos;
LINES TERMINATED BY &apos;\n&apos;
(id, user_id, amount);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;客户端本地文件版本是 &lt;code&gt;LOAD DATA LOCAL INFILE&lt;/code&gt;，需要服务端和客户端同时允许，安全上更敏感，用前确认开关状态。&lt;/p&gt;
&lt;h2&gt;事务与会话控制&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;-- 手动事务四件套
START TRANSACTION;
UPDATE accounts SET balance = balance - 100 WHERE id = 1;
UPDATE accounts SET balance = balance + 100 WHERE id = 2;
COMMIT;      -- 或 ROLLBACK;

-- 查看当前会话的事务隔离级别
SELECT @@transaction_isolation;

-- 找出长事务（超过 60 秒还没提交的）
SELECT trx_id, trx_started, trx_mysql_thread_id, trx_query
FROM information_schema.innodb_trx
WHERE TIME_TO_SEC(TIMEDIFF(NOW(), trx_started)) &amp;gt; 60;

-- 必要时终止某个连接（需要相应权限）
KILL 12345;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;长事务会拖住 Undo 日志回收、放大锁等待，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;发现长事务先联系业务确认再 KILL，不要看到就杀&amp;lt;/span&amp;gt;——杀掉一个正在跑批的事务，回滚本身可能更耗时。&lt;/p&gt;
&lt;h2&gt;用 information_schema 做盘点查询&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;SHOW&lt;/code&gt; 适合看单个对象，批量盘点则要用系统库 &lt;code&gt;information_schema&lt;/code&gt; 写 SQL 查。最常用的是这条「全库表体积排行」：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SELECT
    table_schema AS db,
    table_name AS tbl,
    table_rows AS est_rows,
    ROUND(data_length / 1024 / 1024, 1) AS data_mb,
    ROUND(index_length / 1024 / 1024, 1) AS index_mb,
    ROUND((data_length + index_length) / 1024 / 1024, 1) AS total_mb
FROM information_schema.tables
WHERE table_schema NOT IN (&apos;mysql&apos;, &apos;information_schema&apos;, &apos;performance_schema&apos;, &apos;sys&apos;)
ORDER BY total_mb DESC
LIMIT 20;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;table_rows&lt;/code&gt; 对 InnoDB 是估算值不是精确行数，要精确值得 &lt;code&gt;SELECT COUNT(*)&lt;/code&gt;（大表慎用，正好可以用上面这条先挑出大表再逐个确认）。其它高频盘点：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 哪些表还没有主键（应该全部有，这条结果最好为 0 行）
SELECT t.table_schema, t.table_name
FROM information_schema.tables t
LEFT JOIN information_schema.table_constraints c
  ON c.table_schema = t.table_schema
 AND c.table_name = t.table_name
 AND c.constraint_type = &apos;PRIMARY KEY&apos;
WHERE t.table_schema NOT IN (&apos;mysql&apos;, &apos;information_schema&apos;, &apos;performance_schema&apos;, &apos;sys&apos;)
  AND t.table_type = &apos;BASE TABLE&apos;
  AND c.constraint_name IS NULL;

-- 每个库占多大空间
SELECT table_schema, COUNT(*) AS tables_count,
       ROUND(SUM(data_length + index_length) / 1024 / 1024, 1) AS total_mb
FROM information_schema.tables
GROUP BY table_schema
ORDER BY total_mb DESC;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这类盘点 SQL 建议存成自己的运维脚本库，接手任何一台新实例先跑一遍，库表规模、缺主键的表、体积大户立刻心里有数。&lt;/p&gt;
&lt;h2&gt;客户端里的小效率工具&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;\s&lt;/code&gt;：查看连接状态（字符集、已运行时长等）。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;tee /tmp/session.log&lt;/code&gt;：把当前会话输出留档，排障复盘很好用。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--auto-rehash&lt;/code&gt; 默认开启，表名列名可以 Tab 补全；连大库嫌慢可加 &lt;code&gt;-A&lt;/code&gt; 关掉。&lt;/li&gt;
&lt;li&gt;批量跑脚本文件：&lt;code&gt;source /path/to/init.sql&lt;/code&gt;（客户端内）或 shell 里 &lt;code&gt;mysql db &amp;lt; file.sql&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;结果竖排查看宽表：查询后加 &lt;code&gt;\G&lt;/code&gt;，例如 &lt;code&gt;SELECT * FROM orders LIMIT 1\G&lt;/code&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：中文存进去变问号或乱码？&lt;/strong&gt;
连接、库、表、列四层字符集都要 utf8mb4。连接层可在登录后 &lt;code&gt;SET NAMES utf8mb4;&lt;/code&gt; 临时修正，根治是按安装篇把服务端与建表默认值都定死。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：&lt;code&gt;SHOW PROCESSLIST&lt;/code&gt; 里看到大量 Sleep 连接正常吗？&lt;/strong&gt;
Sleep 是空闲连接，应用连接池常驻就会有。数量稳定、无堆积增长就正常；持续逼近 &lt;code&gt;max_connections&lt;/code&gt; 才需要处理。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：执行 SQL 报 &lt;code&gt;ERROR 1820 (HY000): You must reset your password&lt;/code&gt;？&lt;/strong&gt;
账号密码已过期。用管理员账号执行 &lt;code&gt;ALTER USER ... IDENTIFIED BY ...&lt;/code&gt; 重置，或按策略调整该账号的过期设置，细节见 &lt;a href=&quot;/posts/mysql-users-security/&quot;&gt;MySQL 用户权限与安全管理&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：大查询把客户端卡住了怎么办？&lt;/strong&gt;
另开一个连接 &lt;code&gt;SHOW FULL PROCESSLIST&lt;/code&gt; 找到对应 Id 再 &lt;code&gt;KILL QUERY &amp;lt;id&amp;gt;&lt;/code&gt;（只杀查询不断连接）或 &lt;code&gt;KILL &amp;lt;id&amp;gt;&lt;/code&gt;（断连接）。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;连接先分清 &lt;code&gt;USER()&lt;/code&gt; 与 &lt;code&gt;CURRENT_USER()&lt;/code&gt;，排障少走弯路。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;SHOW&lt;/code&gt; 家族是运维的主力：PROCESSLIST 看现场、INNODB STATUS 看锁、CREATE TABLE 看定义。&lt;/li&gt;
&lt;li&gt;mysqldump 加 &lt;code&gt;--single-transaction&lt;/code&gt; 是线上导出的标准姿势；结构变更与 DROP 类操作先确认库、再挑时间。&lt;/li&gt;
&lt;li&gt;事务与长事务查询要会看，KILL 之前先确认。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;命令顺手之后，下一个话题自然是性能：&lt;a href=&quot;/posts/mysql-index-slow-query/&quot;&gt;MySQL 索引与慢查询优化&lt;/a&gt; 把慢查询日志和 EXPLAIN 串起来用。&lt;/p&gt;
</content:encoded></item><item><title>MySQL 索引与慢查询优化</title><link>https://www.anexns.cloudns.org/posts/mysql-index-slow-query/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/mysql-index-slow-query/</guid><description>从打开慢查询日志抓到元凶，到用 EXPLAIN 看懂 type、key、Extra，再到联合索引的最左前缀与索引失效的八大经典场景——一套完整的 MySQL 查询优化实战流程。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;主线：抓慢 SQL → 看执行计划 → 建对索引 → 复验&lt;/h2&gt;
&lt;p&gt;上一篇 &lt;a href=&quot;/posts/mysql-commands-guide/&quot;&gt;MySQL 常用命令与操作实战&lt;/a&gt; 解决了「怎么操作」，这一篇解决「为什么慢」。MySQL 查询优化不需要玄学，流程就四步：&lt;strong&gt;慢查询日志负责抓现行，EXPLAIN 负责解释原因，索引负责解决问题，最后复验数字&lt;/strong&gt;。这一篇把四步全部走通，索引原理部分可以和 &lt;a href=&quot;/posts/postgresql-index-optimization/&quot;&gt;PostgreSQL 索引与查询优化入门&lt;/a&gt; 对照着看，两边思路相通、细节有别。&lt;/p&gt;
&lt;p&gt;测试表沿用订单场景，造一百万行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE TABLE orders (
    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    user_id BIGINT NOT NULL,
    status VARCHAR(20) NOT NULL,
    amount DECIMAL(10, 2) NOT NULL,
    created_at DATETIME NOT NULL,
    PRIMARY KEY (id),
    KEY idx_user (user_id)
) ENGINE = InnoDB;

INSERT INTO orders (user_id, status, amount, created_at)
SELECT FLOOR(1 + RAND() * 10000),
       ELT(1 + FLOOR(RAND() * 3), &apos;paid&apos;, &apos;pending&apos;, &apos;cancelled&apos;),
       ROUND(RAND() * 1000, 2),
       NOW() - INTERVAL FLOOR(RAND() * 365) DAY
FROM information_schema.columns a, information_schema.columns b
LIMIT 1000000;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;第一步：用慢查询日志抓元凶&lt;/h2&gt;
&lt;p&gt;安装篇的 my.cnf 已经开启了慢查询日志（阈值 &lt;code&gt;long_query_time = 1&lt;/code&gt; 秒）。确认状态并临时调低阈值抓现行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SHOW VARIABLES LIKE &apos;slow_query_log%&apos;;
SHOW VARIABLES LIKE &apos;long_query_time&apos;;

-- 本会话临时把阈值降到 0.1 秒观察（全局修改需 SUPER 权限）
SET GLOBAL long_query_time = 0.1;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;原始日志可读性一般，用官方自带的 &lt;code&gt;mysqldumpslow&lt;/code&gt; 做聚合统计，按总耗时找最值得优化的 SQL：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 按累计总时间排序，取前 10 条
mysqldumpslow -s t -t 10 /var/log/mysql/slow.log

# 按出现次数排序，找高频小慢查询
mysqldumpslow -s c -t 10 /var/log/mysql/slow.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;优化优先级看两个维度：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;总耗时 = 单次耗时 × 出现次数&amp;lt;/span&amp;gt;。一条 3 秒的 SQL 一天跑 3 次，不如一条 0.3 秒的 SQL 一天跑十万次更值得先治。&lt;/p&gt;
&lt;h2&gt;第二步：看懂 EXPLAIN&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;EXPLAIN SELECT * FROM orders WHERE status = &apos;paid&apos; AND created_at &amp;gt;= &apos;2026-06-01&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重点盯五列：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;列&lt;/th&gt;
&lt;th&gt;看什么&lt;/th&gt;
&lt;th&gt;危险信号&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;type&lt;/td&gt;
&lt;td&gt;访问方式，从好到差：system &amp;gt; const &amp;gt; eq_ref &amp;gt; ref &amp;gt; range &amp;gt; index &amp;gt; ALL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ALL&lt;/code&gt; 即全表扫描，大表要警惕&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;key&lt;/td&gt;
&lt;td&gt;实际用到的索引&lt;/td&gt;
&lt;td&gt;为 NULL 说明没用上索引&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;rows&lt;/td&gt;
&lt;td&gt;预估扫描行数&lt;/td&gt;
&lt;td&gt;与实际返回行数差几个数量级就不对劲&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;filtered&lt;/td&gt;
&lt;td&gt;条件过滤后剩余比例&lt;/td&gt;
&lt;td&gt;很低说明大量行被读出来又扔掉&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Extra&lt;/td&gt;
&lt;td&gt;附加信息&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Using filesort&lt;/code&gt;、&lt;code&gt;Using temporary&lt;/code&gt; 要重点看&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;EXPLAIN ANALYZE&lt;/code&gt;（8.0.18+）会真实执行并给出每一步的实际耗时与行数，排障时优先用它。JSON 格式更详细：&lt;code&gt;EXPLAIN FORMAT=JSON&lt;/code&gt;，能看到成本估算细节。&lt;/p&gt;
&lt;h2&gt;第三步：索引怎么建才有效&lt;/h2&gt;
&lt;h3&gt;联合索引与最左前缀&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;ALTER TABLE orders ADD INDEX idx_user_status_created (user_id, status, created_at);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;联合索引 (a, b, c) 能支撑的查询形态：a、a+b、a+b+c、a+b+范围(c)。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;跳过 a 直接查 b、c，索引用不上&amp;lt;/span&amp;gt;，这就是最左前缀原则，与 PostgreSQL 的规则一致。列顺序口诀：&lt;strong&gt;等值条件在前，范围条件在后&lt;/strong&gt;；等值列之间把区分度高的放前面。&lt;/p&gt;
&lt;h3&gt;覆盖索引&lt;/h3&gt;
&lt;p&gt;查询要的列全部包含在索引里时，Extra 显示 &lt;code&gt;Using index&lt;/code&gt;，不需要回表查聚簇索引：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 这条查询只取 user_id、status、amount
-- 若索引为 (user_id, status, amount)，即为覆盖索引
SELECT user_id, status, amount FROM orders WHERE user_id = 42;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;前缀索引&lt;/h3&gt;
&lt;p&gt;长字符串列（如 URL、邮箱）全列建索引太占空间，可以只索引前 N 个字符：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ALTER TABLE users ADD INDEX idx_email_prefix (email(16));
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;代价是无法用索引完成排序与覆盖查询，N 的取值要按实际区分度测试决定。&lt;/p&gt;
&lt;h2&gt;索引失效的八大经典场景&lt;/h2&gt;
&lt;p&gt;索引建了却不走，是日常最高频的问题。对照这张表逐项排查：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;#&lt;/th&gt;
&lt;th&gt;失效场景&lt;/th&gt;
&lt;th&gt;示例&lt;/th&gt;
&lt;th&gt;改法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;对列做函数运算&lt;/td&gt;
&lt;td&gt;&lt;code&gt;WHERE DATE(created_at) = &apos;2026-01-01&apos;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;改写为范围条件 &lt;code&gt;&amp;gt;= &apos;2026-01-01&apos; AND &amp;lt; &apos;2026-01-02&apos;&lt;/code&gt;，或建函数索引&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;隐式类型转换&lt;/td&gt;
&lt;td&gt;字段是 VARCHAR 却传数字 &lt;code&gt;WHERE phone = 13800138000&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;参数加引号，类型对齐&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;前导模糊查询&lt;/td&gt;
&lt;td&gt;&lt;code&gt;LIKE &apos;%abc&apos;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;前缀匹配 &lt;code&gt;LIKE &apos;abc%&apos;&lt;/code&gt; 可用索引；全文需求上全文索引&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;联合索引跳列&lt;/td&gt;
&lt;td&gt;只查 b 列&lt;/td&gt;
&lt;td&gt;补齐最左列或单独建索引&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;OR 两侧列不一致&lt;/td&gt;
&lt;td&gt;&lt;code&gt;WHERE user_id = 1 OR status = &apos;paid&apos;&lt;/code&gt;（status 无索引）&lt;/td&gt;
&lt;td&gt;拆 UNION，或给两列都建索引&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;范围后列失效&lt;/td&gt;
&lt;td&gt;(a,b,c) 上 &lt;code&gt;a = 1 AND b &amp;gt; 2 AND c = 3&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;c 用不上索引排序/定位，调整列序或接受现状&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;不等于与 NOT IN&lt;/td&gt;
&lt;td&gt;&lt;code&gt;WHERE status &amp;lt;&amp;gt; &apos;paid&apos;&lt;/code&gt; 选择性差&lt;/td&gt;
&lt;td&gt;优化器常主动放弃，属正常决策居多&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;8&lt;/td&gt;
&lt;td&gt;低区分度列单建索引&lt;/td&gt;
&lt;td&gt;给 status 这种三值列单建索引&lt;/td&gt;
&lt;td&gt;并入联合索引，别单建&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
看到 &lt;code&gt;type = ALL&lt;/code&gt; 先别急着下「缺索引」的结论。小表全表扫描、或查询本来就要返回大半张表时，优化器放弃索引是正确决策。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;强行 FORCE INDEX 把慢查询「修好」的案例，十有八九在数据量变化后翻倍反弹&amp;lt;/span&amp;gt;。先看 rows 与实际返回行数的比例再判断。
:::&lt;/p&gt;
&lt;h2&gt;其它索引类型速览&lt;/h2&gt;
&lt;p&gt;除了最常用的 B-Tree（普通、唯一、联合、前缀都属此类），MySQL 还有几种专用索引，知道边界即可：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;索引类型&lt;/th&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;th&gt;关键限制&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;唯一索引（UNIQUE）&lt;/td&gt;
&lt;td&gt;保证列值不重复，顺带加速查询&lt;/td&gt;
&lt;td&gt;业务唯一性应由它兜底，不要只靠应用层判断&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;全文索引（FULLTEXT）&lt;/td&gt;
&lt;td&gt;对 TEXT / VARCHAR 做关键词检索&lt;/td&gt;
&lt;td&gt;中文需用 ngram 解析器：&lt;code&gt;WITH PARSER ngram&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;空间索引（SPATIAL）&lt;/td&gt;
&lt;td&gt;地理坐标的范围查询&lt;/td&gt;
&lt;td&gt;列须为几何类型且建索引时列不能为 NULL&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;函数索引（8.0.13+）&lt;/td&gt;
&lt;td&gt;给表达式结果建索引&lt;/td&gt;
&lt;td&gt;索引定义里表达式要加双层括号&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;函数索引正好对应失效场景表里的第 1 条，示例：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 老办法：改写查询为范围条件（优先）
SELECT * FROM orders WHERE created_at &amp;gt;= &apos;2026-01-01&apos; AND created_at &amp;lt; &apos;2026-01-02&apos;;

-- 改不了查询时：给表达式建索引
ALTER TABLE orders ADD INDEX idx_date_created ((DATE(created_at)));
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;全文索引的中文用法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ALTER TABLE articles ADD FULLTEXT INDEX ft_title_body (title, body) WITH PARSER ngram;
SELECT * FROM articles WHERE MATCH(title, body) AGAINST(&apos;数据库优化&apos; IN NATURAL LANGUAGE MODE);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;数据量与检索质量要求再上一个台阶时，应考虑 Elasticsearch 等专用搜索引擎，MySQL 全文索引适合的是中小规模站内搜索。&lt;/p&gt;
&lt;h2&gt;统计信息：优化器的「眼睛」也要保养&lt;/h2&gt;
&lt;p&gt;优化器选不选索引、选哪个，依据的是统计信息（基数估算）。数据大幅变化后统计过期，是「同样的 SQL 以前快、现在慢」的常见原因：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 手动刷新某张表的统计信息
ANALYZE TABLE orders;

-- 查看索引的基数估算（某列 distinct 值约数）
SHOW INDEX FROM orders;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;InnoDB 默认开启自动统计采样，一般不用人工干预；但在大批量导入、删除归档之后，手动 &lt;code&gt;ANALYZE TABLE&lt;/code&gt; 一次成本很低、收益明确。还要注意直方图（Histogram）这个进阶工具：对分布严重倾斜的列（如 status 里 99% 是同一值），给优化器补一份直方图能显著改善行数估算：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ANALYZE TABLE orders UPDATE HISTOGRAM ON status WITH 16 BUCKETS;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;第四步：复验与持续观察&lt;/h2&gt;
&lt;p&gt;改完索引重新 EXPLAIN，并对比慢查询日志里同一条 SQL 的耗时变化。还可以借助 Performance Schema 做持续聚合统计：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 按总耗时排序的 SQL 摘要（sys 库格式化版本）
SELECT query, exec_count, total_latency, avg_latency
FROM sys.statement_analysis
ORDER BY total_latency DESC
LIMIT 10;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;更完整的监控体系与告警，见系列收官篇 &lt;a href=&quot;/posts/database-monitoring-troubleshooting/&quot;&gt;数据库性能监控与常见故障排障&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;还有两个配套习惯值得养成：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;索引命名规范&lt;/strong&gt;：普通索引 &lt;code&gt;idx_&lt;/code&gt; 前缀、唯一索引 &lt;code&gt;uk_&lt;/code&gt; 前缀，后面跟列名缩写，半年后看名字就知道用途。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;删索引要谨慎&lt;/strong&gt;：&lt;code&gt;SHOW INDEX FROM orders;&lt;/code&gt; 盘点后，疑似无用的索引先改名为观察（8.0 支持 &lt;code&gt;ALTER TABLE ... ALTER INDEX idx INVISIBLE;&lt;/code&gt;），确认无影响再真正删除：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;ALTER TABLE orders ALTER INDEX idx_user INVISIBLE;  -- 先隐形观察
ALTER TABLE orders DROP INDEX idx_user;            -- 确认无恙再删
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：EXPLAIN 里 key 用了索引，为什么还是慢？&lt;/strong&gt;
可能扫描行数本身就大（rows 很高），或回表次数太多。看 Extra 有没有 &lt;code&gt;Using filesort&lt;/code&gt;（排序没走索引）、回表量能否用覆盖索引消掉，或者查询条件本身区分度不足。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：&lt;code&gt;Using filesort&lt;/code&gt; 一定要消除吗？&lt;/strong&gt;
不一定。小结果集的内存排序很快；只有大行数排序才值得为它调整索引列序或改写查询。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：新加的索引线上没生效？&lt;/strong&gt;
先 &lt;code&gt;ANALYZE TABLE orders;&lt;/code&gt; 刷新统计信息；再确认查询写法没踩失效场景表；最后检查是否被优化器认为成本更高而主动放弃——用 &lt;code&gt;EXPLAIN FORMAT=JSON&lt;/code&gt; 看成本对比。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：索引是不是建在 WHERE 里出现最多的列上就行？&lt;/strong&gt;
还要看 JOIN 的关联列、ORDER BY / GROUP BY 的列。三者综合考虑，联合索引设计本质是给「过滤 + 关联 + 排序」的组合买单。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;优化四步走：慢日志抓 SQL、EXPLAIN 定原因、索引解决问题、复验看数字，优先级按总耗时排序。&lt;/li&gt;
&lt;li&gt;EXPLAIN 五个关键列：type、key、rows、filtered、Extra。&lt;/li&gt;
&lt;li&gt;联合索引守最左前缀，等值在前、范围在后；覆盖索引靠免回表提速。&lt;/li&gt;
&lt;li&gt;索引失效八场景对照排查；优化器放弃索引有时是正确的，别滥用 FORCE INDEX。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;MySQL 部分到此完整。下一篇切换到 Redis：&lt;a href=&quot;/posts/redis-install-config/&quot;&gt;Redis 安装与初始配置&lt;/a&gt;。&lt;/p&gt;
</content:encoded></item><item><title>MySQL 安装与初始配置</title><link>https://www.anexns.cloudns.org/posts/mysql-install-config/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/mysql-install-config/</guid><description>从零把 MySQL 8.4 跑起来：Docker Compose 部署与系统包安装两条路线对比，讲清 my.cnf 核心参数、字符集 utf8mb4、时区与 root 账号初始化，给你一套能直接用于生产的起步配置。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;这篇解决什么问题&lt;/h2&gt;
&lt;p&gt;从这一篇开始进入 MySQL 部分。目标很具体：&lt;strong&gt;把 MySQL 8.4 LTS 以正确的姿势跑起来&lt;/strong&gt;——字符集不错、时区不错、关键参数不踩默认值坑，后面讲用户权限和命令实战时就不用再回头补课。&lt;/p&gt;
&lt;p&gt;安装路线有两条：Docker Compose 和系统包安装。本系列整体推荐 Docker 路线（&lt;a href=&quot;/posts/database-docker-quickstart/&quot;&gt;用 Docker 快速搭建三大数据库&lt;/a&gt; 里已经给过三合一的 Compose），这一篇会把 MySQL 单独拆开讲透，并补上系统包安装方式方便对照。选型还没想清楚的，先看 &lt;a href=&quot;/posts/database-choosing-guide/&quot;&gt;数据库怎么选&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;路线一：Docker Compose 部署（推荐）&lt;/h2&gt;
&lt;p&gt;目录结构与 Compose 文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/mysql8/{data,conf,logs} &amp;amp;&amp;amp; cd ~/mysql8
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;# docker-compose.yml
services:
  mysql:
    image: mysql:8.4
    container_name: mysql8
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: &quot;ChangeMe_2026!&quot;
      TZ: Asia/Shanghai
    ports:
      - &quot;127.0.0.1:3306:3306&quot;
    volumes:
      - ./data:/var/lib/mysql
      - ./conf/my.cnf:/etc/mysql/conf.d/my.cnf:ro
      - ./logs:/var/log/mysql
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_0900_ai_ci
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;自定义配置文件 &lt;code&gt;conf/my.cnf&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[mysqld]
# 基础
character-set-server = utf8mb4
collation-server = utf8mb4_0900_ai_ci
default-time-zone = &apos;+08:00&apos;
max_connections = 300
wait_timeout = 28800

# InnoDB（内存按机器规格调整，下面按 4 GB 内存机器示例）
innodb_buffer_pool_size = 2G
innodb_log_file_size = 512M
innodb_flush_log_at_trx_commit = 1
sync_binlog = 1

# 日志：慢查询先开起来，下一篇优化全靠它
slow_query_log = 1
slow_query_log_file = /var/log/mysql/slow.log
long_query_time = 1
log_error = /var/log/mysql/error.log
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动并验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose logs -f mysql   # 看到 ready for connections 再继续
docker exec -it mysql8 mysql -uroot -p -e &quot;SELECT VERSION(); SHOW VARIABLES LIKE &apos;character_set_server&apos;;&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;路线二：系统包安装（Debian / Ubuntu）&lt;/h2&gt;
&lt;p&gt;MySQL 官方 APT 仓库提供 8.4 LTS。简化流程如下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 安装官方仓库配置包后
sudo apt update
sudo apt install -y mysql-server

sudo systemctl enable --now mysql
sudo mysql_secure_installation
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;mysql_secure_installation&lt;/code&gt; 会引导设置 root 密码强度策略、删除匿名用户、禁止 root 远程登录、删除 test 库，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;这一步不要跳过&amp;lt;/span&amp;gt;，它是裸装 MySQL 最重要的安全动作。系统包方式的配置文件在 &lt;code&gt;/etc/mysql/mysql.conf.d/mysqld.cnf&lt;/code&gt;，参数名与上面 my.cnf 完全通用。&lt;/p&gt;
&lt;p&gt;两条路线对比：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;Docker Compose&lt;/th&gt;
&lt;th&gt;系统包安装&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;环境隔离&lt;/td&gt;
&lt;td&gt;好，版本切换靠换镜像 tag&lt;/td&gt;
&lt;td&gt;与系统耦合，升级走 APT&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据目录&lt;/td&gt;
&lt;td&gt;宿主机挂载目录，直观可控&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/var/lib/mysql&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;配置位置&lt;/td&gt;
&lt;td&gt;项目内 &lt;code&gt;conf/my.cnf&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/etc/mysql/&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合场景&lt;/td&gt;
&lt;td&gt;个人服务器、多实例、快速试错&lt;/td&gt;
&lt;td&gt;长期单实例、习惯 systemd 管理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;备份迁移&lt;/td&gt;
&lt;td&gt;打包目录即可搬走&lt;/td&gt;
&lt;td&gt;需配合 mysqldump 或停机拷数据&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;初始配置的四个必查项&lt;/h2&gt;
&lt;h3&gt;1. 字符集必须是 utf8mb4&lt;/h3&gt;
&lt;p&gt;MySQL 历史上的 &lt;code&gt;utf8&lt;/code&gt; 是残缺版（每字符最多 3 字节），存不下 emoji 和部分生僻字。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;新装实例一律 utf8mb4，排序规则用 utf8mb4_0900_ai_ci（8.x 默认）或需要区分大小写时用 utf8mb4_bin。&amp;lt;/span&amp;gt;验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SHOW VARIABLES LIKE &apos;character_set%&apos;;
SHOW VARIABLES LIKE &apos;collation%&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;建库时也显式写明，别依赖默认值漂移：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE DATABASE appdb CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;2. 时区显式设为 +08:00&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;TIMESTAMP&lt;/code&gt; 类型会按时区转换存储与显示，时区不一致是「时间差了 8 小时」类 Bug 的头号来源。Docker 方式已通过环境变量和 my.cnf 双保险；系统包安装记得在 my.cnf 写 &lt;code&gt;default-time-zone = &apos;+08:00&apos;&lt;/code&gt;，并确认系统时区正确：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SELECT @@global.time_zone, @@session.time_zone, NOW();
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;3. InnoDB 缓冲池按内存给&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;innodb_buffer_pool_size&lt;/code&gt; 是 MySQL 最重要的性能参数，决定多少热数据能留在内存里。经验值：&lt;strong&gt;专职数据库机器给物理内存的 50%–70%&lt;/strong&gt;，与其它服务混跑时保守些。给太小查询全走磁盘，给太大则可能触发 OOM。修改后需重启生效（8.0 起部分场景支持在线调整，但重启最稳妥）。&lt;/p&gt;
&lt;h3&gt;4. root 账号只用于初始化&lt;/h3&gt;
&lt;p&gt;官方镜像首次启动时用环境变量里的密码初始化 root。初始化完成后，第一件事应该是创建业务账号和管理员账号，root 只留作应急。账号体系与授权方法在下一篇 &lt;a href=&quot;/posts/mysql-users-security/&quot;&gt;MySQL 用户权限与安全管理&lt;/a&gt; 专门讲，这里先记住原则：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要用 root 账号跑业务程序&amp;lt;/span&amp;gt;，更不要把 root 开放到公网远程登录。&lt;/p&gt;
&lt;p&gt;:::warning
Docker 部署时端口绑定务必注意：&lt;code&gt;ports&lt;/code&gt; 写成 &lt;code&gt;&quot;3306:3306&quot;&lt;/code&gt; 等于对所有网卡开放，配合弱密码很容易被扫描爆破。本文示例绑定 &lt;code&gt;127.0.0.1:3306&lt;/code&gt; 只允许本机访问，需要远程连接时优先走 SSH 隧道或内网，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要图省事直接把 3306 暴露到公网&amp;lt;/span&amp;gt;。
:::&lt;/p&gt;
&lt;h2&gt;常用参数速览：知道每个参数在管什么&lt;/h2&gt;
&lt;p&gt;上面 my.cnf 里出现的参数只是起步集，这里把日常最常打交道的参数汇成一张表，调优时对照着看：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;参数&lt;/th&gt;
&lt;th&gt;默认值（8.4）&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;调整建议&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;max_connections&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;151&lt;/td&gt;
&lt;td&gt;允许的最大并发连接数&lt;/td&gt;
&lt;td&gt;按应用连接池总量留 20% 余量，不是越大越好，每个连接都占内存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;innodb_buffer_pool_size&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;128M&lt;/td&gt;
&lt;td&gt;InnoDB 数据与索引的缓存区&lt;/td&gt;
&lt;td&gt;默认值小得离谱，装完第一件事就是按内存改大&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;innodb_log_file_size&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;48M&lt;/td&gt;
&lt;td&gt;Redo 日志单个文件大小&lt;/td&gt;
&lt;td&gt;写密集型可调到 512M–1G，减少刷盘频率&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;max_allowed_packet&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;64M&lt;/td&gt;
&lt;td&gt;单个数据包最大大小&lt;/td&gt;
&lt;td&gt;导入大 SQL 文件或存大字段时报包过大，就是调它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;wait_timeout&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;28800 秒&lt;/td&gt;
&lt;td&gt;非交互连接的空闲断开时间&lt;/td&gt;
&lt;td&gt;连接池场景可适当调小，避免僵尸连接占坑&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;slow_query_log&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;OFF&lt;/td&gt;
&lt;td&gt;慢查询日志开关&lt;/td&gt;
&lt;td&gt;生产必须开，阈值起步设 1 秒&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;binlog_expire_logs_seconds&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;2592000（30 天）&lt;/td&gt;
&lt;td&gt;binlog 自动过期时间&lt;/td&gt;
&lt;td&gt;磁盘紧张时调小，但要先确认备份与主从不再需要老日志&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;character_set_server&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;utf8mb4&lt;/td&gt;
&lt;td&gt;服务端默认字符集&lt;/td&gt;
&lt;td&gt;8.x 默认已是 utf8mb4，老实例升级来的要专门确认&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;查参数当前值与来源的命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 看某个参数现在是多少
SHOW GLOBAL VARIABLES LIKE &apos;innodb_buffer_pool_size&apos;;

-- 看某个参数是在哪个配置文件里定义的（Performance Schema，8.0+）
SELECT VARIABLE_NAME, VARIABLE_SOURCE, SET_TIME
FROM performance_schema.variables_info
WHERE VARIABLE_NAME IN (&apos;max_connections&apos;, &apos;innodb_buffer_pool_size&apos;);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;VARIABLE_SOURCE&lt;/code&gt; 会告诉你值来自编译默认（COMPILED）、配置文件（FILE）还是运行时动态修改（DYNAMIC），排「改了配置没生效」类问题时特别好用。&lt;/p&gt;
&lt;h2&gt;连接与健康检查&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;# 宿主机装了客户端时
mysql -h 127.0.0.1 -P 3306 -uroot -p

# 没装客户端就借容器内的
docker exec -it mysql8 mysql -uroot -p
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;连上后跑一轮体检 SQL：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SHOW VARIABLES LIKE &apos;max_connections&apos;;
SHOW VARIABLES LIKE &apos;innodb_buffer_pool_size&apos;;
SHOW STATUS LIKE &apos;Threads_connected&apos;;
SHOW ENGINE INNODB STATUS\G
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;最后一段 &lt;code&gt;SHOW ENGINE INNODB STATUS&lt;/code&gt; 输出很长，重点看有没有死锁记录和异常等待，日常排障时是重要线索。&lt;/p&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：容器反复重启，日志报 &lt;code&gt;Table &apos;mysql.plugin&apos; doesn&apos;t exist&lt;/code&gt; 或数据目录权限错误？&lt;/strong&gt;
多半是 &lt;code&gt;data&lt;/code&gt; 目录曾经被其它版本或空目录污染。确认目录里没有要保留的数据后清空重新初始化；另外宿主机目录属主问题在官方镜像里一般会自动处理（容器内以 mysql 用户运行），不要手动乱改属主。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：改了 my.cnf 没生效？&lt;/strong&gt;
先确认挂载路径对不对：官方镜像读取 &lt;code&gt;/etc/mysql/conf.d/&lt;/code&gt; 和 &lt;code&gt;/etc/mysql/mysql.conf.d/&lt;/code&gt; 下的配置。用 &lt;code&gt;docker exec mysql8 mysqld --verbose --help | grep -A1 &apos;Default options&apos;&lt;/code&gt; 查看它实际读取的配置文件列表。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：&lt;code&gt;Access denied for user &apos;root&apos;&lt;/code&gt; 本地都登不上？&lt;/strong&gt;
Docker 方式先确认连的是不是刚初始化的那个实例、密码是否与环境变量一致。注意：&lt;code&gt;MYSQL_ROOT_PASSWORD&lt;/code&gt; 只在数据目录为空、首次初始化时生效，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;事后改环境变量不会修改已有密码&amp;lt;/span&amp;gt;，改密码要用 SQL：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ALTER USER &apos;root&apos;@&apos;localhost&apos; IDENTIFIED BY &apos;NewStrongPass_2026!&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;Q：内存只有 1–2 GB 的小机器参数怎么调？&lt;/strong&gt;
&lt;code&gt;innodb_buffer_pool_size&lt;/code&gt; 给 256M–512M，&lt;code&gt;max_connections&lt;/code&gt; 降到 100 以内，并关掉不用的功能如 Performance Schema 的部分消费者。小机器能跑稳比参数好看重要。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;推荐 Docker Compose 部署 MySQL 8.4，配置、数据、日志都落在项目目录里，可控可迁移。&lt;/li&gt;
&lt;li&gt;初始配置四件套：utf8mb4 字符集、&lt;code&gt;+08:00&lt;/code&gt; 时区、合理大小的 InnoDB 缓冲池、root 只作初始化。&lt;/li&gt;
&lt;li&gt;安全底线：跑 &lt;code&gt;mysql_secure_installation&lt;/code&gt;（系统包）或等效处理，3306 不裸奔公网。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;环境就绪，下一篇给它上锁：&lt;a href=&quot;/posts/mysql-users-security/&quot;&gt;MySQL 用户权限与安全管理&lt;/a&gt;；日常操作命令则在 &lt;a href=&quot;/posts/mysql-commands-guide/&quot;&gt;MySQL 常用命令与操作实战&lt;/a&gt; 里系统梳理。&lt;/p&gt;
</content:encoded></item><item><title>MySQL 用户权限与安全管理</title><link>https://www.anexns.cloudns.org/posts/mysql-users-security/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/mysql-users-security/</guid><description>MySQL 的账号是「用户@主机」二元组，搞懂这一点权限管理就通了一大半。这篇讲清 CREATE USER 与 GRANT 的正确姿势、最小权限原则、密码策略与账号锁定，并给出一套上线前的安全自查清单。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先建立正确的心智模型：账号 = 用户名 + 来源主机&lt;/h2&gt;
&lt;p&gt;上一篇 &lt;a href=&quot;/posts/mysql-install-config/&quot;&gt;MySQL 安装与初始配置&lt;/a&gt; 里我们只用 root 完成了初始化。从这篇开始，把账号体系正规化。&lt;/p&gt;
&lt;p&gt;MySQL 权限系统最容易误解的一点：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;code&gt;&apos;app&apos;@&apos;localhost&apos;&lt;/code&gt; 和 &lt;code&gt;&apos;app&apos;@&apos;%&apos;&lt;/code&gt; 是两个完全独立的账号&amp;lt;/span&amp;gt;，密码、权限都各算各的。授权、改密码、删账号时必须把 &lt;code&gt;@主机&lt;/code&gt; 部分写全，漏写就会出现「我明明授权了为什么还是没权限」的经典困惑。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;localhost&lt;/code&gt;：只允许本机通过 socket 或回环连接。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;%&lt;/code&gt;：允许任意来源主机，范围最大，慎用。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;192.168.1.%&lt;/code&gt; / 具体 IP：限定网段或单个来源，生产环境优先这种写法。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;创建账号与授权：两步走，不要一步到位&lt;/h2&gt;
&lt;p&gt;MySQL 8.0 起 &lt;code&gt;GRANT&lt;/code&gt; 不能再顺带创建用户，必须分开写。这反而是好事，职责更清晰：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 第一步：建账号并设密码（限定只能从应用服务器所在网段连）
CREATE USER &apos;app_rw&apos;@&apos;192.168.1.%&apos; IDENTIFIED BY &apos;AppStrong_2026!&apos;;

-- 第二步：按需授权，只给业务库的增删改查
GRANT SELECT, INSERT, UPDATE, DELETE ON appdb.* TO &apos;app_rw&apos;@&apos;192.168.1.%&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;授权层级从大到小有四层，遵循就小不就大：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;授权范围&lt;/th&gt;
&lt;th&gt;写法&lt;/th&gt;
&lt;th&gt;典型用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;全局&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ON *.*&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;仅管理员账号，等同超级权限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据库级&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ON appdb.*&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;一个应用一个库，最常用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;表级&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ON appdb.orders&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只允许碰某几张表&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;列级&lt;/td&gt;
&lt;td&gt;&lt;code&gt;GRANT SELECT (id, name) ON appdb.users&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;敏感列只读脱敏场景&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;只读报表账号的例子：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE USER &apos;report_ro&apos;@&apos;%&apos; IDENTIFIED BY &apos;Report_2026!&apos;;
GRANT SELECT ON appdb.* TO &apos;report_ro&apos;@&apos;%&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;带管理权限的运维账号则要克制得多，宁可拆成「日常账号 + 应急账号」两个：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE USER &apos;dba&apos;@&apos;192.168.1.10&apos; IDENTIFIED BY &apos;DbaStrong_2026!&apos;;
GRANT ALL PRIVILEGES ON *.* TO &apos;dba&apos;@&apos;192.168.1.10&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;最小权限原则：哪些权限不能随便给&lt;/h2&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;SUPER、FILE、GRANT OPTION 是三类最危险的权限&amp;lt;/span&amp;gt;，给了业务账号等于交出服务器：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;FILE&lt;/code&gt;：可以读写服务器文件系统，配合 &lt;code&gt;LOAD_FILE&lt;/code&gt; / &lt;code&gt;INTO OUTFILE&lt;/code&gt; 能读配置、写 WebShell。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;SUPER&lt;/code&gt;：能改全局变量、杀任意连接、绕过只读限制。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;GRANT OPTION&lt;/code&gt;：能把自己的权限再转授给别人，权限会失控扩散。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;业务账号的权限白名单建议：&lt;code&gt;SELECT, INSERT, UPDATE, DELETE&lt;/code&gt;，需要建临时表再加 &lt;code&gt;CREATE TEMPORARY TABLES&lt;/code&gt;，需要看视图加 &lt;code&gt;SHOW VIEW&lt;/code&gt;。像 &lt;code&gt;DROP&lt;/code&gt;、&lt;code&gt;ALTER&lt;/code&gt; 这类结构变更权限，交给发布流程用的专用账号，不要给运行时账号——这样即使应用被注入，攻击者也删不了表。&lt;/p&gt;
&lt;p&gt;查看一个账号现有权限与全库账号盘点：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SHOW GRANTS FOR &apos;app_rw&apos;@&apos;192.168.1.%&apos;;

SELECT user, host FROM mysql.user ORDER BY user, host;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;回收权限与删除账号：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;REVOKE DELETE ON appdb.* FROM &apos;app_rw&apos;@&apos;192.168.1.%&apos;;
DROP USER &apos;old_app&apos;@&apos;%&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 MySQL 8.0 中 &lt;code&gt;GRANT&lt;/code&gt; / &lt;code&gt;REVOKE&lt;/code&gt; 执行后立即生效，不需要再手动 &lt;code&gt;FLUSH PRIVILEGES&lt;/code&gt;（只有直接改 &lt;code&gt;mysql&lt;/code&gt; 系统表时才需要）。&lt;/p&gt;
&lt;h2&gt;密码策略与账号防护&lt;/h2&gt;
&lt;p&gt;MySQL 8.4 默认启用 &lt;code&gt;caching_sha2_password&lt;/code&gt; 认证插件。配套的密码强度与生命周期管理：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 查看密码验证组件是否启用
SHOW VARIABLES LIKE &apos;validate_password%&apos;;

-- 设置全局密码过期天数（0 表示永不过期，按公司规范取舍）
SET GLOBAL default_password_lifetime = 180;

-- 单独要求某个账号定期改密，并限制登录失败锁定
ALTER USER &apos;app_rw&apos;@&apos;192.168.1.%&apos;
  PASSWORD EXPIRE INTERVAL 180 DAY
  FAILED_LOGIN_ATTEMPTS 5
  PASSWORD_LOCK_TIME 1;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;FAILED_LOGIN_ATTEMPTS&lt;/code&gt; + &lt;code&gt;PASSWORD_LOCK_TIME&lt;/code&gt; 是 8.0 起的好东西：连续猜错 5 次锁定 1 天，能有效顶住在线爆破。再配合上一篇说的&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把 3306 直接暴露公网&amp;lt;/span&amp;gt;，爆破面就基本关上了。&lt;/p&gt;
&lt;p&gt;:::warning
改密码、授权这类操作做完后，务必用新账号实际登录验证一次再收工。最常见的事故是：改了 &lt;code&gt;&apos;root&apos;@&apos;localhost&apos;&lt;/code&gt; 的密码，却发现应用连的是 &lt;code&gt;&apos;root&apos;@&apos;%&apos;&lt;/code&gt;，两个账号密码不一致，半夜发布时当场翻车。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;验证时要带上和应用完全相同的来源主机与连接方式&amp;lt;/span&amp;gt;（TCP 还是 socket 都会影响匹配到的账号）。
:::&lt;/p&gt;
&lt;h2&gt;一套可直接套用的账号分级方案&lt;/h2&gt;
&lt;p&gt;理论说完，给一套中小项目可直接落地的账号分级表。核心思想是按用途拆账号，任何一个密码泄露都只影响一个面：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;账号&lt;/th&gt;
&lt;th&gt;来源限制&lt;/th&gt;
&lt;th&gt;权限&lt;/th&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&apos;dba&apos;@&apos;运维机IP&apos;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;单 IP&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ALL PRIVILEGES ON *.*&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;人工运维、应急处理&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&apos;app_rw&apos;@&apos;应用网段&apos;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;网段&lt;/td&gt;
&lt;td&gt;业务库 &lt;code&gt;SELECT, INSERT, UPDATE, DELETE&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;应用运行时读写&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&apos;app_migrate&apos;@&apos;发布机IP&apos;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;单 IP&lt;/td&gt;
&lt;td&gt;业务库结构变更权限（&lt;code&gt;ALTER, CREATE, DROP, INDEX&lt;/code&gt; 等）&lt;/td&gt;
&lt;td&gt;发布流程执行 DDL&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&apos;report_ro&apos;@&apos;%&apos;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;任意（配 TLS）&lt;/td&gt;
&lt;td&gt;业务库 &lt;code&gt;SELECT&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;报表、BI 工具只读&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&apos;backup&apos;@&apos;localhost&apos;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;本机&lt;/td&gt;
&lt;td&gt;&lt;code&gt;SELECT, LOCK TABLES, RELOAD, REPLICATION CLIENT&lt;/code&gt; 等备份所需&lt;/td&gt;
&lt;td&gt;定时备份任务&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;备份账号单独建而不是借用 root，是很多团队容易偷懒的地方。备份脚本里的密码一旦泄露，攻击者拿到的应该只是「能读数据做备份」的权限，而不是整台实例的控制权。当然，能读全库数据本身已是高敏感权限，备份账号的密码同样要进密码管理器、定期轮换。&lt;/p&gt;
&lt;p&gt;密码轮换的正确姿势（8.0 支持双密码过渡，轮换不断业务）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 1. 先给账号追加新密码，旧密码暂时保留
ALTER USER &apos;app_rw&apos;@&apos;192.168.1.%&apos; IDENTIFIED BY &apos;NewPass_2026!&apos; RETAIN CURRENT PASSWORD;

-- 2. 把应用配置改成新密码并完成发布、验证
-- 3. 确认无误后去掉旧密码
ALTER USER &apos;app_rw&apos;@&apos;192.168.1.%&apos; DISCARD OLD PASSWORD;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改密码、改权限这类敏感操作，建议开启通用日志或审计插件留痕，出了问题能回答「谁在什么时候改了什么」。托管型审计可用 MySQL Enterprise Audit，开源环境可用 Percona / MariaDB 的 audit 插件思路替代，最低限度也要把运维操作集中在一台跳板机上执行并保留 shell 记录。&lt;/p&gt;
&lt;h2&gt;其它安全加固项&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;删掉匿名用户和 test 库&lt;/strong&gt;（系统包安装时 &lt;code&gt;mysql_secure_installation&lt;/code&gt; 已处理，Docker 官方镜像默认没有这些）：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;SELECT user, host FROM mysql.user WHERE user = &apos;&apos;;
SHOW DATABASES LIKE &apos;test%&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;root 只保留 localhost&lt;/strong&gt;：盘点时看到 &lt;code&gt;&apos;root&apos;@&apos;%&apos;&lt;/code&gt; 应立即删除，远程管理用普通 dba 账号加 SSH 隧道。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;启用连接加密&lt;/strong&gt;：跨机器连接时要求 TLS：&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;ALTER USER &apos;app_rw&apos;@&apos;192.168.1.%&apos; REQUIRE SSL;
&lt;/code&gt;&lt;/pre&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;审计习惯&lt;/strong&gt;：定期盘点账号，离职、项目下线随手 &lt;code&gt;DROP USER&lt;/code&gt;；长期不用的账号先锁定观察再删：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;ALTER USER &apos;report_ro&apos;@&apos;%&apos; ACCOUNT LOCK;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;角色（Role）：账号多了之后的组织方式&lt;/h2&gt;
&lt;p&gt;账号一多，逐个授权容易漏。MySQL 8.0 支持角色，把一组权限打包后授给多个账号：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE ROLE &apos;app_read&apos;, &apos;app_write&apos;;
GRANT SELECT ON appdb.* TO &apos;app_read&apos;;
GRANT INSERT, UPDATE, DELETE ON appdb.* TO &apos;app_write&apos;;

GRANT &apos;app_read&apos;, &apos;app_write&apos; TO &apos;app_rw&apos;@&apos;192.168.1.%&apos;;
SET DEFAULT ROLE ALL TO &apos;app_rw&apos;@&apos;192.168.1.%&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;注意给账号设置默认角色，否则角色授了也不会自动激活&amp;lt;/span&amp;gt;，这是用角色时最高频的坑。日常连库查数据、管理账号的完整命令清单，在 &lt;a href=&quot;/posts/mysql-commands-guide/&quot;&gt;MySQL 常用命令与操作实战&lt;/a&gt; 里接着讲。&lt;/p&gt;
&lt;h2&gt;定期盘点：把账号审计做成例行动作&lt;/h2&gt;
&lt;p&gt;安全不是一次配置完就结束的，账号会随着人员变动、项目上下线不断累积。建议每月跑一次盘点，重点看三件事：有没有不认识的账号、有没有过宽的来源范围、有没有长期没用过的账号。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 盘点一：所有账号及来源范围，重点盯 host 为 % 的
SELECT user, host, account_locked, password_last_changed
FROM mysql.user
ORDER BY host, user;

-- 盘点二：谁拥有全局权限（这类账号应该一只手数得过来）
SELECT user, host FROM mysql.user
WHERE Super_priv = &apos;Y&apos; OR Grant_priv = &apos;Y&apos;;

-- 盘点三：结合 Performance Schema 看账号最近是否还活跃
SELECT USER, HOST, EVENT_NAME, COUNT_STAR
FROM performance_schema.accounts
WHERE USER IS NOT NULL
ORDER BY COUNT_STAR DESC;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;盘点发现僵尸账号的处理顺序：先 &lt;code&gt;ACCOUNT LOCK&lt;/code&gt; 锁定观察一周，确认没有应用报错再 &lt;code&gt;DROP USER&lt;/code&gt; 删除，直接删容易在半夜把某个早已忘记的定时任务打挂。盘点结果建议留档（导出成文件存进运维文档），这样每次变更都有据可查，出了安全事件也能快速回答「这个账号是什么时候、为什么创建的」。&lt;/p&gt;
&lt;p&gt;另外一个常被忽视的点：应用配置文件、CI 变量、备份脚本里散落的数据库密码，同样属于账号体系的一部分。盘点时顺带清点这些密码的存放位置，能收进密码管理器或密钥服务的就不要明文躺在仓库里——Git 历史里的密码即使后来删掉，也要按已泄露处理、立即轮换。&lt;/p&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：授权后应用还是报 Access denied？&lt;/strong&gt;
按顺序查：连接实际匹配到哪个账号（&lt;code&gt;SELECT CURRENT_USER();&lt;/code&gt; 注意它和 &lt;code&gt;USER()&lt;/code&gt; 不同，前者是认证命中的账号）、密码是否对应那个账号、来源 IP 是否落在 host 范围内。九成问题出在同名不同 host 的账号上。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：忘记 root 密码怎么办？&lt;/strong&gt;
停实例后以跳过授权表方式启动再重置，Docker 环境则可以临时改启动参数。属于高危操作，重置后务必恢复正常启动并全面盘点账号。此流程同时也是 &lt;a href=&quot;/posts/database-backup-restore/&quot;&gt;数据库备份与恢复全攻略&lt;/a&gt; 里提醒要防的场景：能物理接触数据目录的人，本就能绕过密码，所以数据目录本身也要当秘密看管。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：&lt;code&gt;&apos;%&apos;&lt;/code&gt; 到底能不能用？&lt;/strong&gt;
内网隔离良好、前面有防火墙白名单时可以用，但必须配强密码和登录失败锁定。能写具体网段就别写 &lt;code&gt;%&lt;/code&gt;，这条没有例外。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：权限改完需要重启吗？&lt;/strong&gt;
不需要。&lt;code&gt;GRANT&lt;/code&gt;、&lt;code&gt;REVOKE&lt;/code&gt;、&lt;code&gt;ALTER USER&lt;/code&gt; 全部即时生效。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;账号是「用户名@来源主机」二元组，所有操作都要写全。&lt;/li&gt;
&lt;li&gt;建号与授权分两步，权限按最小够用给，&lt;code&gt;SUPER&lt;/code&gt;、&lt;code&gt;FILE&lt;/code&gt;、&lt;code&gt;GRANT OPTION&lt;/code&gt; 不进业务账号。&lt;/li&gt;
&lt;li&gt;密码过期、登录失败锁定、TLS、定期盘点账号，四件套把安全基线拉满。&lt;/li&gt;
&lt;li&gt;角色适合账号规模变大后的权限组织，记得设置默认角色。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>PostgreSQL 索引与查询优化入门</title><link>https://www.anexns.cloudns.org/posts/postgresql-index-optimization/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/postgresql-index-optimization/</guid><description>查询变慢多半不是 PostgreSQL 不行，而是缺索引或索引用错。这篇从 EXPLAIN 看懂执行计划讲起，带你掌握 B-tree、联合索引、部分索引与表达式索引的用法，并给出一套可落地的慢查询排查流程。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说清楚：慢查询到底慢在哪&lt;/h2&gt;
&lt;p&gt;上一篇用 &lt;a href=&quot;/posts/postgresql-psql-guide/&quot;&gt;psql 常用命令与操作实战&lt;/a&gt; 已经能熟练地连库、查表、跑 SQL 了。但真实项目里最常遇到的问题不是「不会写 SQL」，而是「SQL 写出来了，一跑就等半天」。数据量小的时候什么都快，表里攒到几十万、上百万行之后，没有索引的查询就会从毫秒级劣化到秒级。&lt;/p&gt;
&lt;p&gt;这篇的主线很明确：&lt;strong&gt;先学会看执行计划，再学会建对索引，最后形成一套排查慢查询的标准动作&lt;/strong&gt;。优化的前提是定位，没有定位的「优化」基本都是碰运气。如果你的 PostgreSQL 还没装好，先回 &lt;a href=&quot;/posts/postgresql-install-config/&quot;&gt;PostgreSQL 安装与初始配置&lt;/a&gt; 把环境跑起来。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;索引优化的第一原则：先测量，再动手。EXPLAIN ANALYZE 的输出就是你的测量仪。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;没有索引时，PostgreSQL 在做什么&lt;/h2&gt;
&lt;p&gt;准备一张测试表，灌入一百万行数据，后面的例子都基于它：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE TABLE orders (
    id          BIGSERIAL PRIMARY KEY,
    user_id     BIGINT NOT NULL,
    status      VARCHAR(20) NOT NULL,
    amount      NUMERIC(10, 2) NOT NULL,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

INSERT INTO orders (user_id, status, amount, created_at)
SELECT
    (random() * 10000)::bigint,
    (ARRAY[&apos;paid&apos;, &apos;pending&apos;, &apos;cancelled&apos;, &apos;refunded&apos;])[1 + (random() * 3)::int],
    (random() * 1000)::numeric(10, 2),
    now() - (random() * 365) * INTERVAL &apos;1 day&apos;
FROM generate_series(1, 1000000);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;查某个用户的订单：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 1234;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;输出大致是这样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Seq Scan on orders  (cost=0.00..20927.00 rows=100 width=40) (actual time=0.052..118.431 rows=98 loops=1)
  Filter: (user_id = 1234)
  Rows Removed by Filter: 999902
Planning Time: 0.083 ms
Execution Time: 118.512 ms
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;关键词是 &lt;code&gt;Seq Scan&lt;/code&gt;（顺序扫描）：PostgreSQL 把一百万行挨个读了一遍，只为找出其中一百行。表越大，这个数字越难看。这就是索引要解决的问题。&lt;/p&gt;
&lt;h2&gt;看懂 EXPLAIN 输出的几个关键点&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;EXPLAIN&lt;/code&gt; 只给预估计划，&lt;code&gt;EXPLAIN ANALYZE&lt;/code&gt; 会真正执行并给出实际耗时，日常排查用后者。看输出时抓四个重点：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;怎么看&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Scan 类型&lt;/td&gt;
&lt;td&gt;Seq Scan / Index Scan / Index Only Scan / Bitmap Heap Scan&lt;/td&gt;
&lt;td&gt;大表出现 Seq Scan 且过滤后行数很少，就是缺索引信号&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;cost&lt;/td&gt;
&lt;td&gt;优化器估算的相对成本，格式为 &lt;code&gt;启动成本..总成本&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只作相对比较，不等于毫秒&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;rows&lt;/td&gt;
&lt;td&gt;预估返回行数&lt;/td&gt;
&lt;td&gt;与 actual rows 差太多，说明统计信息过期&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;actual time&lt;/td&gt;
&lt;td&gt;实际执行时间，格式为 &lt;code&gt;首行时间..全部行时间&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;这才是真实耗时&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;还有两个高频节点要认识：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;Index Only Scan&lt;/code&gt;：需要的列全在索引里，连表都不用回，是最快的常见形态。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;Bitmap Heap Scan&lt;/code&gt;：命中行数中等时，PostgreSQL 先用索引收集行位置，再批量回表取数据，比逐行 Index Scan 更划算。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;如果预估 rows 和实际 rows 差了几个数量级，先执行一次统计信息更新再判断：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ANALYZE orders;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;B-tree 索引：默认且万能的选择&lt;/h2&gt;
&lt;p&gt;给 &lt;code&gt;user_id&lt;/code&gt; 建索引再查一次：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE INDEX idx_orders_user_id ON orders (user_id);

EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 1234;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;计划会变成 &lt;code&gt;Index Scan&lt;/code&gt; 或 &lt;code&gt;Bitmap Heap Scan&lt;/code&gt;，耗时通常直接掉到 1 毫秒以内。&lt;code&gt;CREATE INDEX&lt;/code&gt; 默认建的就是 B-tree 索引，它支持等值、范围、排序和前缀匹配，覆盖 95% 的日常场景：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 等值与范围都走索引
SELECT * FROM orders WHERE user_id = 1234 AND created_at &amp;gt;= &apos;2026-01-01&apos;;

-- 排序也能用上索引（索引本身就是有序的）
SELECT * FROM orders WHERE user_id = 1234 ORDER BY id DESC LIMIT 20;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;其他索引类型了解即可，按需选用：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;索引类型&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;th&gt;典型语法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;B-tree&lt;/td&gt;
&lt;td&gt;等值、范围、排序，默认选择&lt;/td&gt;
&lt;td&gt;&lt;code&gt;CREATE INDEX ... ON t (col)&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Hash&lt;/td&gt;
&lt;td&gt;仅等值查询，优势不明显，极少用&lt;/td&gt;
&lt;td&gt;&lt;code&gt;USING hash (col)&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GIN&lt;/td&gt;
&lt;td&gt;JSONB、数组、全文检索的包含查询&lt;/td&gt;
&lt;td&gt;&lt;code&gt;USING gin (col)&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GiST&lt;/td&gt;
&lt;td&gt;几何、范围类型、相似度搜索&lt;/td&gt;
&lt;td&gt;&lt;code&gt;USING gist (col)&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;BRIN&lt;/td&gt;
&lt;td&gt;超大表且物理顺序与列值强相关（如按时间追加）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;USING brin (col)&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;联合索引：列的顺序比数量重要&lt;/h2&gt;
&lt;p&gt;业务查询很少只按一列过滤。给 &lt;code&gt;(user_id, created_at)&lt;/code&gt; 建联合索引：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE INDEX idx_orders_user_created ON orders (user_id, created_at DESC);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;联合索引遵循&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;最左前缀原则&amp;lt;/span&amp;gt;：查询条件必须从最左列开始连续使用，索引才完全生效。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 用得上：先等值定位 user_id，再按 created_at 范围扫
SELECT * FROM orders WHERE user_id = 1234 AND created_at &amp;gt;= &apos;2026-06-01&apos;;

-- 用得上：只有最左列
SELECT * FROM orders WHERE user_id = 1234;

-- 用不上这个索引：跳过了最左列
SELECT * FROM orders WHERE created_at &amp;gt;= &apos;2026-06-01&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;经验法则：&lt;strong&gt;等值列在前、范围列在后、排序列尽量贴合&lt;/strong&gt;。把选择性最高（ distinct 值最多）的列放前面通常也更划算。&lt;/p&gt;
&lt;h2&gt;进阶索引：部分索引、表达式索引与覆盖索引&lt;/h2&gt;
&lt;h3&gt;部分索引：只给需要的数据建索引&lt;/h3&gt;
&lt;p&gt;如果业务上 90% 的查询只关心未取消的订单，没必要把全部行都塞进索引：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE INDEX idx_orders_active_user
ON orders (user_id)
WHERE status &amp;lt;&amp;gt; &apos;cancelled&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;索引体积更小、维护成本更低。注意查询条件必须能被优化器证明蕴含索引的 WHERE 条件，否则用不上。&lt;/p&gt;
&lt;h3&gt;表达式索引：函数查询也能走索引&lt;/h3&gt;
&lt;p&gt;按邮箱小写匹配是经典翻车点：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 这样写，email 上的普通索引用不上
SELECT * FROM users WHERE lower(email) = &apos;test@example.com&apos;;

-- 建表达式索引后才走索引
CREATE INDEX idx_users_lower_email ON users (lower(email));
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;覆盖索引：用 INCLUDE 免回表&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;CREATE INDEX idx_orders_user_cover
ON orders (user_id) INCLUDE (status, amount);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;查询只需要 &lt;code&gt;user_id&lt;/code&gt;、&lt;code&gt;status&lt;/code&gt;、&lt;code&gt;amount&lt;/code&gt; 时就是 Index Only Scan，省掉回表开销。代价是索引变胖，写入时维护成本上升，高频更新的列不要往里塞。&lt;/p&gt;
&lt;p&gt;:::warning
索引不是越多越好。每多一个索引，INSERT 和 UPDATE 都要多维护一份数据结构，写入吞吐会下降。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;给低选择性列（如只有两三个取值的 status）单独建索引通常收益很低&amp;lt;/span&amp;gt;，优化器甚至会直接放弃使用它。先确认查询真的需要，再建。
:::&lt;/p&gt;
&lt;h2&gt;慢查询排查的标准流程&lt;/h2&gt;
&lt;p&gt;把上面的知识串成一套可重复执行的动作：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;抓到慢 SQL&lt;/strong&gt;：开启慢查询日志，或从 &lt;code&gt;pg_stat_statements&lt;/code&gt; 扩展里按总耗时排序找元凶。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;复现并看计划&lt;/strong&gt;：&lt;code&gt;EXPLAIN (ANALYZE, BUFFERS)&lt;/code&gt; 看实际耗时和读了多少数据块。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;对症下药&lt;/strong&gt;：Seq Scan 且过滤性强 → 补索引；rows 预估严重偏差 → &lt;code&gt;ANALYZE&lt;/code&gt;；索引建了不用 → 检查类型转换、函数包裹列、隐式拼接等问题。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;验证效果&lt;/strong&gt;：改完再跑一次 EXPLAIN ANALYZE，前后数字留档对比。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;code&gt;pg_stat_statements&lt;/code&gt; 需要在 &lt;code&gt;postgresql.conf&lt;/code&gt; 里预加载，配置方法在 &lt;a href=&quot;/posts/postgresql-install-config/&quot;&gt;PostgreSQL 安装与初始配置&lt;/a&gt; 里有说明。开启后常用的一条排查 SQL：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SELECT query, calls, total_exec_time, mean_exec_time, rows
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 10;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;更系统的监控与告警思路，放在系列最后一篇 &lt;a href=&quot;/posts/database-monitoring-troubleshooting/&quot;&gt;数据库性能监控与常见故障排障&lt;/a&gt; 里统一讲。&lt;/p&gt;
&lt;h2&gt;索引的日常维护&lt;/h2&gt;
&lt;p&gt;索引会随着大量更新和删除产生膨胀，查询逐渐变慢。常用维护动作：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 查看每个索引的大小，揪出异常膨胀的
SELECT indexrelname, pg_size_pretty(pg_relation_size(indexrelid))
FROM pg_stat_user_indexes
ORDER BY pg_relation_size(indexrelid) DESC;

-- 在线重建索引，不锁表写操作（会短暂占双倍空间）
REINDEX INDEX CONCURRENTLY idx_orders_user_id;

-- 查看从未被使用过的索引，考虑删除以减轻写入负担
SELECT relname, indexrelname, idx_scan
FROM pg_stat_user_indexes
WHERE idx_scan = 0;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;pg_stat_user_indexes&lt;/code&gt; 的统计会随服务重启清零，判断「从未使用」前先确认统计周期足够长，别把低频但关键的索引误删了。&lt;/p&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：索引建了，为什么查询还是 Seq Scan？&lt;/strong&gt;
返回行数占全表比例较高时（比如超过 10%–20%），优化器认为顺序扫描更便宜，这是正常决策。另外检查统计信息是否过期、查询里是否有对列做函数运算或类型转换。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：主键还需要单独建索引吗？&lt;/strong&gt;
不需要。主键会自动创建唯一 B-tree 索引。但要注意：联合主键同样遵循最左前缀，单查第二列用不上。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：&lt;code&gt;CREATE INDEX&lt;/code&gt; 会锁表吗？&lt;/strong&gt;
普通 &lt;code&gt;CREATE INDEX&lt;/code&gt; 会阻塞写入。生产环境大表建索引用 &lt;code&gt;CREATE INDEX CONCURRENTLY&lt;/code&gt;，代价是更慢且不能在事务块里执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE INDEX CONCURRENTLY idx_orders_status ON orders (status);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;Q：LIKE &apos;%keyword%&apos; 能走索引吗？&lt;/strong&gt;
普通 B-tree 不行（前缀不确定）。全文检索场景应使用 GIN 索引配合 &lt;code&gt;pg_trgm&lt;/code&gt; 扩展或 &lt;code&gt;tsvector&lt;/code&gt;，不要硬套 B-tree。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;慢查询先看 &lt;code&gt;EXPLAIN ANALYZE&lt;/code&gt;，Seq Scan 加高过滤性是大表缺索引的典型信号。&lt;/li&gt;
&lt;li&gt;B-tree 是默认选择；联合索引记住&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;等值在前、范围在后、最左前缀&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;li&gt;部分索引、表达式索引、覆盖索引分别解决「只查一部分数据」「函数查询」「免回表」三类问题。&lt;/li&gt;
&lt;li&gt;索引有写入代价，宁可少而准，不要一股脑全建；定期清理未使用索引、重建膨胀索引。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;至此 PostgreSQL 部分告一段落，下一篇进入 MySQL：&lt;a href=&quot;/posts/mysql-install-config/&quot;&gt;MySQL 安装与初始配置&lt;/a&gt;。&lt;/p&gt;
</content:encoded></item><item><title>PostgreSQL 安装与初始配置</title><link>https://www.anexns.cloudns.org/posts/postgresql-install-config/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/postgresql-install-config/</guid><description>PostgreSQL 17 两种装法全解：Docker 快速部署与 Debian/Ubuntu 系统包安装，再把监听地址、pg_hba.conf 访问控制、内存与连接数等初始配置一次调对，并完成首次连接验证。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;这一篇解决什么&lt;/h2&gt;
&lt;p&gt;选型（&lt;a href=&quot;/posts/database-choosing-guide/&quot;&gt;《数据库怎么选》&lt;/a&gt;）和练功房（&lt;a href=&quot;/posts/database-docker-quickstart/&quot;&gt;《用 Docker 快速搭建三大数据库》&lt;/a&gt;）都走完了，这一篇正式进入 PostgreSQL：把它以「能长期用」的标准装好——不是能跑就行，而是监听范围、访问控制、基础参数都配置到位。&lt;/p&gt;
&lt;p&gt;两种装法都讲：&lt;strong&gt;Docker 装法&lt;/strong&gt;胜在干净隔离、版本随意切换，适合开发和中小部署；&lt;strong&gt;系统包装法&lt;/strong&gt;胜在和系统服务体系融合、运维工具齐全，适合长期跑在 VPS 上的正式服务。原理部分（配置文件、认证）两边相通，学会一边另一边自然懂。&lt;/p&gt;
&lt;h2&gt;方式一：Docker 安装&lt;/h2&gt;
&lt;p&gt;单跑 PostgreSQL 的精简 Compose（练功房里已有全套的可以跳过）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  postgres:
    image: postgres:17
    container_name: postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: change_me_strong_password
      POSTGRES_DB: appdb
      TZ: Asia/Shanghai
    ports:
      - &quot;127.0.0.1:5432:5432&quot;
    volumes:
      - pg_data:/var/lib/postgresql/data
      - ./postgresql.conf:/etc/postgresql/postgresql.conf
    command: postgres -c config_file=/etc/postgresql/postgresql.conf

volumes:
  pg_data:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;官方镜像的约定要记牢：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;数据目录固定 &lt;code&gt;/var/lib/postgresql/data&lt;/code&gt;，必须挂卷，否则删容器即丢数据。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;POSTGRES_PASSWORD&lt;/code&gt; 等环境变量&lt;strong&gt;只在数据目录为空时生效&lt;/strong&gt;，首次初始化后改密码要进库里用 SQL 改（下一篇 &lt;a href=&quot;/posts/postgresql-users-permissions/&quot;&gt;《PostgreSQL 用户、角色与权限管理》&lt;/a&gt; 专门讲）。&lt;/li&gt;
&lt;li&gt;想自定义配置，就把配置文件挂进去并用 &lt;code&gt;command&lt;/code&gt; 指定，这是 Docker 下调参的标准姿势。&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker exec -it postgres psql -U postgres -d appdb -c &quot;SELECT version();&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;方式二：Debian / Ubuntu 系统包安装&lt;/h2&gt;
&lt;p&gt;用 PostgreSQL 官方 APT 源装 17 版（系统自带源版本往往偏旧）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo apt install -y wget gnupg lsb-release
sudo sh -c &apos;echo &quot;deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main&quot; &amp;gt; /etc/apt/sources.list.d/pgdg.list&apos;
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/postgresql.gpg
sudo apt update
sudo apt install -y postgresql-17
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;安装后服务由 systemd 管理，关键路径：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;路径&lt;/th&gt;
&lt;th&gt;内容&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/etc/postgresql/17/main/postgresql.conf&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;主配置文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/etc/postgresql/17/main/pg_hba.conf&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;客户端认证（谁能连、用什么方式验）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/var/lib/postgresql/17/main/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;数据目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/var/log/postgresql/postgresql-17-main.log&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;日志&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;pre&gt;&lt;code&gt;sudo systemctl status postgresql
sudo -u postgres psql -c &quot;SELECT version();&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;系统包默认建了一个系统用户 &lt;code&gt;postgres&lt;/code&gt; 和同名超级用户，&lt;code&gt;sudo -u postgres psql&lt;/code&gt; 是本机免密进库的入口——它能免密是因为 pg_hba.conf 里本地连接默认走 peer 认证（系统用户和数据库用户同名即放行）。&lt;/p&gt;
&lt;h2&gt;核心配置一：监听与连接&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;postgresql.conf&lt;/code&gt; 里最先要动的几个参数：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;listen_addresses = &apos;localhost&apos;   # 只监听本机；要内网访问改成 &apos;*&apos; 或具体网卡 IP
port = 5432
max_connections = 100            # 默认 100，按机器配置和业务量调整
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改完 &lt;code&gt;listen_addresses&lt;/code&gt; 必须&lt;strong&gt;重启&lt;/strong&gt;服务才生效（&lt;code&gt;sudo systemctl restart postgresql&lt;/code&gt; 或容器重建）；多数其他参数用 reload 即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo -u postgres psql -c &quot;SELECT pg_reload_conf();&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
把 &lt;code&gt;listen_addresses&lt;/code&gt; 改成 &lt;code&gt;&apos;*&apos;&lt;/code&gt; 之前，先想清楚 pg_hba.conf 是否已经收紧、防火墙是否到位。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;监听全网卡 + 弱口令 + pg_hba 放行全网，是数据库被扫被拖库的经典组合&lt;/strong&gt;&amp;lt;/span&amp;gt;。远程管理优先用 SSH 隧道：&lt;code&gt;ssh -L 5432:localhost:5432 user@服务器&lt;/code&gt;，既加密又不用暴露端口。
:::&lt;/p&gt;
&lt;h2&gt;核心配置二：pg_hba.conf 访问控制&lt;/h2&gt;
&lt;p&gt;pg_hba.conf 是 PostgreSQL 的门卫，规则&lt;strong&gt;从上往下匹配，命中第一条就停&lt;/strong&gt;。每行五要素：连接类型、数据库、用户、来源地址、认证方式。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 类型   数据库   用户    来源地址          认证方式
local    all      all                         peer
host     appdb    appuser 127.0.0.1/32       scram-sha-256
host     appdb    appuser 192.168.1.0/24     scram-sha-256
host     all      all     0.0.0.0/0          reject
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;认证方式怎么选：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方式&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;建议&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;peer&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;系统用户名与数据库用户名一致即放行&lt;/td&gt;
&lt;td&gt;仅限 &lt;code&gt;local&lt;/code&gt; 本机连接&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;scram-sha-256&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;密码认证（当前推荐）&lt;/td&gt;
&lt;td&gt;网络连接一律用它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;md5&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;老版密码认证&lt;/td&gt;
&lt;td&gt;能不用就不用，逐步迁移到 scram&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;trust&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;无条件信任，不验密码&lt;/td&gt;
&lt;td&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;只允许出现在本机开发环境，生产用等于裸奔&lt;/strong&gt;&amp;lt;/span&amp;gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;改完 pg_hba.conf 执行 reload 即可生效，不用重启。验证当前生效的规则：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SELECT * FROM pg_hba_file_rules;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;核心配置三：性能起步参数&lt;/h2&gt;
&lt;p&gt;默认配置是为「能在任何破机器上跑起来」定的，正式使用至少要按内存调这几个（以 4 GB 内存的机器为例）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;shared_buffers = 1GB              # 总内存的约 25%，数据缓存
work_mem = 16MB                   # 单个排序/哈希操作可用内存，按连接数保守给
maintenance_work_mem = 256MB      # 建索引、VACUUM 等维护操作用
effective_cache_size = 3GB        # 告诉规划器「系统总共能缓存多少」，约总内存 75%
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里的关键认知是：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;参数调优没有通用最优解，只有与你的内存、连接数、查询形态匹配的配置&lt;/strong&gt;&amp;lt;/span&amp;gt;。起步先按上面这组比例给，之后用 &lt;a href=&quot;/posts/database-monitoring-troubleshooting/&quot;&gt;《数据库性能监控与常见故障排障》&lt;/a&gt; 里的方法看实际瓶颈再动。索引和查询层面的优化则是下一篇之后的内容，见《PostgreSQL 索引与查询优化入门》。&lt;/p&gt;
&lt;h2&gt;首次上手动作清单&lt;/h2&gt;
&lt;p&gt;装完建议按顺序做完这五件事，再交付使用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 1. 给超级用户 postgres 设密码（默认无密码，靠 peer 认证进）
ALTER USER postgres WITH PASSWORD &apos;strong_password_here&apos;;

-- 2. 建业务库和业务用户（不要拿超级用户跑业务，下一篇细讲）
CREATE DATABASE appdb;
CREATE USER appuser WITH PASSWORD &apos;another_strong_password&apos;;
GRANT ALL PRIVILEGES ON DATABASE appdb TO appuser;
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;# 3. 确认时区与编码
sudo -u postgres psql -c &quot;SHOW timezone;&quot; -c &quot;SHOW server_encoding;&quot;

# 4. 从目标机器实测一次远程/本机连接
psql &quot;host=127.0.0.1 port=5432 dbname=appdb user=appuser&quot; -c &quot;SELECT 1;&quot;

# 5. 确认服务开机自启
sudo systemctl enable postgresql
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：&lt;code&gt;psql: error: connection to server ... FATAL: password authentication failed&lt;/code&gt;？&lt;/strong&gt;
A：密码错、或 pg_hba 里该来源走的认证方式和你想的不一样。先确认命中的是哪条规则（&lt;code&gt;pg_hba_file_rules&lt;/code&gt;），再确认密码——注意超级用户初始无密码时，网络连接用密码登录必然失败，先按上文设密码。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：远程连不上，但本机能连？&lt;/strong&gt;
A：按顺序查四层：&lt;code&gt;listen_addresses&lt;/code&gt; 是否包含目标网卡；pg_hba 是否放行来源 IP；服务器防火墙 / 云厂商安全组是否放行 5432；中间网络是否可达（&lt;code&gt;telnet 目标 5432&lt;/code&gt; 或 &lt;code&gt;nc -vz 目标 5432&lt;/code&gt;）。四层里必有一层没过。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：改了 postgresql.conf 重启没生效？&lt;/strong&gt;
A：先确认改的是不是正在用的那份配置：&lt;code&gt;SHOW config_file;&lt;/code&gt; 看路径，Docker 场景还要确认挂载和 &lt;code&gt;config_file&lt;/code&gt; 参数对得上。再确认参数是否需要重启才生效：&lt;code&gt;SELECT name, pending_restart FROM pg_settings WHERE pending_restart;&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：端口 5432 被占怎么办？&lt;/strong&gt;
A：&lt;code&gt;sudo ss -tlnp | grep 5432&lt;/code&gt; 查是谁占的。是另一个 PostgreSQL 实例就换端口跑（改 &lt;code&gt;port&lt;/code&gt; 并同步客户端），是无关进程就处理掉它。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;安装只是把软件放进机器，真正决定它能不能长期稳定服务的，是监听范围、pg_hba 门卫规则和按内存调过的起步参数这三件事。下一篇把用户、角色与权限这套体系讲透——装得再对，权限给错了照样出事。&lt;/p&gt;
</content:encoded></item><item><title>psql 常用命令与操作实战</title><link>https://www.anexns.cloudns.org/posts/postgresql-psql-guide/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/postgresql-psql-guide/</guid><description>psql 是 PostgreSQL 的官方命令行客户端，也是排查问题时最趁手的工具。这篇系统梳理连接方式、反斜杠元命令、格式化输出、执行脚本与导入导出，把日常操作一次练全。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;为什么要专门学 psql&lt;/h2&gt;
&lt;p&gt;图形客户端（pgAdmin、DBeaver）上手是快，但真到了服务器上排查问题，能依靠的往往只有 SSH 里一个 psql：它随 PostgreSQL 一起安装、永远可用、速度最快，还能写进脚本自动化。前几篇里我们已经零散用过它——《PostgreSQL 安装与初始配置》里连库验证、&lt;a href=&quot;/posts/postgresql-users-permissions/&quot;&gt;《PostgreSQL 用户、角色与权限管理》&lt;/a&gt; 里查角色——这一篇把它系统地补齐。&lt;/p&gt;
&lt;p&gt;psql 的能力分两半：&lt;strong&gt;SQL 语句&lt;/strong&gt;本身（上一篇 &lt;a href=&quot;/posts/sql-basics-crud/&quot;&gt;《SQL 基础速成》&lt;/a&gt; 已练过）和&lt;strong&gt;元命令&lt;/strong&gt;（以反斜杠 &lt;code&gt;\&lt;/code&gt; 开头的 psql 专属命令，不发给服务器、在客户端本地执行）。元命令才是 psql 的精华所在。&lt;/p&gt;
&lt;h2&gt;连接：四种常用姿势&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;# 1. 参数式：主机、端口、用户、库分开写
psql -h 127.0.0.1 -p 5432 -U appuser -d appdb

# 2. 连接串式：一条 URI 搞定，写脚本时最方便
psql &quot;postgresql://appuser:password@127.0.0.1:5432/appdb&quot;

# 3. Docker 里直接进
docker exec -it lab-postgres psql -U appuser -d appdb

# 4. 本机系统包安装版，借 peer 认证以 postgres 身份进
sudo -u postgres psql
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;连接相关的实用细节：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;-W&lt;/code&gt; 强制提示输入密码；密码不想出现在命令历史里，用环境变量 &lt;code&gt;PGPASSWORD=xxx psql ...&lt;/code&gt;，或在 &lt;code&gt;~/.pgpass&lt;/code&gt; 文件里存（权限必须 600），格式为 &lt;code&gt;主机:端口:库:用户:密码&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;连接串里密码含特殊字符（&lt;code&gt;@&lt;/code&gt;、&lt;code&gt;/&lt;/code&gt; 等）要做 URL 编码，否则解析会错位。长期用的连接建议都收进 &lt;code&gt;.pgpass&lt;/code&gt;，命令里只留主机和用户。&lt;/li&gt;
&lt;li&gt;进错库不用退出重连，psql 里直接 &lt;code&gt;\c appdb&lt;/code&gt; 切换数据库，&lt;code&gt;\c appdb alice&lt;/code&gt; 还能顺带换用户。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;元命令速查：先记这十五个&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;元命令&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\l&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列出全部数据库&lt;/td&gt;
&lt;td&gt;加 &lt;code&gt;+&lt;/code&gt; 显示大小等详情：&lt;code&gt;\l+&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\c 库名&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;切换数据库&lt;/td&gt;
&lt;td&gt;相当于重新连接&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\dt&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列出当前模式的表&lt;/td&gt;
&lt;td&gt;&lt;code&gt;\dt *.*&lt;/code&gt; 看全部模式；&lt;code&gt;\dt+&lt;/code&gt; 带大小&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\d 表名&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;查看表结构&lt;/td&gt;
&lt;td&gt;字段、类型、索引、外键一屏看全，高频第一名&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\di&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列出索引&lt;/td&gt;
&lt;td&gt;&lt;code&gt;\di+&lt;/code&gt; 带大小&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\dv&lt;/code&gt; / &lt;code&gt;\df&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列出视图 / 函数&lt;/td&gt;
&lt;td&gt;排查视图和函数时用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\du&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列出角色及属性&lt;/td&gt;
&lt;td&gt;查权限体系的入口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\z 表名&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;查看对象的权限授予情况&lt;/td&gt;
&lt;td&gt;核对 GRANT 结果&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\dn&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;列出模式&lt;/td&gt;
&lt;td&gt;多模式项目必备&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\x&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;切换扩展显示&lt;/td&gt;
&lt;td&gt;宽表竖排展示，开/关切换&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\timing&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;开关语句耗时显示&lt;/td&gt;
&lt;td&gt;调 SQL 时常开&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\e&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;把当前语句调入编辑器&lt;/td&gt;
&lt;td&gt;长 SQL 写错了不用重敲&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\i 文件.sql&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;执行脚本文件&lt;/td&gt;
&lt;td&gt;在 psql 内部跑脚本&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;\q&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;退出 psql&lt;/td&gt;
&lt;td&gt;也可以 Ctrl+D&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几乎所有 &lt;code&gt;\d&lt;/code&gt; 系列都支持 &lt;code&gt;+&lt;/code&gt; 后缀看详情、支持通配符过滤，比如 &lt;code&gt;\dt user*&lt;/code&gt; 只看 user 开头的表。&lt;/p&gt;
&lt;h2&gt;看结构与看数据：日常两板斧&lt;/h2&gt;
&lt;p&gt;排查问题时最高频的动作是「这张表长什么样、里面有什么」：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;\d users              -- 表结构：字段、索引、约束
SELECT * FROM users ORDER BY id DESC LIMIT 5;   -- 最近 5 行
SELECT count(*) FROM users;                     -- 总行数

-- 看表和索引占多大空间
SELECT pg_size_pretty(pg_total_relation_size(&apos;users&apos;)) AS total,
       pg_size_pretty(pg_relation_size(&apos;users&apos;)) AS table_only,
       pg_size_pretty(pg_indexes_size(&apos;users&apos;)) AS indexes;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;宽表查询时结果横向溢出看不清，打开扩展显示：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;\x on
SELECT * FROM users WHERE id = 1;
-- 结果会变成一列一行竖排：id │ 1 / username │ zhangsan / ...
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再加一个救急技巧：查询结果太多刷屏时，用 &lt;code&gt;\pset pager off&lt;/code&gt; 关掉分页器，或者干脆在 SQL 里老老实实加 &lt;code&gt;LIMIT&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;输出控制：把结果变成想要的样子&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;\timing on                       -- 每条语句后显示耗时（毫秒）
\pset null &apos;(null)&apos;              -- NULL 显示成 (null)，和空字符串区分开
\a                               -- 切换对齐/非对齐输出（导出数据时用非对齐）
\o /tmp/out.txt                  -- 之后的结果都写进文件，直到再次 \o 关闭
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;执行脚本与导入导出&lt;/h2&gt;
&lt;p&gt;批量操作靠脚本，不要一行行手敲：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 在 shell 里直接执行 SQL 文件，出错即停（ON_ERROR_STOP 很重要）
psql -U appuser -d appdb -v ON_ERROR_STOP=1 -f init.sql

# 只跑一条语句拿结果，常用于脚本里取值
psql -U appuser -d appdb -t -c &quot;SELECT count(*) FROM users;&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;数据导出导入用 &lt;code&gt;\copy&lt;/code&gt;（客户端侧执行，普通用户权限即可；服务端的 &lt;code&gt;COPY&lt;/code&gt; 需要超级用户或相应权限，日常优先 &lt;code&gt;\copy&lt;/code&gt;）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 导出成 CSV
\copy users TO &apos;/tmp/users.csv&apos; WITH (FORMAT csv, HEADER true)

-- 从 CSV 导入（列顺序要与表一致，或显式写列名）
\copy users (username, email, age) FROM &apos;/tmp/users.csv&apos; WITH (FORMAT csv, HEADER true)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
导入前先想清楚目标表里已有数据怎么办：&lt;code&gt;\copy&lt;/code&gt; 是纯追加，遇到唯一约束冲突会整批失败回滚。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;不要在没确认的情况下对生产表做全量覆盖式导入&lt;/strong&gt;&amp;lt;/span&amp;gt;；稳妥做法是先导入临时表、校验无误后再合并进正式表。大批量整库迁移则用 &lt;a href=&quot;/posts/database-backup-restore/&quot;&gt;《数据库备份与恢复全攻略》&lt;/a&gt; 里的 pg_dump 路线。
:::&lt;/p&gt;
&lt;h2&gt;实用进阶：这几个技巧最提效&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. &lt;code&gt;\gset&lt;/code&gt; 把查询结果存成变量&lt;/strong&gt;，后续语句直接引用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SELECT count(*) AS total FROM users \gset
SELECT :total AS user_total;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;2. 变量替换&lt;/strong&gt;：&lt;code&gt;psql -v uid=1&lt;/code&gt; 传入变量，SQL 里用 &lt;code&gt;:uid&lt;/code&gt; 引用，脚本立刻可复用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;psql -U appuser -d appdb -v uid=1 -c &quot;SELECT * FROM users WHERE id = :uid;&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;3. &lt;code&gt;\watch&lt;/code&gt; 定时重复执行&lt;/strong&gt;，盯实时状态不用手刷：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 每 2 秒刷新一次当前连接数
SELECT count(*) FROM pg_stat_activity; \watch 2
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;4. 事务里干活防手滑&lt;/strong&gt;：重要修改先 &lt;code&gt;BEGIN;&lt;/code&gt;，查验无误再 &lt;code&gt;COMMIT;&lt;/code&gt;，不对就 &lt;code&gt;ROLLBACK;&lt;/code&gt;——和《SQL 基础速成》里讲的习惯一脉相承。&lt;/p&gt;
&lt;p&gt;记住 psql 的定位：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;它是你和 PostgreSQL 之间最短的那条路，元命令负责「看」，SQL 负责「做」，两者合起来就是完整的运维现场&lt;/strong&gt;&amp;lt;/span&amp;gt;。后面 &lt;a href=&quot;/posts/postgresql-index-optimization/&quot;&gt;《PostgreSQL 索引与查询优化入门》&lt;/a&gt; 里的 &lt;code&gt;EXPLAIN&lt;/code&gt; 分析，也全是在 psql 里完成的。&lt;/p&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：SQL 写了一半发现错了，怎么取消当前输入？&lt;/strong&gt;
A：按 Ctrl+C 取消当前语句回到提示符；或者新起一行输入 &lt;code&gt;\r&lt;/code&gt; 清空查询缓冲区重新来。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：粘贴大段 SQL 进去，格式全乱、还提前执行了？&lt;/strong&gt;
A：多半是粘贴内容里混了换行触发的自动执行。用 &lt;code&gt;\e&lt;/code&gt; 进编辑器粘贴整理，或者把 SQL 存成文件用 &lt;code&gt;-f&lt;/code&gt; 执行，最稳。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：中文显示乱码？&lt;/strong&gt;
A：查客户端编码：&lt;code&gt;\encoding&lt;/code&gt; 看当前设置，&lt;code&gt;SET client_encoding TO &apos;UTF8&apos;;&lt;/code&gt; 临时修正；根源上确保数据库编码是 UTF8、终端也是 UTF8。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：连接时报 &lt;code&gt;FATAL: no pg_hba.conf entry for host&lt;/code&gt;？&lt;/strong&gt;
A：这是服务器门卫拒绝：你的来源 IP / 用户 / 库组合在 pg_hba.conf 里没有放行规则。回《PostgreSQL 安装与初始配置》一篇补规则并 reload，不要为了图省事把认证改成 trust。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：psql 里怎么看一条慢 SQL 卡在哪？&lt;/strong&gt;
A：先开 &lt;code&gt;\timing&lt;/code&gt;，再用 &lt;code&gt;EXPLAIN ANALYZE 你的SQL;&lt;/code&gt; 看执行计划和实际耗时——这是下一篇索引优化的正题，这里先把工具握在手里。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇把 psql 从「能连上」练到「能干活」：连接四姿势、十五个高频元命令、结构与数据查看、输出控制、脚本与 &lt;code&gt;\copy&lt;/code&gt; 导入导出，再加变量与 &lt;code&gt;\watch&lt;/code&gt; 等提效技巧。PostgreSQL 部分还剩最后一块拼图——索引与查询优化，下一篇收官。&lt;/p&gt;
</content:encoded></item><item><title>PostgreSQL 用户、角色与权限管理</title><link>https://www.anexns.cloudns.org/posts/postgresql-users-permissions/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/postgresql-users-permissions/</guid><description>PostgreSQL 里没有独立的「用户」，只有角色。这篇讲清角色与用户的关系、登录与超级用户属性、库/模式/表三级权限的授予与回收，以及按最小权限原则给应用、只读、运维三类账号落地的完整方案。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先纠正一个概念：PostgreSQL 只有角色&lt;/h2&gt;
&lt;p&gt;上一篇 &lt;a href=&quot;/posts/postgresql-install-config/&quot;&gt;《PostgreSQL 安装与初始配置》&lt;/a&gt; 里我们建过 &lt;code&gt;appuser&lt;/code&gt;，用的命令是 &lt;code&gt;CREATE USER&lt;/code&gt;。但在 PostgreSQL 的世界里，根本不存在与角色分开的「用户」概念：&lt;strong&gt;用户就是带 &lt;code&gt;LOGIN&lt;/code&gt; 属性的角色&lt;/strong&gt;。&lt;code&gt;CREATE USER&lt;/code&gt; 只是 &lt;code&gt;CREATE ROLE ... WITH LOGIN&lt;/code&gt; 的语法糖。理解这一点，后面的权限继承、组角色才不会绕晕。&lt;/p&gt;
&lt;p&gt;为什么这套设计值得认真学？因为权限给错是数据库事故的一大来源：应用拿着超级用户跑，被 SQL 注入后等于把整个数据库双手奉上；离职同事的账号没回收，成了永久后门。所以这一篇的核心原则只有一句：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;每个使用者（人或程序）一个独立账号，只给它完成工作所必需的最小权限&lt;/strong&gt;&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h2&gt;角色的属性&lt;/h2&gt;
&lt;p&gt;创建角色时能控制的属性，决定了这个账号的「权力边界」：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE ROLE appuser WITH
    LOGIN               -- 允许登录（没有它就只是个权限容器，即&quot;组&quot;）
    PASSWORD &apos;strong_password&apos;
    NOSUPERUSER         -- 不是超级用户（默认就是，显式写出来更清楚）
    NOCREATEDB          -- 不能建库
    NOCREATEROLE        -- 不能建角色、不能给自己提权
    CONNECTION LIMIT 20 -- 最多同时 20 个连接
    VALID UNTIL &apos;2027-01-01&apos;;  -- 到期自动失效，适合临时账号
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个属性的红线：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;SUPERUSER&lt;/code&gt; 绕过一切权限检查，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;除了 postgres 本人，任何业务账号、应用账号都不许是超级用户&lt;/strong&gt;&amp;lt;/span&amp;gt;。日常需要超级权限时临时用 postgres，不要图省事给应用开。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;CREATEROLE&lt;/code&gt; 看似无害，实则接近超级用户：能建角色的人可以建出高权限角色或改动他人属性。只给 DBA。&lt;/li&gt;
&lt;li&gt;密码策略上，PostgreSQL 本身不做复杂度校验，强度靠流程把关；配合 pg_hba.conf 的 &lt;code&gt;scram-sha-256&lt;/code&gt; 认证（上一篇讲过）使用。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;查看现有角色：psql 里用 &lt;code&gt;\du&lt;/code&gt;（下一篇 &lt;a href=&quot;/posts/postgresql-psql-guide/&quot;&gt;《psql 常用命令与操作实战》&lt;/a&gt; 会系统讲 psql），或查系统目录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SELECT rolname, rolsuper, rolcanlogin, rolconnlimit FROM pg_roles;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;三级权限体系：库、模式、表&lt;/h2&gt;
&lt;p&gt;PostgreSQL 的对象权限分三层，授权要层层都给到，缺一层就报 &lt;code&gt;permission denied&lt;/code&gt;：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;层级&lt;/th&gt;
&lt;th&gt;关键权限&lt;/th&gt;
&lt;th&gt;控制什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;数据库&lt;/td&gt;
&lt;td&gt;&lt;code&gt;CONNECT&lt;/code&gt;、&lt;code&gt;CREATE&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;能不能连进这个库、能不能在库里建模式&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;模式（schema）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;USAGE&lt;/code&gt;、&lt;code&gt;CREATE&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;能不能「看见并使用」模式里的对象、能不能建表&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;表&lt;/td&gt;
&lt;td&gt;&lt;code&gt;SELECT&lt;/code&gt;、&lt;code&gt;INSERT&lt;/code&gt;、&lt;code&gt;UPDATE&lt;/code&gt;、&lt;code&gt;DELETE&lt;/code&gt; 等&lt;/td&gt;
&lt;td&gt;对具体表能做什么操作&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一个应用账号的标准授权全套（在目标库里执行）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 库级：允许连接
GRANT CONNECT ON DATABASE appdb TO appuser;

-- 模式级：public 模式的使用权
-- 注意：PostgreSQL 15 起，public 模式默认不再向所有人开放 CREATE 权限
GRANT USAGE ON SCHEMA public TO appuser;

-- 表级：现有全部表的读写
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO appuser;

-- 序列：自增主键背后的序列也要给，不然插入数据时会报错
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO appuser;

-- 关键一步：给&quot;未来新建的表&quot;预授权，否则下次建表后应用又没权限
ALTER DEFAULT PRIVILEGES IN SCHEMA public
    GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO appuser;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
    GRANT USAGE, SELECT ON SEQUENCES TO appuser;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;ALTER DEFAULT PRIVILEGES&lt;/code&gt; 是最容易被漏掉的一步：没有它，今天授权一切正常，明天新上线一张表，应用立刻报错。还要注意，它只对「执行这条命令的那个角色今后新建的对象」生效，所以要用实际建表的账号（通常是 postgres 或跑迁移脚本的账号）来执行。&lt;/p&gt;
&lt;h2&gt;用组角色管理权限：别逐个账号授权&lt;/h2&gt;
&lt;p&gt;账号一多，逐个 &lt;code&gt;GRANT&lt;/code&gt; 必乱。正确姿势是建不带 &lt;code&gt;LOGIN&lt;/code&gt; 的&lt;strong&gt;组角色&lt;/strong&gt;承载权限，个人账号只加入组：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 两个组角色：只读组、应用读写组
CREATE ROLE role_readonly NOLOGIN;
CREATE ROLE role_app NOLOGIN;

GRANT CONNECT ON DATABASE appdb TO role_readonly, role_app;
GRANT USAGE ON SCHEMA public TO role_readonly, role_app;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO role_readonly;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO role_app;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO role_app;

-- 个人/服务账号只入组，权限自动继承
CREATE USER alice WITH PASSWORD &apos;alice_password&apos;;
GRANT role_readonly TO alice;

CREATE USER report_svc WITH PASSWORD &apos;report_password&apos;;
GRANT role_readonly TO report_svc;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;离职或转岗时只需 &lt;code&gt;DROP USER alice;&lt;/code&gt;，组上的权限纹丝不动；要全员收紧某项权限，改组一处即可。这也是为什么在 &lt;a href=&quot;/posts/sql-basics-crud/&quot;&gt;《SQL 基础速成》&lt;/a&gt; 之后专门用一篇讲权限——它是团队协作的地基。&lt;/p&gt;
&lt;h2&gt;三类账号的落地模板&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;账号类型&lt;/th&gt;
&lt;th&gt;给什么&lt;/th&gt;
&lt;th&gt;不给什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;应用账号（程序连库用）&lt;/td&gt;
&lt;td&gt;目标库 CONNECT、业务模式 USAGE、业务表增删改查、序列&lt;/td&gt;
&lt;td&gt;超级用户、建库、建角色、碰其他库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;只读账号（报表、人工排查）&lt;/td&gt;
&lt;td&gt;CONNECT、USAGE、全表 SELECT&lt;/td&gt;
&lt;td&gt;一切写权限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;运维账号（DBA 日常）&lt;/td&gt;
&lt;td&gt;建库建角色、全部对象权限&lt;/td&gt;
&lt;td&gt;平时不用超级用户，动大手术时才切 postgres&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;只读账号还有一个双保险：给它设默认只读事务，防手滑写库：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ALTER USER alice SET default_transaction_read_only = on;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;改密码、回收权限与删号&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;ALTER USER appuser WITH PASSWORD &apos;new_strong_password&apos;;  -- 改密码
ALTER USER appuser CONNECTION LIMIT 5;                   -- 改连接数上限
REVOKE DELETE ON TABLE orders FROM appuser;              -- 回收单项权限
REVOKE ALL ON DATABASE appdb FROM appuser;               -- 回收整库权限
DROP USER appuser;                                       -- 删号（名下拥有对象时会失败）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;DROP USER&lt;/code&gt; 前如果这个账号拥有表等对象，会直接报错删不掉。标准处理顺序：先 &lt;code&gt;REASSIGN OWNED BY 旧账号 TO 新账号;&lt;/code&gt; 把对象转给别人，再 &lt;code&gt;DROP OWNED BY 旧账号;&lt;/code&gt; 清掉它的残留权限，最后 &lt;code&gt;DROP USER 旧账号;&lt;/code&gt;。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;千万不要为了让删号成功就随手把对象 DROP 掉&lt;/strong&gt;&amp;lt;/span&amp;gt;，那删掉的可能是业务表。
:::&lt;/p&gt;
&lt;p&gt;回收权限后想确认是否收干净，查信息模式最直观：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- 某账号在各表上的实际权限一览
SELECT table_name, privilege_type
FROM information_schema.role_table_grants
WHERE grantee = &apos;appuser&apos;;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：授权全给了，应用还是报 &lt;code&gt;permission denied for table xxx&lt;/code&gt;？&lt;/strong&gt;
A：按三层逐个查：库的 CONNECT 有没有、模式的 USAGE 有没有、这张表的权限有没有。最高频的原因是这张表建于授权之后、而没设 &lt;code&gt;ALTER DEFAULT PRIVILEGES&lt;/code&gt;；其次是应用连错了库（开发、生产环境串了）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：插入数据时报 &lt;code&gt;permission denied for sequence&lt;/code&gt;？&lt;/strong&gt;
A：自增主键插入时要取序列的下一个值，序列是独立对象、独立授权。补 &lt;code&gt;GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO appuser;&lt;/code&gt;，并同步补上默认权限。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：新建的数据库里，appuser 连得上却建不了表？&lt;/strong&gt;
A：建表需要模式的 &lt;code&gt;CREATE&lt;/code&gt; 权限。PostgreSQL 15 起 public 模式收紧了默认权限，显式执行 &lt;code&gt;GRANT CREATE ON SCHEMA public TO appuser;&lt;/code&gt; 即可。更推荐的做法是给应用建专属模式并把该模式的所有权给它。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：怎么看某个账号到底属于哪些组、继承了什么权限？&lt;/strong&gt;
A：查成员关系可以用 &lt;code&gt;SELECT * FROM pg_auth_members;&lt;/code&gt; 配合 &lt;code&gt;pg_roles&lt;/code&gt; 看；更省事的是在 psql 里执行 &lt;code&gt;\du 账号名&lt;/code&gt;，直接看它的角色成员身份列表。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：忘记 postgres 超级用户密码怎么办？&lt;/strong&gt;
A：本机用系统用户 postgres 通过 peer 认证进去（&lt;code&gt;sudo -u postgres psql&lt;/code&gt;），再用 &lt;code&gt;ALTER USER postgres WITH PASSWORD &apos;...&apos;&lt;/code&gt; 重设。Docker 场景则 &lt;code&gt;docker exec -it 容器 psql -U postgres&lt;/code&gt; 进去改——容器内本地连接默认走 trust，这正是官方镜像的默认行为。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;PostgreSQL 权限管理的骨架就三句话：用户即带 LOGIN 的角色；权限分库、模式、表三层，层层都要给；用组角色承载权限、个人只入组，再用默认权限兜住未来的新表。下一篇换个工具视角，把每天都要用的 psql 客户端练熟。&lt;/p&gt;
</content:encoded></item><item><title>Redis 五大数据类型与实战用法</title><link>https://www.anexns.cloudns.org/posts/redis-data-types/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/redis-data-types/</guid><description>Redis 不只是简单的键值缓存：String、Hash、List、Set、ZSet 五大类型逐个讲透，附完整命令演示、底层选择思路和真实场景对照表，看完就知道什么数据该用哪种类型存。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;写在前面：Redis 的值不只是字符串&lt;/h2&gt;
&lt;p&gt;很多人对 Redis 的第一印象是「一个很快的键值缓存」：&lt;code&gt;SET key value&lt;/code&gt;、&lt;code&gt;GET key&lt;/code&gt;，存个验证码、缓存个查询结果就完事了。但 Redis 真正强大的地方在于，&lt;strong&gt;值（value）本身可以是结构化的数据&lt;/strong&gt;：一个键可以对应一个哈希表、一个列表、一个集合，甚至一个带分数的有序集合。官方把 Redis 定位为「数据结构服务器」（data structures server），这五大基本类型就是它安身立命的本钱。&lt;/p&gt;
&lt;p&gt;上一篇 &lt;a href=&quot;/posts/redis-install-config/&quot;&gt;《Redis 安装与初始配置》&lt;/a&gt; 已经把 Redis 7.4 装好并跑起来了，本文默认你手边有一个能连的实例（Docker 或本机安装都行），所有命令都可以直接在 &lt;code&gt;redis-cli&lt;/code&gt; 里敲一遍。本文主线：先讲清五大类型的命令和特点，再用一张场景对照表收尾，帮你建立「看到业务需求就知道该用哪种类型」的直觉。下一篇 &lt;a href=&quot;/posts/redis-persistence/&quot;&gt;《Redis 持久化：RDB 与 AOF 怎么选》&lt;/a&gt; 会接着讲这些数据怎么落盘保存。&lt;/p&gt;
&lt;p&gt;先记住一个全局性的事实：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;Redis 所有命令都是原子执行的，键名本身永远是字符串&lt;/strong&gt;&amp;lt;/span&amp;gt;。不管值是什么类型，键都是字符串；类型不同，说的是值的结构不同。&lt;/p&gt;
&lt;h2&gt;通用命令：先把键管好&lt;/h2&gt;
&lt;p&gt;在讲五大类型之前，先掌握一组对所有类型都适用的键命令，后面每个小节都会用到：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SET name &quot;alice&quot;          # 设置键
GET name                  # 取值（仅限 String 类型）
DEL name                  # 删除键，可一次删多个
EXISTS name               # 键是否存在，返回 1/0
TYPE name                 # 查看值的类型：string/hash/list/set/zset/none
KEYS user:*               # 按模式查找键（生产环境慎用，见下方警告）
SCAN 0 MATCH user:*       # 游标方式遍历键，生产环境用这个
EXPIRE name 60            # 设置过期时间（秒）
TTL name                  # 查看剩余存活时间，-1 表示永不过期，-2 表示键不存在
RENAME name newname       # 重命名键
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;KEYS&lt;/code&gt; 命令会一次性扫描全部键，数据量大时会&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;阻塞 Redis 主线程&amp;lt;/span&amp;gt;，期间所有请求都得排队等。线上排查问题时查键请用 &lt;code&gt;SCAN&lt;/code&gt; 游标分批遍历，不要图省事用 &lt;code&gt;KEYS *&lt;/code&gt;。
:::&lt;/p&gt;
&lt;p&gt;另外有个设计习惯值得一开始就养成：&lt;strong&gt;键名用冒号分层&lt;/strong&gt;，比如 &lt;code&gt;user:1001:profile&lt;/code&gt;、&lt;code&gt;cache:article:9527&lt;/code&gt;。Redis 没有「目录」的概念，但这种命名法能让 &lt;code&gt;SCAN MATCH user:1001:*&lt;/code&gt; 这类按前缀查找变得很自然，团队协作时也一目了然。&lt;/p&gt;
&lt;h2&gt;String：最基础，也最万能&lt;/h2&gt;
&lt;p&gt;String 是最简单的类型，一个键对应一个字符串值，但它能装的不只是文本：数字、二进制数据（图片、序列化后的对象）都可以，单个值最大 512 MB。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SET session:abc123 &quot;user_id=1001&quot; EX 1800   # 存会话，30 分钟过期（EX 是秒）
SET counter:pageviews 0                      # 计数器初始值
INCR counter:pageviews                       # 原子加 1，返回新值
INCRBY counter:pageviews 10                  # 原子加 10
DECR counter:pageviews                       # 原子减 1
SET article:9527 &quot;文章内容...&quot; NX            # NX：键不存在才设置（分布式锁的雏形）
SETNX lock:order:1 1                         # 同上，老写法
MSET k1 v1 k2 v2                             # 批量设置
MGET k1 k2                                   # 批量获取
APPEND name &quot;-san&quot;                           # 往字符串尾部追加
STRLEN name                                  # 字符串长度
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;String 的典型场景：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;缓存&lt;/strong&gt;：把数据库查询结果序列化成 JSON 字符串存进来，设过期时间，这是 Redis 最常见的用法&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;计数器&lt;/strong&gt;：&lt;code&gt;INCR&lt;/code&gt; 是原子操作，天生适合浏览量、点赞数、限流计数，不用担心并发下算错&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;会话与验证码&lt;/strong&gt;：短时效数据，&lt;code&gt;SET ... EX 秒数&lt;/code&gt; 一步到位&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;注意 &lt;code&gt;INCR&lt;/code&gt; 的前提是值能被解析成整数；如果键不存在，&lt;code&gt;INCR&lt;/code&gt; 会把它当作 0 再加 1，所以计数器甚至不用预先初始化。&lt;/p&gt;
&lt;h2&gt;Hash：存对象的天然选择&lt;/h2&gt;
&lt;p&gt;Hash 是一个键下面挂着多个字段-值对（field-value），特别适合存「对象」：一个用户有姓名、年龄、城市等多个属性，用一个 Hash 键全装下，比拆成多个 String 键优雅得多，也更省内存。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;HSET user:1001 name &quot;alice&quot; age 28 city &quot;guangzhou&quot;   # 一次设置多个字段
HGET user:1001 name                                    # 取单个字段
HMGET user:1001 name age                               # 取多个字段
HGETALL user:1001                                      # 取全部字段和值
HINCRBY user:1001 age 1                                # 字段值原子加 1
HDEL user:1001 city                                    # 删除字段
HEXISTS user:1001 email                                # 字段是否存在
HKEYS user:1001                                        # 所有字段名
HLEN user:1001                                         # 字段个数
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Hash 与「把对象序列化成 JSON 存 String」的取舍：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;Hash&lt;/th&gt;
&lt;th&gt;JSON 存 String&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;修改单个字段&lt;/td&gt;
&lt;td&gt;&lt;code&gt;HSET&lt;/code&gt; 直接改，不用读出全量&lt;/td&gt;
&lt;td&gt;要 GET 出来改完再 SET 回去&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;读取单个字段&lt;/td&gt;
&lt;td&gt;&lt;code&gt;HGET&lt;/code&gt; 只取需要的&lt;/td&gt;
&lt;td&gt;必须取整个 JSON 再解析&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;内存占用&lt;/td&gt;
&lt;td&gt;字段少时有紧凑编码优化，很省&lt;/td&gt;
&lt;td&gt;一份 JSON 文本的体积&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;嵌套结构&lt;/td&gt;
&lt;td&gt;不支持，字段值只能是字符串&lt;/td&gt;
&lt;td&gt;天然支持多层嵌套&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合场景&lt;/td&gt;
&lt;td&gt;扁平对象：用户资料、商品属性、配置项&lt;/td&gt;
&lt;td&gt;结构复杂、整体读写的文档型数据&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;经验法则：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;对象字段经常单独读写就用 Hash，总是整存整取就用 String 存 JSON&lt;/strong&gt;&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h2&gt;List：队列和时间线的老手&lt;/h2&gt;
&lt;p&gt;List 是按插入顺序排列的字符串链表，两头都能进、能出。它最经典的用途是消息队列和最新列表。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;LPUSH queue:tasks &quot;task1&quot; &quot;task2&quot;    # 从左侧（头部）压入
RPUSH queue:tasks &quot;task3&quot;            # 从右侧（尾部）压入
LPOP queue:tasks                     # 从左侧弹出一个
RPOP queue:tasks                     # 从右侧弹出一个
LRANGE queue:tasks 0 -1              # 查看全部元素（0 到 -1 表示头到尾）
LRANGE feed:1001 0 9                 # 取前 10 条：最新动态列表常用
LLEN queue:tasks                     # 列表长度
LINDEX queue:tasks 0                 # 按下标取值
LTRIM feed:1001 0 99                 # 只保留前 100 条，老数据自动丢弃
BLPOP queue:tasks 0                  # 阻塞式弹出，没数据就等（0 表示一直等）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;队列的经典组合是 &lt;code&gt;LPUSH&lt;/code&gt; + &lt;code&gt;BRPOP&lt;/code&gt;（或阻塞版 &lt;code&gt;BLPOP&lt;/code&gt;）：生产者从左边放任务，消费者从右边阻塞着取，没任务时不占 CPU，有任务立刻被唤醒。做「最新评论」「最新动态」这类只保留最近 N 条的列表时，&lt;code&gt;LPUSH&lt;/code&gt; + &lt;code&gt;LTRIM key 0 99&lt;/code&gt; 是标准姿势，列表长度永远不会失控。&lt;/p&gt;
&lt;p&gt;:::warning
List 没有去重能力，同一个元素可以出现很多次；另外 &lt;code&gt;LPOP&lt;/code&gt;/&lt;code&gt;RPOP&lt;/code&gt; 取走即删除，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;消费者处理失败时任务就丢了&amp;lt;/span&amp;gt;。对可靠性要求高的消息队列请用 Redis Stream（&lt;code&gt;XADD&lt;/code&gt;/&lt;code&gt;XREADGROUP&lt;/code&gt;，带消费组和确认机制），不要硬拿 List 凑。
:::&lt;/p&gt;
&lt;h2&gt;Set：无序、唯一，天生去重&lt;/h2&gt;
&lt;p&gt;Set 是无序集合，最大的特点是&lt;strong&gt;元素唯一&lt;/strong&gt;，重复添加会自动忽略。它适合一切「去重」和「集合运算」的场景。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SADD tags:article:1 &quot;redis&quot; &quot;database&quot; &quot;cache&quot;   # 添加成员，重复的自动忽略
SADD tags:article:1 &quot;redis&quot;                       # 返回 0，已存在
SMEMBERS tags:article:1                           # 查看全部成员
SISMEMBER tags:article:1 &quot;redis&quot;                  # 是否包含某成员，返回 1/0
SCARD tags:article:1                              # 成员个数
SREM tags:article:1 &quot;cache&quot;                       # 删除成员
SRANDMEMBER lottery 3                             # 随机抽 3 个（抽奖）
SPOP lottery                                      # 随机弹出一个
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;集合运算是 Set 的杀手锏，交集、并集、差集一条命令搞定：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SADD user:1:follows &quot;a&quot; &quot;b&quot; &quot;c&quot;
SADD user:2:follows &quot;b&quot; &quot;c&quot; &quot;d&quot;
SINTER user:1:follows user:2:follows     # 交集：共同关注 → b、c
SUNION user:1:follows user:2:follows     # 并集：全部关注
SDIFF user:1:follows user:2:follows      # 差集：1 关注了而 2 没关注的 → a
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;典型场景：文章标签、共同好友/共同关注、抽奖池、IP 黑名单、UV 统计的粗略去重（精确去重成员太多时可以考虑 HyperLogLog，那是另一个话题了）。&lt;/p&gt;
&lt;h2&gt;ZSet：带分数的有序集合，排行榜专用&lt;/h2&gt;
&lt;p&gt;ZSet（Sorted Set）在 Set 的基础上给每个成员绑定一个分数（score，浮点数），成员按分数自动排序。它是五大类型里唯一能「按分取排名」的，排行榜场景无可替代。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ZADD rank:score 980 &quot;alice&quot; 950 &quot;bob&quot; 1024 &quot;carol&quot;   # 添加成员和分数
ZINCRBY rank:score 10 &quot;alice&quot;                         # alice 的分数加 10
ZREVRANGE rank:score 0 9 WITHSCORES                   # 分数从高到低取前 10 名（排行榜）
ZRANGE rank:score 0 -1 WITHSCORES                     # 从低到高全取
ZREVRANK rank:score &quot;alice&quot;                           # 查 alice 的名次（从 0 开始）
ZSCORE rank:score &quot;alice&quot;                             # 查分数
ZRANGEBYSCORE rank:score 900 1000                     # 按分数区间取成员
ZREM rank:score &quot;bob&quot;                                 # 删除成员
ZCARD rank:score                                      # 成员总数
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;ZSet 的另一大用途是&lt;strong&gt;延时队列&lt;/strong&gt;：把分数设为「任务到期时的 Unix 时间戳」，消费者用 &lt;code&gt;ZRANGEBYSCORE key 0 当前时间戳&lt;/code&gt; 就能捞出所有到期任务。还有滑动窗口限流：用当前时间戳做分数记录每次请求，统计窗口内的成员数即可，&lt;a href=&quot;/posts/redis-use-cases/&quot;&gt;《Redis 应用场景实战》&lt;/a&gt; 里会完整演示。&lt;/p&gt;
&lt;p&gt;注意：ZSet 里成员唯一，但分数可以相同；分数相同时按成员的字典序排列。&lt;code&gt;ZADD&lt;/code&gt; 在 Redis 7.4 里还支持 &lt;code&gt;GT&lt;/code&gt;/&lt;code&gt;LT&lt;/code&gt; 选项（只在新分数更大/更小时才更新），刷榜单最高分时很好用。&lt;/p&gt;
&lt;h2&gt;五大类型场景速查表&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;一句话特征&lt;/th&gt;
&lt;th&gt;典型场景&lt;/th&gt;
&lt;th&gt;关键命令&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;String&lt;/td&gt;
&lt;td&gt;一个键一个值&lt;/td&gt;
&lt;td&gt;缓存、计数器、会话、验证码&lt;/td&gt;
&lt;td&gt;&lt;code&gt;SET&lt;/code&gt; / &lt;code&gt;GET&lt;/code&gt; / &lt;code&gt;INCR&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Hash&lt;/td&gt;
&lt;td&gt;一个键一堆字段&lt;/td&gt;
&lt;td&gt;用户资料、商品属性、购物车&lt;/td&gt;
&lt;td&gt;&lt;code&gt;HSET&lt;/code&gt; / &lt;code&gt;HGETALL&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;List&lt;/td&gt;
&lt;td&gt;有序、可两头进出&lt;/td&gt;
&lt;td&gt;简单队列、最新动态列表&lt;/td&gt;
&lt;td&gt;&lt;code&gt;LPUSH&lt;/code&gt; / &lt;code&gt;BRPOP&lt;/code&gt; / &lt;code&gt;LTRIM&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Set&lt;/td&gt;
&lt;td&gt;无序、元素唯一&lt;/td&gt;
&lt;td&gt;标签、共同好友、去重、抽奖&lt;/td&gt;
&lt;td&gt;&lt;code&gt;SADD&lt;/code&gt; / &lt;code&gt;SINTER&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ZSet&lt;/td&gt;
&lt;td&gt;按分数排序&lt;/td&gt;
&lt;td&gt;排行榜、延时队列、滑动窗口限流&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ZADD&lt;/code&gt; / &lt;code&gt;ZREVRANGE&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;除了五大基本类型，Redis 还有 Bitmap（位图，适合签到统计）、HyperLogLog（基数估算）、Geospatial（地理位置）、Stream（消息流）等扩展类型，日常开发先把这五种吃透，覆盖 90% 的场景没问题。&lt;/p&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：一个键能存多大的 Hash/List/Set？&lt;/strong&gt;
每个集合类型最多 2^32 - 1 个元素（约 42 亿），实际瓶颈是内存。但要注意「大键」问题：单个键挂几十万元素时，&lt;code&gt;HGETALL&lt;/code&gt;、&lt;code&gt;SMEMBERS&lt;/code&gt; 这类全量命令会一次返回海量数据，阻塞其他请求。排查大键用 &lt;code&gt;redis-cli --bigkeys&lt;/code&gt;，拆分大键是常见优化手段。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：给 Hash 里的单个字段设过期时间可以吗？&lt;/strong&gt;
可以。Redis 7.4 起 Hash 支持字段级过期，命令是 &lt;code&gt;HEXPIRE&lt;/code&gt;、&lt;code&gt;HPEXPIRE&lt;/code&gt;、&lt;code&gt;HTTL&lt;/code&gt; 等。在 7.4 之前只能给整个键设过期，这也是升级到 7.4 的一个实际好处。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：类型用错了会怎样？比如对 Hash 用 GET？&lt;/strong&gt;
Redis 会直接报错：&lt;code&gt;WRONGTYPE Operation against a key holding the wrong kind of value&lt;/code&gt;。不会损坏数据，但程序会抛异常。拿不准时先用 &lt;code&gt;TYPE key&lt;/code&gt; 确认类型。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：过期键是到时间立刻删除吗？&lt;/strong&gt;
不是精确删除。Redis 用「惰性删除（访问时检查）＋定期抽样删除」组合策略，过期键可能短暂残留，但读的时候永远读不到已过期的值。把 Redis 当缓存用完全没问题，别把它当精确定时器。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：五大类型的内存占用有差别吗？&lt;/strong&gt;
有。集合元素少且短时，Redis 会用紧凑编码（如 listpack）存储，内存非常省；超过阈值（由 &lt;code&gt;hash-max-listpack-entries&lt;/code&gt; 等参数控制，默认 128 或 512 不等）才转为标准结构。日常使用不用操心，知道有这回事即可。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;五大类型各管一摊：String 管缓存和计数，Hash 管对象，List 管队列和最新列表，Set 管去重和集合运算，ZSet 管一切带排名的场景。选型的核心问题是先想清楚三件事：&lt;strong&gt;数据要不要有序、要不要去重、是整存整取还是按字段读写&lt;/strong&gt;，答案出来了，类型自然就定了。下一篇讲 &lt;a href=&quot;/posts/redis-persistence/&quot;&gt;持久化&lt;/a&gt;：内存里的数据断电了怎么办，RDB 和 AOF 两种机制怎么选、怎么配。&lt;/p&gt;
</content:encoded></item><item><title>Redis 安装与初始配置</title><link>https://www.anexns.cloudns.org/posts/redis-install-config/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/redis-install-config/</guid><description>把 Redis 7.4 正确地跑起来：Docker Compose 与系统包两种安装方式，讲透 redis.conf 里 bind、密码、最大内存与淘汰策略这几个决定生死的参数，以及上线前的安全自查。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;为什么 Redis 的初始配置格外重要&lt;/h2&gt;
&lt;p&gt;从这一篇开始进入 Redis 部分。在 &lt;a href=&quot;/posts/database-choosing-guide/&quot;&gt;数据库怎么选&lt;/a&gt; 里我们说过，Redis 是内存型键值数据库，定位是缓存、计数器、排行榜、分布式锁这类高速场景，不是拿来替代关系型数据库的主存储。&lt;/p&gt;
&lt;p&gt;但 Redis 有个特点：&lt;strong&gt;默认配置是为「开箱即用」设计的，不是为「安全上线」设计的&lt;/strong&gt;。历史上大量 Redis 被入侵事件，根源都是同一个：无密码、监听所有网卡、直接暴露公网。所以这一篇的主线是：装好只是第一步，把 bind、密码、内存上限这三件事配置对，才算真正能用。&lt;/p&gt;
&lt;h2&gt;路线一：Docker Compose 部署（推荐）&lt;/h2&gt;
&lt;p&gt;目录与 Compose 文件（单机练习与小规模生产都适用）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/redis7/{data,conf} &amp;amp;&amp;amp; cd ~/redis7
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;# docker-compose.yml
services:
  redis:
    image: redis:7.4
    container_name: redis7
    restart: unless-stopped
    ports:
      - &quot;127.0.0.1:6379:6379&quot;
    volumes:
      - ./data:/data
      - ./conf/redis.conf:/usr/local/etc/redis/redis.conf:ro
    command: redis-server /usr/local/etc/redis/redis.conf
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;配置文件 &lt;code&gt;conf/redis.conf&lt;/code&gt; 先写一份最小但正确的版本：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;bind 0.0.0.0
port 6379
protected-mode yes
requirepass ChangeMe_Redis_2026!
daemonize no
dir /data
dbfilename dump.rdb
appendonly yes
appendfilename &quot;appendonly.aof&quot;
maxmemory 1gb
maxmemory-policy allkeys-lru
timeout 300
tcp-keepalive 300
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动与验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose logs redis

# 带密码连接测试
docker exec -it redis7 redis-cli -a &apos;ChangeMe_Redis_2026!&apos; PING
# 期望返回 PONG

docker exec -it redis7 redis-cli -a &apos;ChangeMe_Redis_2026!&apos; INFO server | grep redis_version
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意容器里 &lt;code&gt;bind 0.0.0.0&lt;/code&gt; 是对的：Docker 的网络隔离由宿主机端口映射负责，宿主机侧只绑 &lt;code&gt;127.0.0.1&lt;/code&gt; 就不会暴露到公网。持久化细节（RDB 与 AOF 为什么这里两个都开）留到 &lt;a href=&quot;/posts/redis-persistence/&quot;&gt;Redis 持久化：RDB 与 AOF 怎么选&lt;/a&gt; 专门讲，本篇先让它跑起来。&lt;/p&gt;
&lt;h2&gt;路线二：系统包安装（Debian / Ubuntu）&lt;/h2&gt;
&lt;p&gt;Redis 官方提供 APT 仓库，版本跟得比发行版自带源新：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 添加官方仓库后
sudo apt update
sudo apt install -y redis

sudo systemctl enable --now redis-server
sudo systemctl status redis-server
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;系统包的配置文件在 &lt;code&gt;/etc/redis/redis.conf&lt;/code&gt;，改完 &lt;code&gt;sudo systemctl restart redis-server&lt;/code&gt; 生效。两种路线对比：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;Docker Compose&lt;/th&gt;
&lt;th&gt;系统包安装&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;版本&lt;/td&gt;
&lt;td&gt;镜像 tag 锁定 7.4，升级换 tag&lt;/td&gt;
&lt;td&gt;跟官方 APT 仓库走&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;配置位置&lt;/td&gt;
&lt;td&gt;项目内 &lt;code&gt;conf/redis.conf&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/etc/redis/redis.conf&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据目录&lt;/td&gt;
&lt;td&gt;宿主机 &lt;code&gt;./data&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/var/lib/redis&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;多实例&lt;/td&gt;
&lt;td&gt;改端口与目录即可并行多个&lt;/td&gt;
&lt;td&gt;需要多份配置与 systemd 单元，较繁琐&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合场景&lt;/td&gt;
&lt;td&gt;个人服务器、快速试错、多实例&lt;/td&gt;
&lt;td&gt;单实例长期运行、习惯系统服务管理&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;三合一的快速部署版本在 &lt;a href=&quot;/posts/database-docker-quickstart/&quot;&gt;用 Docker 快速搭建三大数据库&lt;/a&gt; 里有，这里是把 Redis 单独拎出来细化配置。&lt;/p&gt;
&lt;h2&gt;初始配置的四个关键参数&lt;/h2&gt;
&lt;h3&gt;1. bind 与 protected-mode：决定谁能连上你&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;bind 127.0.0.1 -::1&lt;/code&gt; 表示只监听本机回环，这是系统包安装的安全默认值。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;最危险的组合是 bind 0.0.0.0 + 无密码 + protected-mode no&amp;lt;/span&amp;gt;，等于把数据库大门敞开给整个互联网，自动化扫描几分钟内就能找上门。&lt;/p&gt;
&lt;p&gt;需要远程连接时，正确顺序是：先设密码、再改 bind 到内网网卡地址、防火墙只放行应用服务器 IP。顺序反了，中间窗口期就可能被扫到。&lt;/p&gt;
&lt;h3&gt;2. requirepass：密码必须设，且要够强&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;requirepass ChangeMe_Redis_2026!
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Redis 的密码验证速度极快（每秒可尝试上百万次），短密码形同虚设，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;密码长度至少 16 位、随机生成，和其它服务的密码不要复用&amp;lt;/span&amp;gt;。Redis 6.0 起还支持 ACL 多用户权限，可以给不同应用发不同账号并限制可执行的命令与可访问的键前缀：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 在 redis.conf 中追加，或运行时用 ACL SETUSER
# 创建只读账号，只能读 cache: 前缀的键
ACL SETUSER reader on &apos;&amp;gt;ReadOnly_2026!&apos; ~cache:* +get +mget +exists
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;验证 ACL 账号：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;redis-cli --user reader --pass &apos;ReadOnly_2026!&apos; GET cache:home
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;3. maxmemory：不设上限迟早被系统杀掉&lt;/h3&gt;
&lt;p&gt;Redis 把全部数据放在内存里。如果不设 &lt;code&gt;maxmemory&lt;/code&gt;，缓存只进不出，内存涨满后要么 Redis 自己 OOM，要么被 Linux 的 OOM Killer 连带干掉。给缓存型实例设上限是必修课：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;maxmemory 1gb
maxmemory-policy allkeys-lru
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;上限的取值：专机可给物理内存的 60%–75%，混跑机器按规划预留。注意主存储型用法（当队列、锁服务）不要用会淘汰数据的策略，见下节。&lt;/p&gt;
&lt;h3&gt;4. maxmemory-policy：内存满了淘汰谁&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;策略&lt;/th&gt;
&lt;th&gt;行为&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;noeviction&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不淘汰，写入直接报错&lt;/td&gt;
&lt;td&gt;队列、锁、不可丢数据&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;allkeys-lru&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;所有键里淘汰最久未用的&lt;/td&gt;
&lt;td&gt;通用缓存，最常用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;allkeys-lfu&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;所有键里淘汰最不常用的&lt;/td&gt;
&lt;td&gt;热点明显的缓存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;volatile-lru&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只在带过期时间的键里淘汰 LRU&lt;/td&gt;
&lt;td&gt;混存场景：持久键 + 缓存键&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;allkeys-random&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;随机淘汰&lt;/td&gt;
&lt;td&gt;数据访问均匀、无冷热之分&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;volatile-ttl&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;优先淘汰快过期的键&lt;/td&gt;
&lt;td&gt;缓存键过期时间有意义时&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;纯缓存场景默认选 allkeys-lru，拿不准就用它；存了不能丢的数据就必须 noeviction 并靠监控告警守内存。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;:::warning
两个老生常谈但仍在不断出事的点：一是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不要用 root 身份直接把 6379 暴露公网且不设密码&amp;lt;/span&amp;gt;，被入侵后攻击者常用 &lt;code&gt;CONFIG SET dir&lt;/code&gt; + 写文件的方式落 SSH 密钥；二是生产环境建议禁用或改名高危命令（如 &lt;code&gt;FLUSHALL&lt;/code&gt;、&lt;code&gt;CONFIG&lt;/code&gt;、&lt;code&gt;KEYS&lt;/code&gt;），可以在 redis.conf 里用 &lt;code&gt;rename-command FLUSHALL &quot;&quot;&lt;/code&gt; 禁用，防应用层误操作与注入。
:::&lt;/p&gt;
&lt;h2&gt;连接、体检与常用管理命令&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;# 交互连接（密码不写在命令里更安全，用 -a 会留在进程列表与历史中，练习环境可接受）
redis-cli -h 127.0.0.1 -p 6379 -a &apos;ChangeMe_Redis_2026!&apos;

# 体检三件套
INFO memory        # 内存使用：used_memory_human、maxmemory_human、碎片率
INFO stats         # 命中率相关：keyspace_hits / keyspace_misses
DBSIZE             # 当前库键数量
SLOWLOG GET 5      # 最近 5 条慢命令（默认阈值 10ms）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;缓存命中率 = hits / (hits + misses)，长期低于 80% 说明缓存策略或容量有问题。数据类型与具体用法在下一篇 &lt;a href=&quot;/posts/redis-data-types/&quot;&gt;Redis 五大数据类型与实战用法&lt;/a&gt; 展开，这里先会看状态。&lt;/p&gt;
&lt;p&gt;运行时改配置（重启失效，重要变更务必同步写回 redis.conf）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CONFIG GET maxmemory*
CONFIG SET maxmemory 2gb
CONFIG REWRITE   # 把当前运行时配置写回配置文件（系统包安装时常用）
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;上线前自查与压力自测&lt;/h2&gt;
&lt;p&gt;配置改完别急着交付，跑一遍自查清单：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 确认监听范围与密码都已生效
redis-cli -a &apos;ChangeMe_Redis_2026!&apos; CONFIG GET bind
redis-cli -a &apos;ChangeMe_Redis_2026!&apos; CONFIG GET requirepass
redis-cli -a &apos;ChangeMe_Redis_2026!&apos; CONFIG GET maxmemory*

# 2. 确认无密码连接被拒绝（下面这条应该报错 NOAUTH）
redis-cli PING

# 3. 确认持久化状态正常
redis-cli -a &apos;ChangeMe_Redis_2026!&apos; INFO persistence | grep -E &apos;rdb_last_bgsave_status|aof_enabled&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再用官方自带的 &lt;code&gt;redis-benchmark&lt;/code&gt; 做一次本机基准自测，心里有数量级概念即可，不要拿它的数字当生产承诺：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 本机回环、带密码、测 SET/GET 的大致吞吐
redis-benchmark -h 127.0.0.1 -p 6379 -a &apos;ChangeMe_Redis_2026!&apos; -t set,get -n 100000 -q
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;单机 Redis 的 SET/GET 通常在每秒数万到十万级，如果测出来只有几千，先查是不是跨网络测试、管道（pipeline）没开、或机器 CPU 被限频。真实业务压测要用贴近业务的键大小与命令组合，&lt;code&gt;redis-benchmark&lt;/code&gt; 只适合安装验收阶段的冒烟测试。&lt;/p&gt;
&lt;p&gt;日志方面，Docker 部署时 Redis 日志直接打到标准输出，&lt;code&gt;docker compose logs&lt;/code&gt; 就能看；系统包安装则看 &lt;code&gt;/var/log/redis/redis-server.log&lt;/code&gt;。重点关注启动时的警告信息，比如内存超分配（overcommit）与透明大页（THP）的提示，这两条是官方明确建议在宿主机层面处理的：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 宿主机上执行（持久化写入 /etc/sysctl.conf 与开机脚本）
sudo sysctl vm.overcommit_memory=1
echo never | sudo tee /sys/kernel/mm/transparent_hugepage/enabled
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：容器启动就退出，日志报 &lt;code&gt;Can&apos;t open the append-only file&lt;/code&gt;？&lt;/strong&gt;
多为 &lt;code&gt;data&lt;/code&gt; 目录权限问题。官方镜像内以 redis 用户运行，确保宿主机挂载目录可写：&lt;code&gt;sudo chown -R 999:999 ./data&lt;/code&gt;（999 是镜像内 redis 用户的常用 UID），再重启容器。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：连接报 &lt;code&gt;NOAUTH Authentication required&lt;/code&gt;？&lt;/strong&gt;
服务端设了密码而客户端没带。&lt;code&gt;redis-cli&lt;/code&gt; 用 &lt;code&gt;-a 密码&lt;/code&gt; 或连接后执行 &lt;code&gt;AUTH 密码&lt;/code&gt;；用了 ACL 账号则要 &lt;code&gt;AUTH 用户名 密码&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：明明设了 maxmemory，内存还是超过上限？&lt;/strong&gt;
&lt;code&gt;maxmemory&lt;/code&gt; 限制的是数据内存，进程实际占用还包含客户端缓冲区、复制积压、内存碎片等开销。看 &lt;code&gt;INFO memory&lt;/code&gt; 里的 &lt;code&gt;mem_fragmentation_ratio&lt;/code&gt;，碎片率长期高于 1.5 可开启 &lt;code&gt;activedefrag yes&lt;/code&gt; 主动碎片整理。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：改了 redis.conf 重启没生效？&lt;/strong&gt;
Docker 方式先确认 Compose 里 command 指向的是挂载进去的那份配置，且文件是只读挂载后容器重建过（&lt;code&gt;docker compose up -d --force-recreate&lt;/code&gt;）。另外注意 &lt;code&gt;CONFIG SET&lt;/code&gt; 的运行时修改会在重启后被配置文件覆盖，别把两者搞混。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Redis 上线三件套：bind 只听该听的网卡、requirepass 设 16 位以上强密码、maxmemory 必须设上限。&lt;/li&gt;
&lt;li&gt;纯缓存用 &lt;code&gt;allkeys-lru&lt;/code&gt; 淘汰；存不可丢数据用 &lt;code&gt;noeviction&lt;/code&gt; 并做好内存监控。&lt;/li&gt;
&lt;li&gt;ACL 可以按应用发账号、限命令、限键前缀，比全员共用一个密码规范得多。&lt;/li&gt;
&lt;li&gt;高危命令该禁用的禁用，6379 永远不要无密码裸奔公网。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;装好配好，下一篇开始真正用它：&lt;a href=&quot;/posts/redis-data-types/&quot;&gt;Redis 五大数据类型与实战用法&lt;/a&gt;。&lt;/p&gt;
</content:encoded></item><item><title>Redis 持久化：RDB 与 AOF 怎么选</title><link>https://www.anexns.cloudns.org/posts/redis-persistence/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/redis-persistence/</guid><description>Redis 数据都在内存里，断电重启会不会全丢？本文讲透 RDB 快照与 AOF 日志两种持久化机制的原理、配置、恢复方式和优缺点对比，给出单机缓存、重要数据、Docker 部署三种场景的明确选型建议。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;写在前面：内存数据库的命门&lt;/h2&gt;
&lt;p&gt;上一篇 &lt;a href=&quot;/posts/redis-data-types/&quot;&gt;《Redis 五大数据类型与实战用法》&lt;/a&gt; 里，我们把各种数据结构玩得很顺手。但有个问题始终悬在头上：Redis 的数据全部放在内存里，进程一重启、服务器一断电，内存里的数据不就全没了吗？&lt;/p&gt;
&lt;p&gt;答案是：Redis 提供了两套持久化机制把数据写到硬盘上——**RDB（快照）**和 &lt;strong&gt;AOF（追加日志）&lt;/strong&gt;。重启时它会把硬盘上的文件重新读回内存。但两套机制的思路完全不同：RDB 是「隔一段时间给全部数据拍一张照片」，AOF 是「把每一条写命令都记进流水账」。选哪种、怎么组合，直接决定了你最坏情况下丢多少数据、恢复要多久。&lt;/p&gt;
&lt;p&gt;本文主线：先分别讲透 RDB 和 AOF 的工作方式与配置，再讲恢复流程和混合持久化，最后用一张对比表和三个场景给出明确结论。前置知识是 &lt;a href=&quot;/posts/redis-install-config/&quot;&gt;《Redis 安装与初始配置》&lt;/a&gt;，里面的 &lt;code&gt;dir&lt;/code&gt;、&lt;code&gt;dbfilename&lt;/code&gt; 等参数在这里会接着用。&lt;/p&gt;
&lt;h2&gt;RDB：定时给数据拍快照&lt;/h2&gt;
&lt;h3&gt;工作原理&lt;/h3&gt;
&lt;p&gt;RDB（Redis Database）的工作方式是：在某个时间点，把内存里的全部数据序列化成一个紧凑的二进制文件（默认叫 &lt;code&gt;dump.rdb&lt;/code&gt;），存到 &lt;code&gt;dir&lt;/code&gt; 配置指定的目录。触发快照有两种方式：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;自动触发&lt;/strong&gt;：配置文件里的 &lt;code&gt;save&lt;/code&gt; 规则，比如默认的三条：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;save 3600 1      # 3600 秒内至少有 1 次写入，就触发快照
save 300 100     # 300 秒内至少有 100 次写入，就触发快照
save 60 10000    # 60 秒内至少有 10000 次写入，就触发快照
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;手动触发&lt;/strong&gt;：执行 &lt;code&gt;BGSAVE&lt;/code&gt;（后台异步生成，推荐）或 &lt;code&gt;SAVE&lt;/code&gt;（同步生成，会阻塞主线程，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;生产环境不要用 SAVE&amp;lt;/span&amp;gt;）。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;真正干活时 Redis 会 fork 一个子进程，由子进程把数据写盘，父进程继续处理请求。靠的是操作系统的写时复制（copy-on-write）：fork 瞬间父子共享同一份内存页，父进程修改哪个页，系统才复制哪个页。所以快照期间内存占用最高可能接近翻倍，内存本来就吃紧的机器要留意。&lt;/p&gt;
&lt;h3&gt;RDB 的优缺点&lt;/h3&gt;
&lt;p&gt;优点很明确：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;恢复快&lt;/strong&gt;：一个二进制文件直接载入内存，大数据集恢复速度远快于 AOF 重放&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;文件小&lt;/strong&gt;：二进制紧凑编码，适合备份、异地传输、灾难恢复归档&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;不影响主进程性能&lt;/strong&gt;：写盘由子进程完成&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;缺点同样明确：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;丢数据窗口大&lt;/strong&gt;：两次快照之间宕机，这段时间的数据全丢。按默认配置，最坏能丢好几分钟&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;fork 成本&lt;/strong&gt;：数据量很大时 fork 子进程本身要复制页表，可能造成毫秒到秒级的卡顿&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;AOF：把每条写命令记成流水账&lt;/h2&gt;
&lt;h3&gt;工作原理&lt;/h3&gt;
&lt;p&gt;AOF（Append Only File）走的是另一条路：Redis 把每一条&lt;strong&gt;写命令&lt;/strong&gt;以文本协议的形式追加到 aof 文件末尾。重启时把这些命令从头到尾重新执行一遍，数据就恢复了——原理和 MySQL 的 binlog 回放是一个思路。&lt;/p&gt;
&lt;p&gt;Redis 7.4 的 AOF 是「多部件」结构：开启后 &lt;code&gt;dir&lt;/code&gt; 目录下会出现一个 &lt;code&gt;appendonlydir&lt;/code&gt; 文件夹，里面包含一个基础文件（base，相当于一份 RDB 格式的全量数据）和若干增量文件（incr，记录之后的写命令），外加一个清单文件（manifest）管理它们。&lt;/p&gt;
&lt;p&gt;开启 AOF 只需改一行配置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;appendonly yes          # 开启 AOF（默认 no）
appendfsync everysec    # 刷盘策略，见下文
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;刷盘策略：appendfsync 三档&lt;/h3&gt;
&lt;p&gt;AOF 写入后先进入操作系统的页缓存，什么时候真正落盘由 &lt;code&gt;appendfsync&lt;/code&gt; 决定，这是 AOF 最重要的参数：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;策略&lt;/th&gt;
&lt;th&gt;行为&lt;/th&gt;
&lt;th&gt;最坏丢失&lt;/th&gt;
&lt;th&gt;性能影响&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;always&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每条命令都同步刷盘&lt;/td&gt;
&lt;td&gt;几乎不丢&lt;/td&gt;
&lt;td&gt;很大，吞吐量明显下降&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;everysec&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;每秒刷一次盘（默认）&lt;/td&gt;
&lt;td&gt;最多丢 1 秒&lt;/td&gt;
&lt;td&gt;很小，推荐&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;no&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;交给操作系统决定（通常约 30 秒）&lt;/td&gt;
&lt;td&gt;最多丢约 30 秒&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;绝大多数场景选 &lt;code&gt;everysec&lt;/code&gt; 就对了&amp;lt;/span&amp;gt;：性能损失可以忽略，最坏只丢 1 秒数据。只有对数据零容忍的金融类场景才考虑 &lt;code&gt;always&lt;/code&gt;，并且要接受吞吐量打折。&lt;/p&gt;
&lt;h3&gt;AOF 重写：日志不能无限长&lt;/h3&gt;
&lt;p&gt;命令流水越记越长，总不能把一条数据改了 100 次的 100 条命令全留着。Redis 有自动重写机制：当 aof 文件大小超过上次重写后大小的一定比例且达到最小体积时，后台进程会把当前数据用最精简的命令重新生成一份新文件，老的增量就扔掉了。相关配置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;auto-aof-rewrite-percentage 100   # aof 文件比上次重写后翻倍时触发重写
auto-aof-rewrite-min-size 64mb    # aof 文件小于 64MB 不触发重写
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;手动触发重写用 &lt;code&gt;BGREWRITEAOF&lt;/code&gt;。注意重写同样要 fork 子进程，资源开销和 BGSAVE 类似，不要在业务高峰期手动触发。&lt;/p&gt;
&lt;h2&gt;混合持久化：7.4 时代的默认最优解&lt;/h2&gt;
&lt;p&gt;RDB 和 AOF 不是二选一。从 Redis 4.0 开始就支持&lt;strong&gt;混合持久化&lt;/strong&gt;，Redis 7.4 里 AOF 的 base 文件本身就是 RDB 格式，等于天生在用混合模式，配置项是：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;aof-use-rdb-preamble yes    # 默认就是 yes，保持开启
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;它的逻辑是：AOF 重写时，先把当前全量数据以 RDB 二进制格式写成 base 文件，之后的写命令再以 AOF 文本格式追加为 incr 文件。恢复时先秒速载入 base，再重放少量增量命令。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;恢复速度接近 RDB，数据丢失窗口只有 AOF 的 1 秒&amp;lt;/span&amp;gt;，两头的好处都占了，这也是现在推荐的默认方案。&lt;/p&gt;
&lt;h2&gt;恢复流程：重启时 Redis 先读谁&lt;/h2&gt;
&lt;p&gt;当 RDB 和 AOF 同时存在时，重启的加载顺序是固定的：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;如果开启了 AOF（&lt;code&gt;appendonly yes&lt;/code&gt;），&lt;strong&gt;优先加载 AOF&lt;/strong&gt;（数据更新更全）&lt;/li&gt;
&lt;li&gt;没开 AOF 时，才加载 &lt;code&gt;dump.rdb&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;两者都没有，就以空数据库启动&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;验证恢复是否成功，进 &lt;code&gt;redis-cli&lt;/code&gt; 执行 &lt;code&gt;INFO persistence&lt;/code&gt;，重点看几个字段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;INFO persistence
# aof_enabled:1            是否开启 AOF
# aof_last_bgrewrite_status:ok    上次重写是否成功
# rdb_last_bgsave_status:ok       上次快照是否成功
# rdb_last_bgsave_time_sec:2      上次快照耗时
# loading:0                       1 表示正在加载数据，别催
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
从备份恢复数据时有个高频事故：把备份的 &lt;code&gt;dump.rdb&lt;/code&gt; 拷进 &lt;code&gt;dir&lt;/code&gt; 目录后直接启动，结果数据没回来——因为这台机器开着 AOF，Redis 优先读了旧的 AOF 文件，RDB 被无视了。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;恢复 RDB 备份前，必须先停掉 AOF 或删掉 appendonlydir&amp;lt;/span&amp;gt;，或者干脆用 AOF 文件做备份源。
:::&lt;/p&gt;
&lt;h2&gt;Docker 部署时的持久化要点&lt;/h2&gt;
&lt;p&gt;用 Docker 跑 Redis 时，持久化文件必须落在数据卷里，否则容器一删文件就没了。Compose 里这样写（完整三大数据库的 Compose 在 &lt;a href=&quot;/posts/database-docker-quickstart/&quot;&gt;《用 Docker 快速搭建三大数据库》&lt;/a&gt; 里）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  redis:
    image: redis:7.4
    container_name: redis
    restart: unless-stopped
    command: redis-server --appendonly yes --appendfsync everysec
    volumes:
      - redis_data:/data
    ports:
      - &quot;6379:6379&quot;

volumes:
  redis_data:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Redis 容器的工作目录（&lt;code&gt;dir&lt;/code&gt;）默认就是 &lt;code&gt;/data&lt;/code&gt;，所以 &lt;code&gt;dump.rdb&lt;/code&gt; 和 &lt;code&gt;appendonlydir&lt;/code&gt; 都会写进 &lt;code&gt;redis_data&lt;/code&gt; 卷。验证一下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec redis redis-cli BGSAVE
docker exec redis ls -la /data
# 能看到 dump.rdb 和 appendonlydir 目录，就说明落盘位置对了
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;还有个细节：宿主机上如果对卷目录做备份，记得把 &lt;code&gt;appendonlydir&lt;/code&gt; 整个目录一起拷走，只拷其中一个文件是恢复不出来的。&lt;/p&gt;
&lt;h2&gt;RDB 与 AOF 对比总表&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;RDB&lt;/th&gt;
&lt;th&gt;AOF&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;记录方式&lt;/td&gt;
&lt;td&gt;定时全量快照（二进制）&lt;/td&gt;
&lt;td&gt;逐条追加写命令（日志）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件体积&lt;/td&gt;
&lt;td&gt;小，紧凑&lt;/td&gt;
&lt;td&gt;较大（混合模式下显著缩小）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;恢复速度&lt;/td&gt;
&lt;td&gt;快&lt;/td&gt;
&lt;td&gt;较慢（混合模式下接近 RDB）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;最坏丢数据&lt;/td&gt;
&lt;td&gt;两次快照之间（可达数分钟）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;everysec&lt;/code&gt; 下最多 1 秒&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;对性能影响&lt;/td&gt;
&lt;td&gt;fork 时有短暂开销&lt;/td&gt;
&lt;td&gt;&lt;code&gt;everysec&lt;/code&gt; 下几乎无感&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件可读性&lt;/td&gt;
&lt;td&gt;二进制，不可读&lt;/td&gt;
&lt;td&gt;文本协议，肉眼可查&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合定位&lt;/td&gt;
&lt;td&gt;备份归档、灾备&lt;/td&gt;
&lt;td&gt;日常持久化主机制&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;三个场景的选型建议&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;纯缓存场景&lt;/strong&gt;（数据丢了可以从数据库重新加载）：只开 RDB 就够了，甚至可以全关持久化换取极致性能。判断标准就一条：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;数据丢光了业务能不能接受&amp;lt;/span&amp;gt;，能接受就别纠结。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;重要数据场景&lt;/strong&gt;（队列、计数、排行榜等丢了找不回）：AOF &lt;code&gt;everysec&lt;/code&gt; + 混合持久化打开，这是默认最优解，再配合 &lt;a href=&quot;/posts/database-backup-restore/&quot;&gt;《数据库备份与恢复全攻略》&lt;/a&gt; 里的定期备份策略。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;小内存机器&lt;/strong&gt;：留意 fork 的写时复制开销，数据量接近内存上限时快照可能把内存撑爆。用 &lt;code&gt;maxmemory&lt;/code&gt; 给 Redis 设个上限并留足余量，别让它吃满整机内存。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：怎么确认持久化真的在工作，而不是自我感觉良好？&lt;/strong&gt;
做一次最朴素的验证：往 Redis 里写一个带标记的键，执行 &lt;code&gt;BGSAVE&lt;/code&gt; 等它完成，确认 &lt;code&gt;dump.rdb&lt;/code&gt; 的修改时间是刚刚；然后重启 Redis（Docker 就 &lt;code&gt;docker restart redis&lt;/code&gt;），再 &lt;code&gt;GET&lt;/code&gt; 那个键，能读回来才算数。开启 AOF 的则检查 &lt;code&gt;appendonlydir&lt;/code&gt; 里 incr 文件的更新时间是否在持续变化。这套动作建议每次改完持久化配置都做一遍，不要等事故来验证。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：&lt;code&gt;INFO persistence&lt;/code&gt; 里 &lt;code&gt;rdb_last_bgsave_status&lt;/code&gt; 是 err 怎么办？&lt;/strong&gt;
十有八九是 &lt;code&gt;dir&lt;/code&gt; 目录没写权限或磁盘满了。先 &lt;code&gt;df -h&lt;/code&gt; 看磁盘，再确认 Redis 进程对 &lt;code&gt;dir&lt;/code&gt; 目录可写，Docker 部署则检查卷的挂载是否正常。修好后手动 &lt;code&gt;BGSAVE&lt;/code&gt; 一次验证。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：fork 时出现卡顿，日志里有 THP 警告怎么办？&lt;/strong&gt;
日志里若出现 &lt;code&gt;WARNING you have Transparent Huge Pages (THP) support enabled&lt;/code&gt;，大内存页会放大 fork 的复制成本，建议在宿主机关闭：&lt;code&gt;echo never &amp;gt; /sys/kernel/mm/transparent_hugepage/enabled&lt;/code&gt;（Docker 部署时改的是宿主机，不是容器里）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：AOF 文件损坏了（断电写一半）怎么恢复？&lt;/strong&gt;
Redis 自带修复工具：&lt;code&gt;redis-check-aof --fix appendonlydir&lt;/code&gt;，它会截断到最后一条完整命令，代价是丢失尾部少量数据。操作前先把整个 &lt;code&gt;appendonlydir&lt;/code&gt; 备份一份再修。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：可以完全关掉持久化吗？&lt;/strong&gt;
可以：&lt;code&gt;save &quot;&quot;&lt;/code&gt; 清空所有快照规则且不开 AOF，就是纯内存模式。只适合纯缓存且数据源在别处（比如 MySQL）的场景，&lt;a href=&quot;/posts/redis-use-cases/&quot;&gt;《Redis 应用场景实战》&lt;/a&gt; 里缓存架构正是这个思路。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：备份时应该拷 RDB 还是 AOF？&lt;/strong&gt;
日常自动备份拷 RDB 文件最方便（单文件、体积小）；AOF 适合做「准实时」的本地持久化底线。两者不冲突：开 AOF 保底线，定时把 RDB 拷走做异地备份。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;RDB 是照片，AOF 是流水账，混合持久化是「照片打底＋流水账补增量」。Redis 7.4 的推荐姿势很明确：&lt;strong&gt;开启 AOF、刷盘选 everysec、混合持久化保持默认开启，再定时把 RDB 文件备份走&lt;/strong&gt;。持久化解决的是单机重启不丢数据，但机器本身坏了还是没辙——那就要靠下一篇应用实战之后讲的主从复制与备份策略来兜底了。&lt;/p&gt;
</content:encoded></item><item><title>Redis 应用场景实战：缓存、计数器与分布式锁</title><link>https://www.anexns.cloudns.org/posts/redis-use-cases/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/redis-use-cases/</guid><description>把 Redis 用到业务里：缓存的读写模式与穿透、击穿、雪崩三大经典问题，计数器与限流的原子实现，以及分布式锁从 SET NX 到 Redlock 的正确姿势，全部配可运行的命令与代码。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;写在前面：Redis 在业务里到底干哪几件事&lt;/h2&gt;
&lt;p&gt;前两篇讲了 Redis 的&lt;a href=&quot;/posts/redis-data-types/&quot;&gt;数据类型&lt;/a&gt;和&lt;a href=&quot;/posts/redis-persistence/&quot;&gt;持久化&lt;/a&gt;，属于「兵器谱」。这一篇讲实战打法：把 Redis 放进真实业务系统里，它最高频的四种用法是——&lt;strong&gt;缓存、计数器、限流、分布式锁&lt;/strong&gt;。这四件事有一个共同点：都依赖 Redis 的单线程原子执行特性，所有命令排队一条一条来，天然没有并发竞态，这是用普通数据库很难做到的。&lt;/p&gt;
&lt;p&gt;本文每种用法都给完整的命令序列，关键处附伪代码级别的实现思路，看完就能往自己的项目里搬。开始之前先明确一条边界：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Redis 是加速层和协调层，不是数据的最终归宿&amp;lt;/span&amp;gt;。重要数据该落 PostgreSQL/MySQL 还是要落，Redis 挂了业务可以降级，不能直接崩。&lt;/p&gt;
&lt;h2&gt;缓存：Cache-Aside 是最主流的读写模式&lt;/h2&gt;
&lt;p&gt;缓存的读法大同小异，区别在写的时候怎么处理。最常用的是 &lt;strong&gt;Cache-Aside（旁路缓存）&lt;/strong&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;读流程：
  1. 先查 Redis，命中 → 直接返回
  2. 未命中 → 查数据库 → 把结果写入 Redis（带过期时间）→ 返回

写流程：
  1. 先更新数据库
  2. 再删除 Redis 里对应的缓存键（注意：是删除，不是更新）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;为什么写的时候删而不是改？因为缓存里的值往往是多表拼出来的结果，写方很难算出新值，删掉让下一次读去回填，逻辑最简单也最不容易出错。对应的命令非常朴素：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;GET cache:article:9527                  # 查缓存
# 未命中，查数据库后回填：
SET cache:article:9527 &apos;{&quot;id&quot;:9527,&quot;title&quot;:&quot;...&quot;}&apos; EX 3600
# 文章被修改后：
DEL cache:article:9527
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;过期时间不要全设成一样的值，建议在基础值上加随机抖动，比如 &lt;code&gt;3600 + random(0, 300)&lt;/code&gt; 秒，原因在下面的雪崩一节会讲到。&lt;/p&gt;
&lt;h3&gt;缓存三大经典问题&lt;/h3&gt;
&lt;p&gt;这是面试和实战都绕不开的三个坑，务必分清：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;问题&lt;/th&gt;
&lt;th&gt;现象&lt;/th&gt;
&lt;th&gt;典型解法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;穿透&lt;/td&gt;
&lt;td&gt;查一个&lt;strong&gt;根本不存在&lt;/strong&gt;的数据，缓存永远不命中，每次都打到数据库&lt;/td&gt;
&lt;td&gt;缓存空值（短过期）；布隆过滤器拦截&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;击穿&lt;/td&gt;
&lt;td&gt;某个&lt;strong&gt;热点键过期瞬间&lt;/strong&gt;，大量请求同时涌向数据库回填&lt;/td&gt;
&lt;td&gt;互斥锁回填；热点数据不过期＋后台刷新&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;雪崩&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;大批键同时过期&lt;/strong&gt;（或 Redis 宕机），请求洪峰压垮数据库&lt;/td&gt;
&lt;td&gt;过期时间加随机抖动；Redis 高可用；限流降级&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;穿透的解法里「缓存空值」最简单直接：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 查数据库确认文章不存在时，也往缓存里写一个空标记，过期时间短一点
SET cache:article:99999 &quot;&quot; EX 60
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;下次再查这个 ID，命中空标记就直接返回「不存在」，不再惊动数据库。缺点是会短暂缓存「不存在」状态，如果数据在这 60 秒内被创建了，会读到错误的空结果——大多数业务可以接受，不能接受就上布隆过滤器。&lt;/p&gt;
&lt;p&gt;击穿的互斥锁回填，就是用一个短命的锁保证同一时刻只有一个请求去查数据库：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;回填逻辑：
  抢到锁（SET lock:article:9527 1 NX EX 10）→ 查库 → 写缓存 → 释放锁
  没抢到锁 → 睡 50ms → 重新读缓存（大概率已被回填）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这个锁的实现细节正是本文第四节要讲的分布式锁，先有个印象即可。&lt;/p&gt;
&lt;p&gt;:::warning
缓存雪崩还有一种更惨的版本：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Redis 整个宕机&amp;lt;/span&amp;gt;。再好的过期策略也救不了这种情况，必须靠主从＋哨兵或集群做高可用（见 &lt;a href=&quot;/posts/database-replication-basics/&quot;&gt;《主从复制入门》&lt;/a&gt; 的思路），应用层再加一层本地限流兜底，不要把全部身家押在单点 Redis 上。
:::&lt;/p&gt;
&lt;h2&gt;计数器：INCR 的原子性就是一切&lt;/h2&gt;
&lt;p&gt;浏览量、点赞数、库存扣减、短信发送次数……凡是「并发下绝对不能算错」的计数，都是 &lt;code&gt;INCR&lt;/code&gt; 家族的主场。因为 Redis 单线程执行命令，&lt;code&gt;INCR&lt;/code&gt; 的「读-改-写」是不可分割的一步，不存在两个请求读到同一个旧值的问题。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;INCR views:article:9527              # 文章浏览量 +1
INCRBY stock:sku:1001 -1             # 库存扣 1（负数即减）
HINCRBY user:1001 likes 1            # Hash 字段计数：用户获赞数
ZINCRBY rank:hot 1 article:9527      # 热度榜分数 +1，顺带维护排行榜
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;一个经典的计数翻车场景是库存超卖。用数据库做扣减要写 &lt;code&gt;UPDATE ... WHERE stock &amp;gt; 0&lt;/code&gt; 并检查影响行数，用 Redis 则要先判断再扣减，两步之间必须保证原子——这时要用 Lua 脚本把「判断＋扣减」打包成一个原子操作：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- stock.lua：库存大于 0 才扣减，返回 1 表示成功
local stock = tonumber(redis.call(&apos;GET&apos;, KEYS[1]))
if stock and stock &amp;gt; 0 then
    redis.call(&apos;DECR&apos;, KEYS[1])
    return 1
end
return 0
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;EVAL &quot;$(cat stock.lua)&quot; 1 stock:sku:1001
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Redis 执行 Lua 脚本期间不会插入其他命令，这是它在业务代码里最重要的用法之一：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;凡是「先查再改」的复合逻辑，都应该用 Lua 打包成原子操作&amp;lt;/span&amp;gt;，别在应用层分两步发命令。&lt;/p&gt;
&lt;h2&gt;限流：固定窗口与滑动窗口&lt;/h2&gt;
&lt;p&gt;接口限流（比如每个用户每分钟最多 60 次请求）用计数器就能实现，最简单的是固定窗口：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;INCR limit:user:1001:202611151030     # 键名带分钟时间戳
EXPIRE limit:user:1001:202611151030 60  # 首次创建时设置过期（需判断返回值，只在 INCR 返回 1 时设）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;INCR&lt;/code&gt; 返回 1 说明是本分钟第一次请求，这时才 &lt;code&gt;EXPIRE&lt;/code&gt;；返回值超过 60 就拒绝。固定窗口的问题是临界突刺：11:30:59 和 11:31:01 两秒内可以各打满 60 次。要求更平滑时用滑动窗口，拿 ZSet 实现：成员是请求 ID，分数是请求时间戳。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 一次请求进来时的滑动窗口检查（同样建议用 Lua 打包）
ZREMRANGEBYSCORE limit:api:user1001 0 &amp;lt;一分钟前的时间戳毫秒&amp;gt;   # 清掉窗口外的旧记录
ZCARD limit:api:user1001                                        # 窗口内已有多少次
ZADD limit:api:user1001 &amp;lt;当前时间戳毫秒&amp;gt; &amp;lt;请求唯一ID&amp;gt;             # 记下本次
EXPIRE limit:api:user1001 60
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;窗口内计数小于阈值才放行并记录，超了直接拒绝。这个方案精确但每个用户要维护一个 ZSet，量级很大时可以退回固定窗口或令牌桶，按业务取舍。&lt;/p&gt;
&lt;h2&gt;分布式锁：SET NX 只是起点&lt;/h2&gt;
&lt;p&gt;多台应用服务器同时跑定时任务、扣库存、生成订单号时，需要一把跨进程的锁。Redis 分布式锁的标准实现是一条命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;SET lock:order:create &amp;lt;随机令牌&amp;gt; NX PX 30000
# NX：键不存在才设置成功（抢到锁）
# PX 30000：锁 30 秒后自动过期，防止持锁进程崩溃导致死锁
# 值必须是随机令牌（如 UUID），释放时要验证
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;释放锁&lt;strong&gt;不能直接 DEL&lt;/strong&gt;：万一自己的锁已经过期、被别人抢走了，你 DEL 删掉的是别人的锁。必须「验证令牌是自己的才删」，这一步也要用 Lua 保证原子：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;-- unlock.lua：令牌一致才删除
if redis.call(&apos;GET&apos;, KEYS[1]) == ARGV[1] then
    return redis.call(&apos;DEL&apos;, KEYS[1])
end
return 0
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;EVAL &quot;$(cat unlock.lua)&quot; 1 lock:order:create &amp;lt;你的随机令牌&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;分布式锁的三个高频错误，逐个避开：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;忘记设过期时间&amp;lt;/span&amp;gt;：持锁进程一崩，锁永远不释放，全系统卡死&lt;/li&gt;
&lt;li&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;过期时间比业务执行时间短&amp;lt;/span&amp;gt;：业务还没跑完锁先过期，第二个人又进来，锁形同虚设。对策是估足时长，或用看门狗机制定期续期（Java 的 Redisson 就是这么做的）&lt;/li&gt;
&lt;li&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;释放时不验令牌&amp;lt;/span&amp;gt;：删掉别人的锁，并发问题在低概率下复现，最难查&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;至于要不要上 Redlock（多节点版锁算法）：社区争论多年，工程界的普遍共识是——普通业务用单节点锁＋合理过期时间完全够用；对正确性极端敏感的场景（如金融交易），应该用数据库或 ZooKeeper/etcd 这类强一致工具，而不是在锁算法上较劲。Redis 锁的定位是「高性能的尽力协调」，心里要有数。&lt;/p&gt;
&lt;h2&gt;综合案例：一个内容站怎么把四种用法拼起来&lt;/h2&gt;
&lt;p&gt;把上面的零件拼到一个真实系统里，画面就完整了。假设是一个文章站：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;文章详情页&lt;/strong&gt;走缓存：&lt;code&gt;cache:article:&amp;lt;id&amp;gt;&lt;/code&gt; 存 JSON，过期 1 小时加随机抖动，编辑文章时删键失效，防穿透用空值缓存，防击穿用互斥锁回填&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;浏览量和点赞&lt;/strong&gt;走计数器：&lt;code&gt;INCR views:article:&amp;lt;id&amp;gt;&lt;/code&gt;、&lt;code&gt;HINCRBY&lt;/code&gt; 维护作者获赞总数，每小时把增量批量回写一次 PostgreSQL 做持久账本&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;热度排行榜&lt;/strong&gt;顺手用计数器的数据：每次浏览同时 &lt;code&gt;ZINCRBY rank:hot 1 article:&amp;lt;id&amp;gt;&lt;/code&gt;，首页取 &lt;code&gt;ZREVRANGE rank:hot 0 9&lt;/code&gt; 就是实时热榜，不用单独跑统计任务&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;接口限流&lt;/strong&gt;走滑动窗口：发评论接口限制每用户每分钟 5 次，ZSet 方案精确拦截刷评论的脚本&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;定时任务防重&lt;/strong&gt;走分布式锁：三台应用服务器都部署了「每小时生成报表」的定时任务，用 &lt;code&gt;SET lock:job:report &amp;lt;令牌&amp;gt; NX PX 600000&lt;/code&gt; 保证只有一个实例真正执行&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;可以看到，四种用法不是孤立的知识点，而是同一套原子能力在不同位置的复用。真实项目里 Redis 的键会成千上万，务必从一开始就执行统一的键命名规范（业务前缀＋冒号分层，见 &lt;a href=&quot;/posts/redis-data-types/&quot;&gt;数据类型&lt;/a&gt; 那篇），否则后期治理成本会很高。另外记得给每类键都想清楚过期策略：缓存键必须有过期，计数键看业务决定，锁键必须有过期——没有过期策略的键，最终都会变成内存里的垃圾。&lt;/p&gt;
&lt;h2&gt;四大场景选型速查&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;核心命令/结构&lt;/th&gt;
&lt;th&gt;关键要点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;缓存&lt;/td&gt;
&lt;td&gt;String + &lt;code&gt;EX&lt;/code&gt; 过期&lt;/td&gt;
&lt;td&gt;Cache-Aside、删缓存而非改缓存、过期加抖动&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;计数器&lt;/td&gt;
&lt;td&gt;&lt;code&gt;INCR&lt;/code&gt; / &lt;code&gt;HINCRBY&lt;/code&gt; / &lt;code&gt;ZINCRBY&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;原子性免加锁；复合逻辑用 Lua&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;限流&lt;/td&gt;
&lt;td&gt;计数器或 ZSet 滑动窗口&lt;/td&gt;
&lt;td&gt;固定窗口简单但有突刺，滑动窗口精确但成本高&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;分布式锁&lt;/td&gt;
&lt;td&gt;&lt;code&gt;SET NX PX&lt;/code&gt; + Lua 解锁&lt;/td&gt;
&lt;td&gt;必须设过期、令牌验证、时长估足&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：缓存和数据库的数据最终会不一致，怎么办？&lt;/strong&gt;
Cache-Aside 本身就是最终一致模型：极端情况下（删缓存失败）会短暂不一致。工程上的补强手段是删缓存失败时重试或把键名发进消息队列异步删，再加上缓存本身有过期时间兜底，最长不一致时间就是过期时长。强一致场景不要用缓存，直接读库。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：&lt;code&gt;INCR&lt;/code&gt; 计数只存在 Redis 里，重启会丢吗？&lt;/strong&gt;
取决于持久化配置。浏览量这类丢一点无所谓的计数，丢就丢了；重要计数（如已售数量）建议定期把 Redis 的值回写数据库做对账，或者干脆以数据库为准、Redis 只做加速。这正是 &lt;a href=&quot;/posts/redis-persistence/&quot;&gt;《Redis 持久化》&lt;/a&gt; 里说的选型问题。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：Lua 脚本写错了会不会把 Redis 卡死？&lt;/strong&gt;
会。Lua 脚本执行期间主线程被独占，脚本里写死循环或大批量遍历能让整个 Redis 假死。脚本要短小、只做 O(1) 或小范围操作；失控时可以用 &lt;code&gt;SCRIPT KILL&lt;/code&gt; 终止（但若脚本已执行过写命令则杀不掉，只能 &lt;code&gt;SHUTDOWN NOSAVE&lt;/code&gt;，所以务必先在测试环境验证）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：分布式锁能完全替代数据库事务吗？&lt;/strong&gt;
不能。锁解决的是「同一时刻只有一个执行者」，事务解决的是「一组操作要么全成要么全败」，两回事。扣库存的完整方案通常是：分布式锁（或 Lua 原子扣减）防并发 + 数据库事务保落地 + 对账任务兜底。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Redis 的四大实战用法，本质上都在消费同一个特性：&lt;strong&gt;单线程带来的原子性&lt;/strong&gt;。缓存靠它防击穿，计数靠它防算错，限流靠它做精确窗口，分布式锁靠它做跨进程协调。用的时候守住三条纪律：缓存要有过期和降级、复合操作用 Lua 打包、锁必须带过期和令牌。至此 Redis 三篇（类型、持久化、实战）已经成环，下一篇转入通用话题——&lt;a href=&quot;/posts/database-backup-restore/&quot;&gt;《数据库备份与恢复全攻略》&lt;/a&gt;，把 PostgreSQL、MySQL、Redis 三家的备份方案一次讲清。&lt;/p&gt;
</content:encoded></item><item><title>Alist：把各家网盘聚合成一个文件站</title><link>https://www.anexns.cloudns.org/posts/selfhost-alist/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-alist/</guid><description>用 Alist 把本地目录、阿里云盘、百度网盘、夸克、OneDrive、WebDAV 等几十种存储挂载到同一个网页文件站里：Docker 部署、添加存储驱动、权限与访客控制、和 Cloudreve 的分工搭配。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说主线：文件散在七八个网盘里，是时候收拢了&lt;/h2&gt;
&lt;p&gt;很多人手里的文件是这样的：一部分在百度网盘，一部分在阿里云盘，工作文件在 OneDrive，老照片在移动硬盘挂着的本地目录里。每个网盘一个客户端、一个 App，找文件先要想「它到底在哪个盘里」。&lt;/p&gt;
&lt;p&gt;Alist 解决的就是这个问题：它是一个支持几十种存储的文件列表程序，把各家网盘、对象存储、WebDAV、本地目录统统挂载成一个统一的目录树，用一个网页（或 WebDAV）访问所有文件。它本身不存文件，只做「聚合与转发」，所以部署极轻，几十 MB 内存就能跑。&lt;/p&gt;
&lt;p&gt;要先分清 Alist 和上一篇 &lt;a href=&quot;/posts/selfhost-cloudreve/&quot;&gt;Cloudreve&lt;/a&gt; 的定位区别：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;Alist&lt;/th&gt;
&lt;th&gt;Cloudreve&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;定位&lt;/td&gt;
&lt;td&gt;聚合网关：把别处的存储拢到一起&lt;/td&gt;
&lt;td&gt;网盘本体：文件存在自己服务器上&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件存放&lt;/td&gt;
&lt;td&gt;各原始存储处，Alist 只转发&lt;/td&gt;
&lt;td&gt;自己的磁盘或对象存储&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;上传&lt;/td&gt;
&lt;td&gt;透传到对应存储&lt;/td&gt;
&lt;td&gt;存进自有空间&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;多用户/分享&lt;/td&gt;
&lt;td&gt;有，但偏轻量&lt;/td&gt;
&lt;td&gt;完整网盘式权限与分享&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合&lt;/td&gt;
&lt;td&gt;统一入口浏览、下载、挂载给播放器&lt;/td&gt;
&lt;td&gt;长期保存、私人文件托管&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一句话：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Alist 是「门」，Cloudreve 是「家」。&amp;lt;/span&amp;gt;门负责把散落各处的东西找出来，家负责安放真正重要的文件。两者搭配，是自建文件体系最常见的组合。&lt;/p&gt;
&lt;h2&gt;Docker Compose 部署&lt;/h2&gt;
&lt;p&gt;官方镜像 &lt;code&gt;xhofe/alist&lt;/code&gt;，部署非常简单：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  alist:
    image: xhofe/alist:latest
    container_name: alist
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
      - UMASK=022
    ports:
      - &quot;127.0.0.1:5244:5244&quot;
    volumes:
      - ./data:/opt/alist/data
      - /你的本地目录:/mnt/local:ro
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;本地目录建议以只读（&lt;code&gt;:ro&lt;/code&gt;）方式挂进去当一个存储源，避免误删。启动后取初始管理员密码：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker exec -it alist ./alist admin random   # 随机重置并打印管理员密码
# 或者查看首次启动日志里的初始密码
docker logs alist | grep -i password
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;登录后第一件事：改管理员密码、把站点地址（外部访问用的完整 URL，含 HTTPS 域名）在「设置 → 站点」里填对。Alist 生成的下载直链、WebDAV 地址都依赖这个设置，填错了外网就下不动文件。入口同样建议走 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager&lt;/a&gt; 反代并套上 HTTPS。&lt;/p&gt;
&lt;p&gt;:::warning
Alist 默认允许访客（Guest）浏览部分内容，公开部署前务必检查「设置 → 权限」和每个存储的可见范围。把私人网盘以访客可读的方式挂出去，等于把文件目录贴在公网上，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;曾经有大量公开 Alist 站点因为访客权限没关，被人当成免费资源站甚至翻出私人文件。&amp;lt;/span&amp;gt;
:::&lt;/p&gt;
&lt;h2&gt;添加存储：驱动体系怎么理解&lt;/h2&gt;
&lt;p&gt;Alist 的核心概念是「存储驱动」：每添加一个存储，就选一个驱动类型，填入该平台的授权信息，再指定挂载路径。比如把阿里云盘挂到 &lt;code&gt;/阿里云盘&lt;/code&gt;、百度网盘挂到 &lt;code&gt;/百度网盘&lt;/code&gt;、本地目录挂到 &lt;code&gt;/本地&lt;/code&gt;，最终呈现为一棵统一目录树。&lt;/p&gt;
&lt;p&gt;添加入口在「管理 → 存储 → 添加」。几类最常用的驱动：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;驱动&lt;/th&gt;
&lt;th&gt;授权方式&lt;/th&gt;
&lt;th&gt;注意点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;本地存储&lt;/td&gt;
&lt;td&gt;填容器内路径&lt;/td&gt;
&lt;td&gt;路径是容器内的，如 &lt;code&gt;/mnt/local&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;阿里云盘 Open&lt;/td&gt;
&lt;td&gt;扫码授权拿 refresh token&lt;/td&gt;
&lt;td&gt;官方开放接口，相对稳定&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;百度网盘&lt;/td&gt;
&lt;td&gt;Cookie 或 OAuth&lt;/td&gt;
&lt;td&gt;官方限速依旧存在，Alist 不绕过会员限速&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;夸克网盘&lt;/td&gt;
&lt;td&gt;Cookie&lt;/td&gt;
&lt;td&gt;Cookie 会过期，失效后重新获取&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;OneDrive&lt;/td&gt;
&lt;td&gt;OAuth 登录授权&lt;/td&gt;
&lt;td&gt;国际版与世纪互联版驱动不同，别选错&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;WebDAV&lt;/td&gt;
&lt;td&gt;地址 + 账号密码&lt;/td&gt;
&lt;td&gt;可以把 Cloudreve 的 WebDAV 再挂进来&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;S3 对象存储&lt;/td&gt;
&lt;td&gt;AK/SK + Bucket + Endpoint&lt;/td&gt;
&lt;td&gt;和 Cloudreve 的对象存储策略是同一批桶也能共用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个通用要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;挂载路径&lt;/strong&gt;就是目录名，用中文没问题，但给播放器、脚本调用时英文路径更少踩坑&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Web 代理 / WebDAV 代理&lt;/strong&gt;开关决定文件流量是否经过你的 VPS：开代理则下载走服务器带宽（能隐藏源站、但吃流量），关代理则 302 跳转到源站直链（省流量、速度看源站）&lt;/li&gt;
&lt;li&gt;驱动的令牌、Cookie 都会过期，某个存储突然打不开，先怀疑授权失效，重新授权即可，别急着删了重加&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;以本地存储为例，添加时驱动选「本地存储」，根文件夹路径填 &lt;code&gt;/mnt/local&lt;/code&gt;，挂载路径填 &lt;code&gt;/本地&lt;/code&gt;，保存后回到首页就能看到。云盘类驱动按官方文档的授权指引走一遍即可，各平台授权细节时有变化，以 Alist 官方文档对应驱动页为准，这里不写死容易过期的步骤。&lt;/p&gt;
&lt;h2&gt;权限、用户与访客控制&lt;/h2&gt;
&lt;p&gt;Alist 的权限分三层，公开部署前逐层确认：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;全局设置&lt;/strong&gt;：「设置」里关掉不需要的功能，如访客访问、文件上传、WebDAV 的写入权限按需开&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;用户管理&lt;/strong&gt;：除管理员外，给家人朋友单独建普通用户，限定其可见的根目录范围（Base Path），比如只能看 &lt;code&gt;/公开分享&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;存储级设置&lt;/strong&gt;：每个存储可单独设隐藏、只读、禁止下载等；敏感目录用「元信息（Meta）」给指定路径单独加密码&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;实用做法：自己用管理员账号全量访问；对外分享只给一个受限用户 + 带密码的 Meta 路径；访客（Guest）直接禁用或只放行一个公开目录。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;尤其注意搜索功能：Alist 的索引搜索会把文件名建进索引，公开站点开着搜索等于把全部文件名目录对外可查。&amp;lt;/span&amp;gt;自用站点无所谓，要对外就关掉搜索或限制范围。&lt;/p&gt;
&lt;h2&gt;进阶用法：直链、WebDAV 与给播放器供片&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;下载直链&lt;/strong&gt;：文件详情里可复制直链（带签名的 &lt;code&gt;/d/&lt;/code&gt; 路径），拿去给下载工具或当临时图床都行；签名有效期在设置里可调&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;WebDAV 输出&lt;/strong&gt;：地址是 &lt;code&gt;https://你的域名/dav&lt;/code&gt;，用 Alist 账号登录。这样所有挂载的存储又能被当成一个 WebDAV 挂进电脑、手机或播放器&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;给影音服务供片&lt;/strong&gt;：Jellyfin 等媒体服务器可以直接添加 Alist 的 WebDAV 或本地路径作为媒体库来源——如果你的影片本来就躺在某个网盘里，这条路能省掉「先下载到本地」的步骤。具体到影音库的搭建看 &lt;a href=&quot;/posts/selfhost-jellyfin/&quot;&gt;Jellyfin：私人影音库与硬件转码&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;流量策略上再强调一次：云盘文件经 Alist 代理下载时，流量走 VPS。1 TB 流量的小鸡别开全站代理下载大文件，一个月就能跑光；&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;自用浏览开直链跳转、给播放器供片时再按需开代理，是流量最省的用法。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;和 Cloudreve 怎么搭&lt;/h2&gt;
&lt;p&gt;两种典型组合，按需求二选一：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;组合方式&lt;/th&gt;
&lt;th&gt;做法&lt;/th&gt;
&lt;th&gt;适合&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Alist 挂 Cloudreve&lt;/td&gt;
&lt;td&gt;把 Cloudreve 的 WebDAV 作为一个存储加进 Alist&lt;/td&gt;
&lt;td&gt;想用一个入口看全部文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;并行使用&lt;/td&gt;
&lt;td&gt;Alist 管外部网盘聚合，Cloudreve 管自有文件&lt;/td&gt;
&lt;td&gt;权限边界清晰，最推荐&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一般推荐并行：重要文件进 Cloudreve 长期保存并纳入备份；各家网盘的存量文件用 Alist 统一浏览、下载、供片。两者都怕丢的只有 Cloudreve 那份，备份策略不用为网盘平台的存量文件操心。备份体系见 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移实战&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;添加存储后显示不出来或报错&lt;/strong&gt;
先看「管理 → 存储」里该条的状态信息，Alist 会给出驱动返回的错误。九成是授权失效（Cookie/token 过期）或根目录 ID 填错，重新授权即可。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;下载速度慢&lt;/strong&gt;
先分清是源站限速还是代理吃带宽：关掉该存储的 Web 代理试直链下载，若立刻变快，说明瓶颈在 VPS 带宽；若依旧慢，是网盘平台本身的限速，Alist 解决不了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;WebDAV 挂载失败或只能读&lt;/strong&gt;
检查三处：站点地址是否填了正确的外网 HTTPS 地址、用户是否开了 WebDAV 相关权限、反代是否放行了大文件请求体。部分客户端需要用应用密码或单独的 WebDAV 密码，按客户端报错信息对。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;容器重启后配置丢失&lt;/strong&gt;
&lt;code&gt;data&lt;/code&gt; 目录没挂载或挂错路径。确认 Compose 里 &lt;code&gt;./data:/opt/alist/data&lt;/code&gt; 存在且目录属主可写。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;升级后驱动失效&lt;/strong&gt;
大版本升级偶尔会调整驱动参数，升级前看一眼官方更新日志；升级后某个存储报错，进编辑页重新保存一次往往就能恢复，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;切忌手一抖把存储删了重加——分享链接和路径全会变。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Alist 的价值在于「收拢」：几十种存储一个入口，浏览、下载、WebDAV、供片全解决。部署十分钟，真正要用心的是权限——访客、搜索、用户范围这三处关好，它就是个安全好用的文件门户。搭配 Cloudreve 的「家」，自建文件体系就齐了：外面聚合、里面安放。&lt;/p&gt;
</content:encoded></item><item><title>自建服务备份与迁移实战</title><link>https://www.anexns.cloudns.org/posts/selfhost-backup-migration/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-backup-migration/</guid><description>给全部自建服务建立可落地的备份与迁移流程：盘点数据构成、Compose 项目打包脚本、数据库热备、restic 加密异地备份、定时任务，以及换服务器时从打包到改 DNS 的完整迁移清单。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说清楚：自建服务真正的资产是数据&lt;/h2&gt;
&lt;p&gt;容器删了可以重拉，镜像没了可以重下，Compose 文件可以重写——唯独数据丢了就是丢了。密码库、聊天记录、云盘文件、监控历史，这些才是自建服务真正的资产。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;备份不是可选项，而是自建服务从「玩具」变成「生产」的分界线。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;这一篇给出一套对前面所有服务都通用的方法：先盘点每个服务的数据构成，再写一个通用打包脚本，配上数据库热备和异地加密备份，最后是换服务器时的完整迁移流程。单个数据库自身的备份命令细节，在数据库系列的 &lt;a href=&quot;/posts/database-backup-restore/&quot;&gt;数据库备份与恢复全攻略&lt;/a&gt; 里有更深入的展开，这一篇侧重「多服务整体」的组织方法。&lt;/p&gt;
&lt;p&gt;主线：&lt;strong&gt;盘点 → 打包脚本 → 数据库热备 → 异地备份 → 定时执行 → 迁移实战 → 恢复演练&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;第一步：盘点每个服务的数据构成&lt;/h2&gt;
&lt;p&gt;任何一个 Docker 服务的数据都由四部分组成，备份时逐项对照，漏一项就可能恢复不完整：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;构成&lt;/th&gt;
&lt;th&gt;例子&lt;/th&gt;
&lt;th&gt;备份方式&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;配置文件&lt;/td&gt;
&lt;td&gt;docker-compose.yml、.env、反代配置&lt;/td&gt;
&lt;td&gt;直接打包&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据卷/绑定目录&lt;/td&gt;
&lt;td&gt;Cloudreve 数据、Vaultwarden 的 vw-data&lt;/td&gt;
&lt;td&gt;打包目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据库&lt;/td&gt;
&lt;td&gt;PostgreSQL、MySQL、MongoDB、SQLite 文件&lt;/td&gt;
&lt;td&gt;逻辑导出或停机打包&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;密钥与证书&lt;/td&gt;
&lt;td&gt;rsa_key、JWT 密钥、证书私钥&lt;/td&gt;
&lt;td&gt;随配置一起加密保存&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;特别提醒：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;只备份数据卷、不备份 Compose 和 .env，是最常见的翻车姿势&amp;lt;/span&amp;gt;——恢复时环境变量对不上，服务起来了也是一堆报错。把每个服务的整个项目目录（Compose + .env + 数据目录）当作一个整体来备份，就不会漏。&lt;/p&gt;
&lt;h2&gt;第二步：通用打包脚本&lt;/h2&gt;
&lt;p&gt;在服务器上建一个统一的备份脚本，把所有服务项目目录逐个打包到 &lt;code&gt;/backup&lt;/code&gt; 并按日期命名：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;#!/usr/bin/env bash
set -euo pipefail

BACKUP_DIR=&quot;/backup/$(date +%F)&quot;
mkdir -p &quot;$BACKUP_DIR&quot;

# 需要备份的服务项目目录，一行一个
PROJECTS=(
  &quot;/root/apps/vaultwarden&quot;
  &quot;/root/apps/cloudreve&quot;
  &quot;/root/apps/rocketchat&quot;
  &quot;/root/apps/freshrss&quot;
  &quot;/root/apps/komari&quot;
)

for p in &quot;${PROJECTS[@]}&quot;; do
  name=$(basename &quot;$p&quot;)
  echo &quot;==&amp;gt; backing up $name&quot;
  tar --exclude=&apos;*/cache&apos; --exclude=&apos;*/logs&apos; \
      -czf &quot;$BACKUP_DIR/${name}.tar.gz&quot; -C &quot;$(dirname &quot;$p&quot;)&quot; &quot;$name&quot;
done

echo &quot;done: $BACKUP_DIR&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意脚本里排除了 cache 和 logs 这类可再生目录，能显著减小体积。但有个前提问题：&lt;strong&gt;正在运行的服务直接打包数据目录，可能把数据库文件拷到写入一半的状态&lt;/strong&gt;。处理办法按数据库类型分：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;在线打包是否安全&lt;/th&gt;
&lt;th&gt;推荐做法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;SQLite&lt;/td&gt;
&lt;td&gt;有风险&lt;/td&gt;
&lt;td&gt;先用 &lt;code&gt;.backup&lt;/code&gt; 命令热备出一致副本再打包&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;PostgreSQL / MySQL&lt;/td&gt;
&lt;td&gt;不安全&lt;/td&gt;
&lt;td&gt;用 pg_dump / mysqldump 逻辑导出&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MongoDB&lt;/td&gt;
&lt;td&gt;不安全&lt;/td&gt;
&lt;td&gt;mongodump，或短暂停机打包&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;纯文件（网盘、附件）&lt;/td&gt;
&lt;td&gt;基本安全&lt;/td&gt;
&lt;td&gt;直接打包，个别文件不一致可接受&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;SQLite 热备示例（Vaultwarden、FreshRSS 都适用）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec vaultwarden sqlite3 /data/db.sqlite3 &quot;.backup /data/db-backup.sqlite3&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;关系型数据库则把导出命令加进备份脚本，产物和项目包放在一起：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec postgres pg_dump -U postgres appdb &amp;gt; &quot;$BACKUP_DIR/appdb.sql&quot;
docker exec mysql mysqldump -u root -p&apos;密码&apos; appdb &amp;gt; &quot;$BACKUP_DIR/appdb.sql&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果服务能接受几分钟停机（比如深夜的个人服务），最省心的做法是备份前 &lt;code&gt;docker compose stop&lt;/code&gt;、打包完再 &lt;code&gt;up -d&lt;/code&gt;，一致性问题直接归零。个人自建服务大多能接受，优先选这个笨办法。&lt;/p&gt;
&lt;h2&gt;第三步：异地备份——本机留一份不算备份&lt;/h2&gt;
&lt;p&gt;备份只存在同一台 VPS 上，机器被回收、磁盘损坏、账号出问题时就一起没了。遵循经典的 &lt;strong&gt;3-2-1 原则&lt;/strong&gt;：至少 3 份副本、2 种介质、1 份异地。对个人自建服务，落地版本是：服务器本地一份 + 加密后传到对象存储或另一台机器一份。&lt;/p&gt;
&lt;p&gt;推荐用 &lt;strong&gt;restic&lt;/strong&gt; 做异地备份：自带加密、增量、去重，恢复也简单：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 初始化仓库（以 S3 兼容对象存储为例）
export AWS_ACCESS_KEY_ID=&quot;你的KEY&quot;
export AWS_SECRET_ACCESS_KEY=&quot;你的SECRET&quot;
export RESTIC_PASSWORD=&quot;仓库密码，务必另行保存&quot;
restic -r s3:s3.amazonaws.com/你的桶名 init

# 执行备份
restic -r s3:s3.amazonaws.com/你的桶名 backup /backup

# 查看与恢复
restic -r s3:s3.amazonaws.com/你的桶名 snapshots
restic -r s3:s3.amazonaws.com/你的桶名 restore latest --target /restore
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
restic 的仓库密码丢了，备份就等于一堆乱码，谁也解不开——这正是它安全的原理。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;RESTIC_PASSWORD 必须记在密码库里并另有一份离线记录&amp;lt;/span&amp;gt;，不要只存在服务器的环境变量里，服务器没了它也跟着没了。
:::&lt;/p&gt;
&lt;p&gt;没有对象存储也可以用 rclone 传到网盘、或用 rsync 推到另一台 VPS，关键是「异地」和「自动」两条要占住。&lt;/p&gt;
&lt;h2&gt;第四步：定时执行与保留策略&lt;/h2&gt;
&lt;p&gt;把打包脚本挂到 cron，每天凌晨跑，成功失败都写日志：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;30 3 * * * /root/scripts/backup.sh &amp;gt;&amp;gt; /var/log/backup.log 2&amp;gt;&amp;amp;1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;保留策略建议：本地保留最近 7 天、异地保留最近 30 天，更老的自动清掉，避免磁盘被备份撑爆：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;find /backup -maxdepth 1 -type d -mtime +7 -name &quot;20*&quot; -exec rm -rf {} +
restic forget --keep-daily 30 --prune
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再进一步，把备份任务的成败纳入监控告警：脚本结尾按退出码发一条通知，连续失败必须有人知道。通知通道的搭法见 &lt;a href=&quot;/posts/selfhost-monitoring-alerts/&quot;&gt;监控告警实战：通知、值班与故障处理流程&lt;/a&gt;——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;静默失败是备份系统最危险的故障模式&amp;lt;/span&amp;gt;，跑了三个月才发现脚本一直在报错的惨剧非常常见。&lt;/p&gt;
&lt;h2&gt;第五步：迁移实战——换服务器的完整流程&lt;/h2&gt;
&lt;p&gt;迁移和「从备份恢复」本质是同一件事，所以流程直接复用备份体系：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;步骤&lt;/th&gt;
&lt;th&gt;动作&lt;/th&gt;
&lt;th&gt;要点&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;旧机停服务并做最后一次全量备份&lt;/td&gt;
&lt;td&gt;选业务低峰期&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;备份传到新机&lt;/td&gt;
&lt;td&gt;restic restore 或直接 scp&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;新机装 Docker、解开项目目录&lt;/td&gt;
&lt;td&gt;版本尽量与旧机一致&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;逐个 &lt;code&gt;docker compose up -d&lt;/code&gt; 并看日志&lt;/td&gt;
&lt;td&gt;先起数据库类，再起应用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;用 hosts 或内网地址逐个验证&lt;/td&gt;
&lt;td&gt;别急着改 DNS&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;6&lt;/td&gt;
&lt;td&gt;改 DNS 解析到新机 IP&lt;/td&gt;
&lt;td&gt;提前把 TTL 调小到 300&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7&lt;/td&gt;
&lt;td&gt;观察 24 小时，旧机保留一周再销毁&lt;/td&gt;
&lt;td&gt;出问题随时切回&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个迁移专属的坑：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;数据库大版本不能降级&lt;/strong&gt;：新机如果装了更低版本的数据库镜像，旧数据可能起不来。迁移时镜像 tag 先与旧机对齐，升级是另一件事，分开做。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;文件属主变了&lt;/strong&gt;：打包解包跨机器时注意属主，容器内服务用非 root 用户跑的（如 www-data），解包后属主不对会报权限错，按容器要求 chown 回来。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;证书不用搬&lt;/strong&gt;：反代的 HTTPS 证书在新机上重新申请即可，Nginx Proxy Manager 的配置本身在它的数据库里，如果 NPM 也在迁移名单里，记得它自己的数据目录也要备份，见 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager：所有自建服务的统一入口&lt;/a&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;各服务的备份要点速查&lt;/h2&gt;
&lt;p&gt;把本系列部署过的服务逐个过一遍，备份时各自的注意事项不同：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;服务&lt;/th&gt;
&lt;th&gt;核心数据&lt;/th&gt;
&lt;th&gt;备份注意&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Nginx Proxy Manager&lt;/td&gt;
&lt;td&gt;NPM 的数据库与证书目录&lt;/td&gt;
&lt;td&gt;丢了等于全部站点代理配置重配，优先级高&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Komari&lt;/td&gt;
&lt;td&gt;探针服务端数据库&lt;/td&gt;
&lt;td&gt;历史监控数据可丢，配置和节点列表别丢&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Uptime Kuma&lt;/td&gt;
&lt;td&gt;data 目录（SQLite）&lt;/td&gt;
&lt;td&gt;停机打包最稳，监控项重建很费时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cloudreve&lt;/td&gt;
&lt;td&gt;数据库 + 存储目录&lt;/td&gt;
&lt;td&gt;文件本体可能很大，考虑增量同步而非整包&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Vaultwarden&lt;/td&gt;
&lt;td&gt;vw-data 整个目录&lt;/td&gt;
&lt;td&gt;含 rsa_key，丢了密钥等于丢了库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Rocket.Chat&lt;/td&gt;
&lt;td&gt;MongoDB + uploads 卷&lt;/td&gt;
&lt;td&gt;数据库用 mongodump，附件单独打包&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Jellyfin&lt;/td&gt;
&lt;td&gt;配置与媒体库元数据&lt;/td&gt;
&lt;td&gt;媒体本体一般单独用同步/快照保护&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;FreshRSS&lt;/td&gt;
&lt;td&gt;data 目录&lt;/td&gt;
&lt;td&gt;SQLite 热备后打包即可&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;两个通用提醒：其一，&lt;strong&gt;备份前先给服务列一张「恢复顺序表」&lt;/strong&gt;——数据库和反代是其他服务的前置依赖，恢复时先起它们；其二，备份文件本身也要有校验，&lt;code&gt;sha256sum&lt;/code&gt; 生成校验和存好，异地传输后比对一次，避免传回来一个损坏的包还浑然不知：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /backup/2026-11-15
sha256sum *.tar.gz &amp;gt; SHA256SUMS
sha256sum -c SHA256SUMS   # 恢复前先验一遍
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;恢复演练：没验证过的备份不算备份&lt;/h2&gt;
&lt;p&gt;每季度至少做一次演练：随便挑一个服务（比如 FreshRSS），用上周的备份在一个临时目录里完整恢复出来，打开页面确认数据在、能登录。演练中发现的问题——缺文件、密码对不上、版本不兼容——在真正的灾难里只会更难处理。把演练步骤和结果简单记成文档，下次照着做就行。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. 备份包越来越大&lt;/strong&gt;
先查是不是把日志、缓存、转码临时文件打进去了，用 &lt;code&gt;--exclude&lt;/code&gt; 排除；再查数据库类服务是否忘了做日志轮转。&lt;code&gt;du -sh&lt;/code&gt; 逐层定位大头。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 定时备份没执行&lt;/strong&gt;
查 cron 服务是否在运行、脚本是否有执行权限、日志里报了什么。最常见的是脚本用了相对路径或依赖交互式环境变量，cron 环境里都没有——路径全写绝对路径，密钥写进脚本或单独的 env 文件。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 恢复后服务起不来，日志报数据库连接失败&lt;/strong&gt;
先确认 .env 里的数据库地址、密码和恢复的数据是不是同一套；再确认数据库容器先于应用完全就绪，应用连不上时加 &lt;code&gt;depends_on&lt;/code&gt; 也没用，要看日志等数据库打印 ready 再重启应用。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. restic 提示仓库被锁&lt;/strong&gt;
上次备份异常中断留下了锁，确认没有正在运行的 restic 进程后执行 &lt;code&gt;restic unlock&lt;/code&gt; 再重跑。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;备份这件事没有技术难点，难在成体系和坚持：盘点不漏项、脚本全自动、异地有一份、失败有告警、恢复练过手。做到这五条，你的全部自建服务就从「坏了会心疼」变成「坏了能重来」。迁移也不要怕，它就是一次计划内的恢复演练而已。&lt;/p&gt;
</content:encoded></item><item><title>Cloudreve：私人云盘部署与存储策略</title><link>https://www.anexns.cloudns.org/posts/selfhost-cloudreve/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-cloudreve/</guid><description>在自己的 VPS 上搭一个功能完整的私人网盘：Cloudreve 的 Docker 部署、存储策略（本地盘与对象存储）、离线下载、分享与 WebDAV，并讲清数据落在哪、怎么备份才不丢。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说主线：为什么要自建网盘，又为什么选 Cloudreve&lt;/h2&gt;
&lt;p&gt;公共网盘的问题人人都遇到过：限速、和谐、会员年年涨价，更麻烦的是重要文件放在别人服务器上，心里总不踏实。把网盘建在自己的 VPS 上，空间、速度、规则全都自己说了算，这也是整个自建服务里最能立刻提升幸福感的一类应用。&lt;/p&gt;
&lt;p&gt;同类产品里，Cloudreve 是国内开发者维护的开源网盘系统，特点很对自建用户的胃口：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;界面是熟悉的网盘式操作：上传、下载、文件夹、在线预览、分享链接，和公共网盘几乎无缝衔接&lt;/li&gt;
&lt;li&gt;支持多种存储后端：本地磁盘、S3 兼容对象存储、OneDrive 等，可以按文件类型分流&lt;/li&gt;
&lt;li&gt;自带离线下载（通过 Aria2）、WebDAV、多用户与用户组、文件直链等功能&lt;/li&gt;
&lt;li&gt;单容器部署，数据目录结构简单，迁移和备份都方便&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这一篇的主线是：&lt;strong&gt;先用 Docker 把 Cloudreve 跑起来，再把存储策略想清楚——哪些文件放本地盘、哪些放对象存储、备份怎么做&lt;/strong&gt;。部署本身只需要十分钟，存储策略才是决定这个网盘能用多久、用得安不安心的关键。&lt;/p&gt;
&lt;p&gt;部署前建议先看 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager：所有自建服务的统一入口&lt;/a&gt;，把反向代理和 HTTPS 证书准备好，网盘这种要传文件的服务尤其需要稳定的 HTTPS 入口。&lt;/p&gt;
&lt;h2&gt;部署前准备&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;项目&lt;/th&gt;
&lt;th&gt;建议&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;内存&lt;/td&gt;
&lt;td&gt;1 GB 以上&lt;/td&gt;
&lt;td&gt;Cloudreve 本体很轻，吃资源的是转码预览和缩略图&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;磁盘&lt;/td&gt;
&lt;td&gt;按需求规划&lt;/td&gt;
&lt;td&gt;本地存储策略下，网盘容量等于 VPS 磁盘容量&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;域名&lt;/td&gt;
&lt;td&gt;一个子域名，如 &lt;code&gt;pan.example.com&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;走 NPM 反代并签发证书&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;端口&lt;/td&gt;
&lt;td&gt;5212（默认）&lt;/td&gt;
&lt;td&gt;只绑定本机，经反代对外&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;先建好目录结构，把数据、配置和上传文件分开放：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p /opt/cloudreve/{data,uploads,avatar,aria2}
cd /opt/cloudreve
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;目录规划的思路是：&lt;code&gt;data&lt;/code&gt; 放数据库和配置，&lt;code&gt;uploads&lt;/code&gt; 是本地存储策略下的文件本体，之后备份时这两个目录就是全部身家，路径固定才好写备份脚本。&lt;/p&gt;
&lt;h2&gt;Docker Compose 部署&lt;/h2&gt;
&lt;p&gt;Cloudreve 官方镜像为 &lt;code&gt;cloudreve/cloudreve&lt;/code&gt;，配合 Aria2 实现离线下载。一份完整的 Compose 如下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  cloudreve:
    image: cloudreve/cloudreve:latest
    container_name: cloudreve
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
    ports:
      - &quot;127.0.0.1:5212:5212&quot;
    volumes:
      - ./data:/cloudreve/data
      - ./uploads:/cloudreve/uploads
      - ./avatar:/cloudreve/avatar
    depends_on:
      - aria2

  aria2:
    image: p3terx/aria2-pro:latest
    container_name: aria2
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
      - RPC_SECRET=改成你的RPC密钥
      - RPC_PORT=6800
    volumes:
      - ./aria2:/config
      - ./uploads:/downloads
    ports:
      - &quot;127.0.0.1:6800:6800&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动并查看初始管理员账号：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker logs cloudreve | head -30
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;首次启动时日志会打印随机生成的管理员邮箱和密码，形如：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[Info] Admin user name: admin@cloudreve.org
[Info] Admin password: xxxxxxxx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;务必第一时间登录并修改管理员密码，并把初始密码从日志里记下来后改掉&amp;lt;/span&amp;gt;——这组随机密码会一直留在容器日志里，谁能看日志谁就能进你的网盘。改完密码后到「管理面板 → 参数设置」里把站点地址改成你的正式域名，后面生成的分享链接才会正确。&lt;/p&gt;
&lt;p&gt;:::warning
Aria2 的 RPC 端口 6800 千万不要直接暴露到公网。RPC 接口一旦被扫到，别人可以借你的服务器下载任意文件甚至写文件。上面的 Compose 已经只绑定 127.0.0.1，Cloudreve 与 Aria2 在同一台机器上通信走本机地址即可；RPC_SECRET 也要设成足够随机的字符串。
:::&lt;/p&gt;
&lt;h2&gt;存储策略：这一篇的核心&lt;/h2&gt;
&lt;p&gt;Cloudreve 的「存储策略」决定上传的文件最终落在哪里。一个用户组绑定一个默认策略，不同用户组可以走不同策略。常见三种打法：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;策略&lt;/th&gt;
&lt;th&gt;文件落点&lt;/th&gt;
&lt;th&gt;优点&lt;/th&gt;
&lt;th&gt;缺点&lt;/th&gt;
&lt;th&gt;适合&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;本地存储&lt;/td&gt;
&lt;td&gt;VPS 磁盘&lt;/td&gt;
&lt;td&gt;速度最快、零额外成本&lt;/td&gt;
&lt;td&gt;容量受磁盘限制&lt;/td&gt;
&lt;td&gt;小文件、文档、常用资料&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;对象存储（S3 兼容）&lt;/td&gt;
&lt;td&gt;云厂商对象存储&lt;/td&gt;
&lt;td&gt;容量近乎无限、单价低&lt;/td&gt;
&lt;td&gt;上传下载多一跳、回源流量计费需看厂商&lt;/td&gt;
&lt;td&gt;大文件、影音、冷数据&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;从机/远程节点&lt;/td&gt;
&lt;td&gt;另一台服务器&lt;/td&gt;
&lt;td&gt;扩容灵活&lt;/td&gt;
&lt;td&gt;部署复杂&lt;/td&gt;
&lt;td&gt;多机玩家&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;本地存储策略配置&lt;/h3&gt;
&lt;p&gt;管理面板 → 存储策略 → 新建，选择「本地存储」，物理路径填写容器内的上传目录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/cloudreve/uploads
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意这里填的是&lt;strong&gt;容器内路径&lt;/strong&gt;，和 Compose 里挂载的 &lt;code&gt;./uploads:/cloudreve/uploads&lt;/code&gt; 对应。文件名保存方式建议选「根据 ID 命名」或保留原名按日期分目录，避免同名覆盖和中文路径编码问题。&lt;/p&gt;
&lt;h3&gt;对象存储策略配置&lt;/h3&gt;
&lt;p&gt;如果 VPS 磁盘只有几十 GB，又想存大量视频，可以把大文件策略指向 S3 兼容对象存储（各家云厂商都有，接口基本一致）。新建策略选「对象存储」，填入 Bucket、Endpoint、AccessKey、SecretKey，并打开「获取文件直链」相关选项。跨域（CORS）需要在存储桶侧放行你的网盘域名，否则浏览器直传会失败。&lt;/p&gt;
&lt;p&gt;一个实用的组合是：&lt;strong&gt;默认用户组走本地盘保证速度，给自己单独建一个「大文件」用户组走对象存储&lt;/strong&gt;。Cloudreve 支持上传时按策略分流的程度有限，更稳妥的做法是按用户组区分，或者干脆全量走对象存储、本地盘只作缓存。到底怎么选，结论很简单：&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;VPS 磁盘 ≥ 200 GB 就全本地，简单可靠；磁盘小又要存大文件，就本地放小文件、对象存储放大文件。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h3&gt;缩略图与预览&lt;/h3&gt;
&lt;p&gt;图片缩略图、视频封面会占用额外空间并吃 CPU。低配 VPS 可以在参数设置里调低缩略图质量，或者关闭视频封面生成。Office 文档预览依赖外部服务，自建场景下建议关掉在线编辑类功能，只保留图片、音视频和文本预览，稳定压倒一切。&lt;/p&gt;
&lt;h2&gt;离线下载与 WebDAV&lt;/h2&gt;
&lt;h3&gt;离线下载&lt;/h3&gt;
&lt;p&gt;在管理面板的参数设置里启用 Aria2，RPC 地址填 &lt;code&gt;http://aria2:6800/jsonrpc&lt;/code&gt;（同一 Compose 网络内用容器名互访），密钥与 Aria2 容器的 &lt;code&gt;RPC_SECRET&lt;/code&gt; 一致。启用后在网盘界面新建离线下载任务，粘贴 HTTP 或磁力链接即可，下载完成的文件会出现在网盘里。磁力链接需要 Aria2 容器能访问公网 UDP/TCP，家宽或受限网络下成功率会打折，这是协议本身的限制，不是配置错误。&lt;/p&gt;
&lt;h3&gt;WebDAV&lt;/h3&gt;
&lt;p&gt;Cloudreve 自带 WebDAV，在个人设置的「连接与应用」或管理面板中开启后，用网盘账号即可挂载：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;地址：https://pan.example.com/dav
账号：你的网盘邮箱
密码：账号密码（或应用密码，视版本设置）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;挂载到本地当网络驱动器用，配合 &lt;a href=&quot;/posts/selfhost-file-sync/&quot;&gt;文件同步实战：Syncthing 点对点同步与备份&lt;/a&gt; 可以组成「网盘归档 + 设备同步」的组合：重要资料丢进网盘长期保存，工作文件用 Syncthing 在设备间实时同步，各司其职。&lt;/p&gt;
&lt;h2&gt;分享、直链与多用户&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;分享链接&lt;/strong&gt;：可设密码、有效期和下载次数限制。给外人的链接一律设有效期，避免链接被转发后长期有效&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;文件直链&lt;/strong&gt;：适合给图片、文档生成可直接访问的 URL，当图床用也未尝不可，但流量走你自己的 VPS，注意带宽&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;多用户&lt;/strong&gt;：用户组可以分别限制容量、存储策略和功能权限。给家人朋友开账号时单独建组、限好容量，免得一个人把盘塞满&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;如果网盘要挂在公网长期开放注册，务必关闭自由注册或开启邮箱验证，自建服务的安全总原则在 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全加固：最小暴露与访问控制&lt;/a&gt; 里有系统讲法，这里只强调一点：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;网盘类应用一旦被陌生人注册利用，存违规文件、跑流量的锅全在服务器所有者身上。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;备份：网盘的命门&lt;/h2&gt;
&lt;p&gt;网盘里存的是文件本体，丢了没有任何服务商帮你找回。备份至少要覆盖三部分：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;内容&lt;/th&gt;
&lt;th&gt;位置&lt;/th&gt;
&lt;th&gt;备份方式&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;数据库与配置&lt;/td&gt;
&lt;td&gt;&lt;code&gt;./data&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;打包 + 异地保存&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本地文件本体&lt;/td&gt;
&lt;td&gt;&lt;code&gt;./uploads&lt;/code&gt;、&lt;code&gt;./avatar&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;rsync 增量同步&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Compose 与说明&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/opt/cloudreve&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;随配置一起打包&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;用对象存储策略的文件不在本地，备份压力小很多，但要注意对象存储侧也要开启版本控制或跨区复制，别把鸡蛋换个篮子继续只放一处。完整的备份节奏和迁移方法在 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移实战&lt;/a&gt; 里统一讲，Cloudreve 按那套流程走即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 每日增量同步文件本体到备份机
rsync -az --delete /opt/cloudreve/uploads/ backup@备份机:/backup/cloudreve/uploads/
# 每周打包一次配置与数据库
tar czf /backup/cloudreve-data-$(date +%F).tar.gz -C /opt/cloudreve data
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;上传大文件失败或超时&lt;/strong&gt;
多半卡在反向代理的请求体大小限制。NPM 里对应站点的 Advanced 配置加上 &lt;code&gt;client_max_body_size 0;&lt;/code&gt; 并调大超时；同时检查 Cloudreve 用户组里的单文件大小上限。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;分享链接打开是内网地址&lt;/strong&gt;
站点地址没改。管理面板参数设置里的站点 URL 必须是外网域名，改完后旧链接需要重新生成。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;离线下载一直等待&lt;/strong&gt;
按顺序查：Aria2 容器是否运行、RPC 密钥两边是否一致、Cloudreve 里填的 RPC 地址是否可达。&lt;code&gt;docker logs aria2&lt;/code&gt; 里能看到连接记录；磁力任务长时间没速度则多半是资源本身没做种者，换直链或种子文件。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;图片没有缩略图&lt;/strong&gt;
检查 &lt;code&gt;data&lt;/code&gt; 目录权限和缩略图生成开关；容器重建后第一次打开目录会现生成，稍等即可。若日志报内存不足，调低缩略图尺寸。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;升级后打不开&lt;/strong&gt;
先看日志确认是否在做数据库迁移，老版本跨度太大时不要一步升到最新，中间隔一个大版本逐级升；升级前务必先备份 &lt;code&gt;data&lt;/code&gt; 目录，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;数据库迁移失败又没备份，是自建网盘最惨烈的事故，没有之一。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Cloudreve 的部署只是十分钟的事，真正要花心思的是存储策略和备份：本地盘胜在速度和简单，对象存储胜在容量，两者按文件大小分工是最稳妥的组合；Aria2 和数据库备份是两个最容易被忽略、又最容易出大事的点，按上文收好。搭完这一篇，你的自建服务里就有了「家」——后面 Alist 聚合外部网盘、影音类服务找本地文件，都会和这个网盘打交道。&lt;/p&gt;
</content:encoded></item><item><title>文件同步实战：Syncthing 点对点同步与备份</title><link>https://www.anexns.cloudns.org/posts/selfhost-file-sync/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-file-sync/</guid><description>不经过任何第三方云，用 Syncthing 在电脑、手机和 VPS 之间点对点同步文件：Docker 部署、设备配对、文件夹类型与版本控制、冲突处理，并讲清「同步不等于备份」以及两者如何组合。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说主线：网盘之外，为什么还需要「同步」&lt;/h2&gt;
&lt;p&gt;网盘系列的 &lt;a href=&quot;/posts/selfhost-cloudreve/&quot;&gt;Cloudreve&lt;/a&gt; 解决的是「文件放在哪儿」，这一篇解决的是「文件怎么在设备之间自己流动」。日常场景是这样的：电脑上改了一份文档，希望手机立刻能看；相机拍的照片，希望回家自动躺进电脑硬盘；服务器上的配置，希望本地留一份随时能改。&lt;/p&gt;
&lt;p&gt;这类需求用网盘也能凑合，但要么靠手动上传下载，要么依赖公共云的同步客户端。Syncthing 是更纯粹的解法：开源、点对点（P2P）、不经过任何中心服务器，文件只在你自己的设备之间直连传输，加密、实时、多端，特别适合「我的文件只在我自己的设备之间转」这个场景。&lt;/p&gt;
&lt;p&gt;部署形态有两种，本文的主线是：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;每台要同步的设备（电脑、手机）装 Syncthing 客户端&lt;/li&gt;
&lt;li&gt;VPS 上用 Docker 再跑一个节点，作为 7×24 在线的「中转站 + 常驻副本」&lt;/li&gt;
&lt;li&gt;讲清文件夹类型、版本控制、忽略规则和冲突处理&lt;/li&gt;
&lt;li&gt;最后把最重要的概念钉死：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;同步不是备份，同步要配合版本控制和独立备份才安全。&amp;lt;/span&amp;gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;Syncthing 的工作方式&lt;/h2&gt;
&lt;p&gt;Syncthing 没有「云端」概念，每台设备是一个节点，节点之间靠设备 ID 互相识别、双向配对后才开始同步。文件变化会被切成块做增量传输，改一个大文件只传变化的部分。节点发现靠全球发现服务器和局域网广播，真正传文件时优先直连，连不上才走公共中继——中继只转发加密流量，看不到内容，但自建玩家也可以连中继都不用，只在自己的设备间组网。&lt;/p&gt;
&lt;p&gt;几个关键概念先建立起来：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;概念&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;设备 ID&lt;/td&gt;
&lt;td&gt;每台设备一串唯一 ID，配对靠它，相当于「手机号」&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件夹&lt;/td&gt;
&lt;td&gt;一个同步单元，有自己的 ID、路径和同步类型&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件夹类型&lt;/td&gt;
&lt;td&gt;发送与接收 / 仅发送 / 仅接收，决定数据流向&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;版本控制&lt;/td&gt;
&lt;td&gt;文件被覆盖或删除时保留历史版本，是防误删的关键&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;忽略规则&lt;/td&gt;
&lt;td&gt;&lt;code&gt;.stignore&lt;/code&gt; 文件，排除缓存、临时文件等不想同步的内容&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;VPS 节点：Docker 部署&lt;/h2&gt;
&lt;p&gt;官方镜像 &lt;code&gt;syncthing/syncthing&lt;/code&gt;。VPS 节点的作用是常驻在线：电脑关机、手机离网时，文件先同步到 VPS 攒着，其他设备上线再取走，不用等两台设备同时在线。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  syncthing:
    image: syncthing/syncthing:latest
    container_name: syncthing
    hostname: vps-node
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
      - PUID=1000
      - PGID=1000
    ports:
      - &quot;127.0.0.1:8384:8384&quot;     # Web 管理界面，只绑本机走反代
      - &quot;22000:22000/tcp&quot;         # 同步传输（TCP）
      - &quot;22000:22000/udp&quot;         # 同步传输（QUIC）
      - &quot;21027:21027/udp&quot;         # 局域网发现，公网 VPS 可不开
    volumes:
      - ./config:/var/syncthing/config
      - ./sync:/var/syncthing/sync
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;22000&lt;/code&gt; 是设备间传文件的端口，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;必须对公网放行&amp;lt;/span&amp;gt;（或至少对你其他设备所在网络放行），否则只能绕中继，速度慢且不稳定；它传的是加密流量，暴露本身没有数据泄露风险&lt;/li&gt;
&lt;li&gt;&lt;code&gt;8384&lt;/code&gt; 管理界面只绑 127.0.0.1，通过 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager&lt;/a&gt; 反代出来并套 HTTPS&lt;/li&gt;
&lt;li&gt;同步目录挂在 &lt;code&gt;./sync&lt;/code&gt; 下，每个同步文件夹在里面建一个子目录，路径固定方便备份&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;启动后打开管理界面，第一件事是给 Web 界面设账号密码（设置 → 常规 → GUI 认证），然后记下本机设备 ID（操作 → 显示 ID），配对要用。&lt;/p&gt;
&lt;h2&gt;客户端安装与设备配对&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Windows / macOS / Linux&lt;/strong&gt;：官网下载，或用包管理器安装；想要开机自启和托盘图标，Windows 可用 SyncTrayzor 这类官方推荐的封装&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Android&lt;/strong&gt;：官方 App（应用商店或 F-Droid），注意给足后台运行和存储权限，否则同步会断断续续&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;iOS&lt;/strong&gt;：没有官方客户端，有第三方付费应用（如 Möbius Sync），体验尚可但不如安卓原生顺畅，这是选设备时要提前知道的现实&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;配对流程在任意一端操作即可：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;在 VPS 管理界面点「添加远程设备」，填入电脑的设备 ID，给它起个名&lt;/li&gt;
&lt;li&gt;电脑端会弹出新设备请求，确认接受&lt;/li&gt;
&lt;li&gt;反过来在电脑端也能看到 VPS 已配对——双向确认过才算配对成功&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;配对完成后，再共享文件夹：选中文件夹 → 编辑 → 共享 → 勾选要同步到的设备。对方界面会弹出「新文件夹」邀请，选好本地存放路径再接受。第一次全量同步大文件夹时耐心等索引和传输完成，状态显示「已同步」才算落地。&lt;/p&gt;
&lt;h2&gt;文件夹类型：同步方向要想清楚&lt;/h2&gt;
&lt;p&gt;这是最容易配置错、又最重要的一组设置：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;行为&lt;/th&gt;
&lt;th&gt;典型用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;发送与接收&lt;/td&gt;
&lt;td&gt;双向同步，任何一端改动都互相同步&lt;/td&gt;
&lt;td&gt;工作文档、多设备协作目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;仅发送&lt;/td&gt;
&lt;td&gt;本端改动推出去，不接受对端改动&lt;/td&gt;
&lt;td&gt;手机相册 → 电脑/VPS 单向归档&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;仅接收&lt;/td&gt;
&lt;td&gt;只收对端改动，本端修改会被对端版本覆盖&lt;/td&gt;
&lt;td&gt;VPS 上的分发目录、镜像副本&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;两个经典配置：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;手机相册&lt;/strong&gt;：手机端设「仅发送」，VPS 端「仅接收」。照片只流向服务器，手机上删照片不会把服务器上的删掉（配合下面要讲的版本控制更稳）&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;工作中转目录&lt;/strong&gt;：所有设备「发送与接收」，哪台设备改了都自动散布到其他设备&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
「仅接收」文件夹里手动改了文件，Syncthing 会认为本地版本与全局不一致并显示「本地新增」，下次同步可能被覆盖。只读归档目录就只让它收，不要在里面直接编辑；要改文件，去源头设备上改。
:::&lt;/p&gt;
&lt;h2&gt;版本控制：防误删的保险丝&lt;/h2&gt;
&lt;p&gt;同步最大的风险是「错误也会被同步」：在一台设备上误删或误改，全网设备一起遭殃。Syncthing 的版本控制（文件夹 → 高级设置 → 文件版本控制）就是保险丝，被覆盖、被删除的文件会先挪进 &lt;code&gt;.stversions&lt;/code&gt; 目录留档。&lt;/p&gt;
&lt;p&gt;四种模式：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;模式&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;th&gt;建议&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;无版本控制&lt;/td&gt;
&lt;td&gt;直接覆盖删除&lt;/td&gt;
&lt;td&gt;只用于纯缓存类目录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;回收站式&lt;/td&gt;
&lt;td&gt;旧版本移到 .stversions，可设保留天数&lt;/td&gt;
&lt;td&gt;通用首选，如保留 30 天&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;简单版本控制&lt;/td&gt;
&lt;td&gt;按数量保留最近 N 个版本&lt;/td&gt;
&lt;td&gt;文档类目录，保留 5–10 个&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;交错版本控制&lt;/td&gt;
&lt;td&gt;按时间密度保留多个时间点的版本&lt;/td&gt;
&lt;td&gt;重要长期目录&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;给 VPS 节点的工作目录开「回收站式、保留 30 天」是性价比最高的默认：多占一点磁盘，换误删后一个月内可回滚。注意 &lt;code&gt;.stversions&lt;/code&gt; 本身不参与同步，它是每台设备本地的留档，所以常开机的 VPS 节点留档最可靠。&lt;/p&gt;
&lt;h2&gt;忽略规则与冲突处理&lt;/h2&gt;
&lt;p&gt;不想同步的东西用文件夹根目录下的 &lt;code&gt;.stignore&lt;/code&gt; 排除，一行一个模式：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;(?d)Thumbs.db
(?d).DS_Store
*.tmp
~$*
node_modules
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;(?d)&lt;/code&gt; 表示「如果对端删除了它，本地也允许删」，适合缓存类文件。注意：&lt;code&gt;.stignore&lt;/code&gt; 本身可以作为普通文件同步到各端，保持各端规则一致，省得一台一台改。&lt;/p&gt;
&lt;p&gt;冲突文件是双向同步的日常：两台设备离线时改了同一个文件，重连后 Syncthing 会保留一份胜出版本，另一份改名为 &lt;code&gt;文件名.sync-conflict-日期-设备.后缀&lt;/code&gt; 放在旁边。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;冲突文件不会自动合并，也不会有人提醒你&amp;lt;/span&amp;gt;，重要目录要定期搜一下 &lt;code&gt;sync-conflict&lt;/code&gt; 关键字手动处理，养成习惯能避免「我改的那版到底去哪了」的灵异事件。&lt;/p&gt;
&lt;h2&gt;同步不等于备份：怎么组合才完整&lt;/h2&gt;
&lt;p&gt;再强调一遍逻辑：同步保证的是「每台设备上都有一份」，但如果文件被勒索软件加密、被误删且过了版本保留期，所有副本会一起完蛋。完整的方案是分层：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Syncthing 负责流动&lt;/strong&gt;：文件在设备间实时同步，VPS 节点常驻兜底&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;版本控制负责回滚&lt;/strong&gt;：30 天内的误改误删能找回&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;独立备份负责兜底&lt;/strong&gt;：VPS 上的同步目录再按 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移实战&lt;/a&gt; 的节奏，定期打包同步到另一台机器或对象存储——这份备份不参与实时同步，灾难时它是最后一根稻草&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;另外 VPS 节点本身也别当成保险箱：它同时在线、同时可达，真出事时和其它节点是一根绳上的蚂蚱。独立的、离线的或异地的备份副本才是备份。安全边界和暴露面控制可以再看 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全加固&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;设备显示「已断开」&lt;/strong&gt;
按顺序查：22000 端口在 VPS 防火墙和云厂商安全组里是否放行（TCP+UDP）、设备 ID 是否填错、两端时间是否差太多。管理界面设备详情里能看到连接方式是直连还是中继，走中继且速度慢，基本就是端口没通。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;文件夹卡在「正在扫描」或同步不动&lt;/strong&gt;
大文件夹首次扫描要时间，先看 CPU 和进度百分比。若某文件一直报错，多为权限问题或文件名包含对端系统不支持的字符（如 Windows 不允许的 &lt;code&gt;:&lt;/code&gt;），改名即可。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;手机同步时好时坏&lt;/strong&gt;
安卓的电池优化在杀后台。给 Syncthing 关闭电池优化、允许后台运行，并打开「在 Wi-Fi 下同步」等条件设置里的开关；国产 ROM 还要在自启动管理里放行。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;磁盘被 .stversions 吃满&lt;/strong&gt;
版本保留策略太宽或同步了频繁变动的大文件目录。调小保留天数/份数，并把日志、缓存类目录用 &lt;code&gt;.stignore&lt;/code&gt; 排除，版本控制只给真正重要的目录开。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;两台设备版本不一致&lt;/strong&gt;
不要跨太多个大版本混跑，客户端保持自动更新即可；VPS 的 Docker 镜像定期 &lt;code&gt;docker compose pull&lt;/code&gt; 更新，更新前看一眼官方发布说明。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Syncthing 是自建文件体系里最「润物细无声」的一件：配好之后，文件在自己的设备之间安静流动，不经过任何第三方。记住三条就够了：相册类目录单向发送、工作目录双向同步、所有重要目录都开版本控制；再叠一层独立备份，同步才真正等于安心。它和 Cloudreve 是互补关系——网盘管归档与分享，同步管日常流动，两件一起上，文件这块就再没什么可操心的了。&lt;/p&gt;
</content:encoded></item><item><title>FreshRSS：自建 RSS 阅读器与订阅管理</title><link>https://www.anexns.cloudns.org/posts/selfhost-freshrss/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-freshrss/</guid><description>用 FreshRSS 在 VPS 上自建 RSS 阅读器：Docker Compose 部署、数据库选型、订阅分类与 OPML 导入、定时刷新任务、开启 API 接入手机客户端，以及订阅不更新等常见问题的排查。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说清楚：RSS 过时了吗&lt;/h2&gt;
&lt;p&gt;算法推荐流解决的是「平台想让你看什么」，RSS 解决的是「你自己想看什么」。博客、播客、新闻站、GitHub 项目动态、视频站更新——凡是支持 RSS 输出的源，订阅之后按时间顺序全部汇到一个页面，没有广告、没有信息茧房、没有「猜你喜欢」。&lt;/p&gt;
&lt;p&gt;自建 RSS 阅读器的意义在于：订阅列表和阅读记录是你自己的数据，不怕哪天某个阅读器服务关停或收费。&lt;strong&gt;FreshRSS&lt;/strong&gt; 是目前最活跃的开源自建阅读器：界面清爽、支持多用户、扩展丰富，还提供 Google Reader 兼容 API，能喂饱几乎所有移动端阅读 App。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;一次部署，所有设备共用同一份订阅和已读状态。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;主线：&lt;strong&gt;Compose 部署 → 走完安装向导 → 导入订阅并分类 → 设定时刷新 → 开 API 接手机客户端 → 日常排障&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;Compose 部署与数据库选型&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;services:
  freshrss:
    image: freshrss/freshrss:latest
    container_name: freshrss
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
    volumes:
      - ./data:/var/www/FreshRSS/data
      - ./extensions:/var/www/FreshRSS/extensions
    ports:
      - &quot;127.0.0.1:8081:80&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动后在 Nginx Proxy Manager 里给它配一个域名和 HTTPS，方法与系列其他服务一致，见 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager：所有自建服务的统一入口&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;FreshRSS 支持三种数据库，安装向导里选：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;数据库&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;SQLite&lt;/td&gt;
&lt;td&gt;个人使用（默认推荐）&lt;/td&gt;
&lt;td&gt;零配置，数据就在 data 目录里&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MySQL / MariaDB&lt;/td&gt;
&lt;td&gt;多用户、订阅量大&lt;/td&gt;
&lt;td&gt;需要额外数据库容器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;PostgreSQL&lt;/td&gt;
&lt;td&gt;已经有 PG 在跑时顺手用&lt;/td&gt;
&lt;td&gt;性能好，配置略多&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;个人使用直接选 SQLite 就够了，几千个订阅毫无压力，而且备份时整个 data 目录打包带走就行，不用单独导数据库。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/freshrss &amp;amp;&amp;amp; cd ~/freshrss
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;安装向导与初始设置&lt;/h2&gt;
&lt;p&gt;打开域名，进入安装向导：选语言（简体中文）→ 检查环境（全绿才继续）→ 选数据库（SQLite）→ 创建管理员账号。装完登录进去，先到「设置 → 系统」里确认两件事：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;站点标题和时区&lt;/strong&gt;：时区不对会导致文章时间显示错乱；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;是否开放注册&lt;/strong&gt;：默认只留自己用的话，到「设置 → 用户」确认不允许公开注册，道理和系列里反复强调的一样，见 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全加固：最小暴露与访问控制&lt;/a&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;界面可以在「设置 → 显示」里换主题，深色主题晚上看长文舒服很多；每页文章数、阅读模式（标题列表/展开全文）按个人习惯调。&lt;/p&gt;
&lt;h2&gt;订阅管理：分类、导入与整理&lt;/h2&gt;
&lt;p&gt;点左上角「订阅管理 → 添加订阅源」，粘贴站点地址或 RSS 地址，FreshRSS 会自动探测源。整理订阅的关键是&lt;strong&gt;分类&lt;/strong&gt;，建议按「每天必看 / 资讯 / 技术 / 更新提醒」粗分四到六个，不要一上来建二十个分类，最后自己都不想点开。&lt;/p&gt;
&lt;p&gt;已有阅读器迁移过来：旧服务导出 OPML 文件，在「导入/导出」里一键导入，订阅和分类结构完整保留。反过来，FreshRSS 也能随时导出 OPML，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;保证你永远可以带着订阅列表走人&amp;lt;/span&amp;gt;，这是自建的核心价值之一。&lt;/p&gt;
&lt;p&gt;几个让阅读体验质变的小设置：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;对更新太频繁的源，在订阅设置里开启「标记为已读策略」：比如打开页面即标记、或超过 N 天自动标记；&lt;/li&gt;
&lt;li&gt;对只给摘要的源，可以试「抓取原文」功能（订阅设置里的 XPath 抓取），把全文拉回本地读；&lt;/li&gt;
&lt;li&gt;星标和标签用来攒长文，周末统一清。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;定时刷新：最容易漏的一步&lt;/h2&gt;
&lt;p&gt;FreshRSS 本身不会在后台自动拉取，&lt;strong&gt;必须配一个定时任务周期性地执行刷新脚本&lt;/strong&gt;，否则你打开页面看到的永远是上次手动刷新时的内容。漏配这一步是新手最常见的「为什么订阅不更新」。&lt;/p&gt;
&lt;p&gt;在宿主机上加一条 crontab：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;crontab -e
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;写入（每 15 分钟刷新一次）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;*/15 * * * * docker exec freshrss php /var/www/FreshRSS/app/actualize_script.php &amp;gt; /dev/null 2&amp;gt;&amp;amp;1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
注意：刷新脚本要以容器内 Web 服务相同的用户身份执行才不会把数据文件属主弄乱。用宿主机 cron 通过 &lt;code&gt;docker exec&lt;/code&gt; 调用时，如果刷新后出现「数据库不可写」之类报错，多半是属主问题——进容器看 &lt;code&gt;data&lt;/code&gt; 目录属主是否为 &lt;code&gt;www-data&lt;/code&gt;，不一致就 &lt;code&gt;docker exec freshrss chown -R www-data:www-data /var/www/FreshRSS/data&lt;/code&gt; 修回来。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要图省事长期用 root 在宿主机上直接改容器数据目录里的文件。&amp;lt;/span&amp;gt;
:::&lt;/p&gt;
&lt;p&gt;也可以把每个订阅源的刷新间隔单独调：重磅源保持默认，低频博客在订阅设置里改成每天拉一次，减轻服务器和对方站点的压力。&lt;/p&gt;
&lt;h2&gt;开启 API：接入手机客户端&lt;/h2&gt;
&lt;p&gt;FreshRSS 的杀手锏是 API。到「设置 → 账户 → API 管理」：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;给 API 单独设一个&lt;strong&gt;API 密码&lt;/strong&gt;（和登录密码相互独立）；&lt;/li&gt;
&lt;li&gt;勾选允许 API 访问；&lt;/li&gt;
&lt;li&gt;你的 API 地址就是 &lt;code&gt;https://你的域名/api/greader.php&lt;/code&gt;。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;之后在手机阅读 App（Reeder、NetNewsWire、FeedMe 等支持 Google Reader API 的客户端）里选择「FreshRSS / Google Reader」类型，填服务器地址、账号和 API 密码，就能同步全部订阅和已读状态。通勤路上用手机刷掉资讯类，回家电脑上打开只剩长文，这个工作流非常顺手。&lt;/p&gt;
&lt;p&gt;如果以后想在 FreshRSS 里聚合其他类型的信息流，社区还有各种扩展，装到 &lt;code&gt;extensions&lt;/code&gt; 目录后在「设置 → 扩展」启用即可。&lt;/p&gt;
&lt;h2&gt;订阅源从哪来：把日常信息入口都收进来&lt;/h2&gt;
&lt;p&gt;装好阅读器之后，最大的问题往往是「不知道订什么」。几个实用的来源思路：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;常看的博客和独立站&lt;/strong&gt;：绝大多数个人博客都自带 RSS，在网址后试 &lt;code&gt;/feed&lt;/code&gt;、&lt;code&gt;/rss.xml&lt;/code&gt;、&lt;code&gt;/atom.xml&lt;/code&gt;，或者把网址直接粘进 FreshRSS 让它自动探测；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;GitHub 动态&lt;/strong&gt;：项目 Releases、某个仓库的 commits 都有 Atom 输出，关注的开源项目发新版第一时间知道，格式形如 &lt;code&gt;https://github.com/作者/仓库/releases.atom&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;播客&lt;/strong&gt;：播客本质就是带音频附件的 RSS，在 FreshRSS 里订阅后能看到更新列表，点开跳转收听；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;视频站与公众号类&lt;/strong&gt;：这类平台官方 RSS 支持较弱，社区有 RSSHub 这类开源的「RSS 生成器」项目，可以自建一个把各类站点转成 RSS 再喂给 FreshRSS，自建 RSSHub 本身也是一个简单的 Docker 容器，和 FreshRSS 放在同一台机器上正好配套；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;别人的 OPML 分享&lt;/strong&gt;：技术圈经常有人分享自己的订阅清单 OPML 文件，导入后挑感兴趣的留，其余删掉，是冷启动最快的方式。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;订阅数量的经验值：总数控制在 100 个以内、每天新增文章不超过 200 篇，阅读压力就不会失控。RSS 的目的是「不错过」，不是「全看完」，已读焦虑大可不必——一周没看的资讯类文章，一键全部标记已读，世界不会塌。&lt;/p&gt;
&lt;h2&gt;阅读工作流与多用户&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;键盘快捷键&lt;/strong&gt;值得花五分钟熟悉：&lt;code&gt;j/k&lt;/code&gt; 上下篇、空格展开、&lt;code&gt;m&lt;/code&gt; 标记已读、&lt;code&gt;s&lt;/code&gt; 星标。资讯类文章用这个流速每分钟能过几十篇标题，只把真正感兴趣的点开。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;星标即稍后读&lt;/strong&gt;：把星标当成唯一的「待读清单」，并坚持每天清掉一部分。FreshRSS 还能为星标列表生成一个专属 RSS 输出地址，可以再喂给其他工具做二次处理。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;多用户&lt;/strong&gt;：FreshRSS 支持多账号，每个用户的订阅和已读完全隔离。在「设置 → 用户」里建号即可。给家人各开一个号共用同一套服务，比每人各装一个阅读器省心得多。注意管理员能看到所有用户的订阅清单，介意隐私的场景就不要共用——不过家庭场景一般无所谓。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;移动端离线&lt;/strong&gt;：通过 API 接入的手机客户端大多支持离线缓存，出门前在 Wi-Fi 下刷新一次，地铁里慢慢看，回公司自动同步已读状态，这是自建 RSS 相比网页阅读器最舒服的体验之一。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. 订阅源添加失败或拉取为空&lt;/strong&gt;
先在浏览器直接打开那个 RSS 地址确认源本身活着；再在服务器上 &lt;code&gt;curl&lt;/code&gt; 同一地址看是否被对方拦截（有些站点对机房 IP 不友好）。个别源需要自定义 User-Agent，在订阅设置的高级选项里可以单独指定。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 文章时间不对、排序混乱&lt;/strong&gt;
检查三处时区：宿主机、容器 &lt;code&gt;TZ&lt;/code&gt; 环境变量、FreshRSS 系统设置，三者统一为 Asia/Shanghai。源本身时间戳写错的没法救，只能靠自动已读策略兜底。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 页面打开慢、文章列表卡&lt;/strong&gt;
多半是未读数攒了几万条。在「设置 → 归档」里设置自动清理：已读文章保留 1–3 个月，未读保留更久；再手动跑一次「清理数据库」压缩 SQLite。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 全文抓取失败&lt;/strong&gt;
XPath 规则随目标站点改版失效是常态，重新按新版页面结构写规则即可；也可以退一步只读摘要、点原文跳转，不必强求每个源都全文。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. 订阅几百个之后刷新变慢、容器内存涨&lt;/strong&gt;
先分清瓶颈在哪：刷新慢多半是少数几个源响应慢拖住整批，在订阅管理里看每个源的刷新耗时，把长期超时的源删掉或降频；内存涨则多半是文章攒太多，按前面说的归档策略定期清理。另外 SQLite 在高频写入时是单写者模型，个人使用无感，真到了多用户重度使用阶段，再迁到 MySQL 不迟，官方文档有现成的迁移路径。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;6. 页面样式错乱、图片不显示&lt;/strong&gt;
如果只在 HTTPS 下出现，基本是混合内容：源站文章里的图片还是 http 地址，被浏览器拦了。可以给 FreshRSS 前面的反代加图片代理，或者接受点开原文看图。样式整体错乱则多半是反代把路径改错了，FreshRSS 对子路径部署比较敏感，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;强烈建议用独立子域名部署，不要挂在某个域名的子目录下&amp;lt;/span&amp;gt;，能省掉一整类问题。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;7. 换服务器后 API 客户端全部掉线&lt;/strong&gt;
API 地址绑定域名，迁移时保持域名不变、数据目录整体搬过去（方法见 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移实战&lt;/a&gt;），客户端无感；域名变了就得逐个客户端改地址。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;8. 搜索不到很久以前的文章&lt;/strong&gt;
先确认文章是不是被归档策略清掉了：清理规则按保留时长删旧文，清掉的搜不到是正常现象，长文请及时星标，星标文章默认不参与自动清理。再确认搜索范围：FreshRSS 的搜索框默认只搜当前视图（比如当前分类），找全文时要切到「全部订阅」视图再搜。另外搜索支持一些实用语法，比如 &lt;code&gt;intitle:关键词&lt;/code&gt; 只搜标题、&lt;code&gt;author:名字&lt;/code&gt; 按作者过滤、&lt;code&gt;#标签&lt;/code&gt; 按标签过滤，善用这些比一页页翻快得多。实在要做深度全文检索，可以把星标文章的专属 RSS 输出接到外部工具里，不必强求阅读器本身样样都行。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;FreshRSS 是典型的「小而美」自建服务：部署十分钟，价值在长期——订阅列表归你、已读状态全端同步、没有算法插队。记住三个关键动作：装完先关公开注册、务必设定时刷新脚本、给 API 设独立密码。配好这三样，它就能安安静静地替你守着整个信息入口好几年。&lt;/p&gt;
</content:encoded></item><item><title>自建服务实战：Frigate 打造 AI 摄像头监控系统</title><link>https://www.anexns.cloudns.org/posts/selfhost-frigate/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-frigate/</guid><description>用 Frigate 在自己的服务器上搭建本地 AI 目标检测的 NVR 监控系统：Coral、OpenVINO、NVIDIA 三种检测加速方案对比，Docker Compose 部署与 config.yml 逐段详解，双码流分工、事件录像保留、误报调优与存储估算全流程。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：摄像头的录像，凭什么要先绕一圈云端&lt;/h2&gt;
&lt;p&gt;家里装摄像头的人越来越多，但多数消费级摄像头的「智能检测」是这么工作的：画面先传到厂商云端，云端判断「有人经过」，再把通知推回你的手机。代价很具体：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;隐私不在自己手里&lt;/strong&gt;。你家门口、院子、车库的画面，常年流经别人的服务器，对方怎么存、存多久、给谁看，你说了不算。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;订阅绑架&lt;/strong&gt;。云存储、AI 检测、历史回放，一层层都是月费，不交钱摄像头就退化成只会录像的摆设。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;断网即瞎&lt;/strong&gt;。云端检测依赖外网，宽带一断，检测和通知跟着一起断，本地明明有录像也调不出来智能事件。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;误报轰炸&lt;/strong&gt;。云端算法不认识你家的环境，树影、车灯、飞虫全给你推一条，几天下来就把通知关了，监控形同虚设。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Frigate 的路线完全相反：它是一个跑在你自己服务器上的开源 NVR（网络录像机），摄像头画面只在局域网里流动，AI 目标检测在本地硬件上完成，识别出人、车、猫、狗之后才生成事件、截图和录像片段。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;Frigate 的核心价值就一句话：检测和录像全部本地完成，画面不出家门，智能不靠订阅。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;认识 Frigate 的工作模型 → 准备摄像头与检测加速硬件 → Docker Compose 部署 → config.yml 逐段详解 → 事件与回放 → 检测性能调优 → 与 MQTT、Home Assistant 联动 → 存储容量估算与保留策略&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;Frigate 是什么：一个「只对感兴趣的东西录像」的 NVR&lt;/h2&gt;
&lt;p&gt;传统 NVR 的逻辑是 24 小时无差别录像，回放时靠时间轴慢慢拖。Frigate 的逻辑是事件驱动的，三条流水线各司其职：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;流水线&lt;/th&gt;
&lt;th&gt;干什么&lt;/th&gt;
&lt;th&gt;用哪路码流&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;运动检测（motion）&lt;/td&gt;
&lt;td&gt;用 OpenCV 在低清画面上找「哪里动了」，成本极低&lt;/td&gt;
&lt;td&gt;子码流&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;目标检测（detect）&lt;/td&gt;
&lt;td&gt;把动起来的区域截出来，喂给 AI 模型判断是人、车还是猫狗&lt;/td&gt;
&lt;td&gt;子码流&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;录像（record）&lt;/td&gt;
&lt;td&gt;把高清画面按事件切成片段存盘，没事件的时段可直接丢弃&lt;/td&gt;
&lt;td&gt;主码流&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;运动检测先筛掉 99% 的静止画面，AI 模型只处理真正有变化的区域，这是 Frigate 能在小主机上带多路摄像头的关键。检测到目标后，它会生成一个「事件」：带目标框的截图、事件前后的录像片段、目标类型和置信度，全部存进本地数据库，在 Web 界面里按摄像头、按目标类型筛选回放。&lt;/p&gt;
&lt;p&gt;它识别的目标类型来自 COCO 数据集，常用的包括 person（人）、car（车）、motorcycle、bicycle、dog、cat、bird 等。对家庭场景来说，真正有用的就四五个，剩下的在配置里关掉还能减少误报。&lt;/p&gt;
&lt;p&gt;:::warning
Frigate 只做检测和录像，不提供云端中继，也没有官方手机 App。远程查看要靠你自己的方式回到内网（比如在 Nginx Proxy Manager 后面加访问控制），这块的安全思路可以参考本系列的&lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全与访问控制&lt;/a&gt;，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;千万不要把 Frigate 的 5000 端口裸奔暴露到公网&amp;lt;/span&amp;gt;——它早期版本的鉴权非常薄弱，等于把家里画面开给全网看。
:::&lt;/p&gt;
&lt;h2&gt;硬件准备：摄像头与检测加速器&lt;/h2&gt;
&lt;h3&gt;摄像头：认准 RTSP 和双码流&lt;/h3&gt;
&lt;p&gt;Frigate 不挑品牌，只挑协议。选购时确认三件事：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;支持 RTSP 输出&lt;/strong&gt;。海康、大华、TP-LINK、Reolink 的多数型号都支持；某些只给自家云 App 的纯消费级摄像头拿不到 RTSP 流，直接排除。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;支持双码流&lt;/strong&gt;。主码流 4MP/5MP 高清录像，子码流 720P 或 D1 低清给检测用，两路同时输出，这是后面配置分工的前提。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;编码格式优先 H.264&lt;/strong&gt;。H.265 省空间但部分硬件解码兼容性差，Frigate 官方也建议检测链路用 H.264 更稳；录像路可以保留 H.265。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;供电和网络没什么好说的：PoE 交换机一根网线搞定供电加数据，是最省心的方案。摄像头和服务器放同一个局域网网段，跨网段拉流徒增排障难度。&lt;/p&gt;
&lt;h3&gt;检测加速器：整个系统最关键的一笔钱&lt;/h3&gt;
&lt;p&gt;目标检测是纯算力活，用 CPU 硬算不是不行，但一路摄像头就能吃掉一两个核心，多路必爆。Frigate 支持三类加速方案：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方案&lt;/th&gt;
&lt;th&gt;代表硬件&lt;/th&gt;
&lt;th&gt;推理性能&lt;/th&gt;
&lt;th&gt;功耗&lt;/th&gt;
&lt;th&gt;成本&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Google Coral TPU&lt;/td&gt;
&lt;td&gt;USB 版 / M.2 / PCIe 版 Edge TPU&lt;/td&gt;
&lt;td&gt;约 4 TOPS，一次推理个位数毫秒&lt;/td&gt;
&lt;td&gt;约 2W&lt;/td&gt;
&lt;td&gt;一两百元但常缺货&lt;/td&gt;
&lt;td&gt;路数不多、追求低功耗小主机的首选&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Intel OpenVINO&lt;/td&gt;
&lt;td&gt;N100、J4125 等带核显的 Intel CPU&lt;/td&gt;
&lt;td&gt;核显跑检测，性能够用，多路略吃紧&lt;/td&gt;
&lt;td&gt;整机功耗的一部分&lt;/td&gt;
&lt;td&gt;零额外成本（核显白送）&lt;/td&gt;
&lt;td&gt;已经用 Intel 小主机的人，零成本起步&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;NVIDIA GPU&lt;/td&gt;
&lt;td&gt;GTX 1660、RTX 3050 等独显，或 Jetson&lt;/td&gt;
&lt;td&gt;性能最强，多路高帧率无压力&lt;/td&gt;
&lt;td&gt;几十瓦起步&lt;/td&gt;
&lt;td&gt;独显价格＋电费&lt;/td&gt;
&lt;td&gt;已有显卡、路数多，或还要兼跑其他 AI 服务&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个选型要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Coral 是 Frigate 的「原配」&lt;/strong&gt;。它的模型就是为 Edge TPU 编译的，单路检测延迟最低、功耗几乎可忽略。USB 版要注意插 USB 3.0 口并保证供电，挂在廉价 Hub 上容易掉设备。缺点是这两年经常缺货，价格被炒高时不必硬追。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;OpenVINO 是性价比之王&lt;/strong&gt;。N100 这类小主机的核显跑 3–4 路子码流检测毫无压力，整机待机功耗也就十来瓦。家里已经有 Intel 平台软路由或小主机的，这是零成本方案。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;NVIDIA 适合「一卡多用」&lt;/strong&gt;。如果你的服务器上已经插了显卡跑其他服务（比如本系列 &lt;a href=&quot;/posts/selfhost-jellyfin/&quot;&gt;Jellyfin 影音库&lt;/a&gt;的硬件转码），Frigate 可以共享同一张卡做检测。独显的驱动与容器直通配置，本系列的 &lt;a href=&quot;/posts/docker-gpu-nvidia/&quot;&gt;Docker 调用 NVIDIA GPU 指南&lt;/a&gt;里有完整流程，这里不重复。纯为 Frigate 买独显则不划算，功耗和噪音都摆在那里。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;宿主机本身的门槛不高：双核 CPU、4GB 内存就能起步（用了加速器之后 CPU 只负责运动检测和录像写入）。存储单独规划，下一节细说。&lt;/p&gt;
&lt;h2&gt;Docker Compose 部署&lt;/h2&gt;
&lt;p&gt;先建目录结构：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p /opt/frigate/config /mnt/nvr/frigate
cd /opt/frigate
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;录像目录 &lt;code&gt;/mnt/nvr/frigate&lt;/code&gt; 建议是一块独立的大容量机械盘或 NAS 挂载点，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把录像写进系统盘或 Docker 数据盘&amp;lt;/span&amp;gt;，原因在后面的排障部分会讲透。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;docker-compose.yml&lt;/code&gt; 如下，以 Coral USB 版为例：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  frigate:
    container_name: frigate
    image: ghcr.io/blakeblackshear/frigate:stable
    restart: unless-stopped
    stop_grace_period: 30s
    shm_size: &quot;256mb&quot;
    devices:
      - /dev/bus/usb:/dev/bus/usb        # Coral USB 版直通
      # - /dev/dri/renderD128:/dev/dri/renderD128   # Intel 核显直通（OpenVINO/VAAPI 用）
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./config:/config                  # config.yml 所在目录
      - /mnt/nvr/frigate:/media/frigate   # 录像与截图存储
      - type: tmpfs
        target: /tmp/cache                # 录像分片先写内存盘，再转存正式目录
        tmpfs:
          size: 1000000000
    ports:
      - &quot;5000:5000&quot;    # Web 界面
      - &quot;8554:8554&quot;    # 内置 go2rtc 的 RTSP 转发
      - &quot;8555:8555/tcp&quot;  # WebRTC 直播
      - &quot;8555:8555/udp&quot;
    environment:
      FRIGATE_RTSP_PASSWORD: &quot;你的摄像头密码&quot;
      TZ: Asia/Shanghai
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这份 Compose 里有三个容易被忽略但很关键的点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;shm_size&lt;/code&gt; 不能省&lt;/strong&gt;。Frigate 用共享内存给每路摄像头存检测帧，默认的 64MB 在多路或高分辨率子码流下会直接报 &lt;code&gt;Bus error&lt;/code&gt; 崩溃。官方经验公式是：&lt;code&gt;宽 × 高 × 1.5 × 20 + 270000&lt;/code&gt; 字节/路，720P 子码流一路约 40MB，256MB 够 4–5 路用，路数多就往上加。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;/tmp/cache&lt;/code&gt; 用 tmpfs&lt;/strong&gt;。录像分片是高频小写入，先落内存盘、成片后再搬到正式存储，能大幅减少机械盘的碎片写入和抖动。1GB 内存盘是常规值，路数多可加大。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;密码走环境变量&lt;/strong&gt;。摄像头密码不要明文写进 config.yml，在配置里用 &lt;code&gt;{FRIGATE_RTSP_PASSWORD}&lt;/code&gt; 占位引用，Compose 里注入，后面换密码只改一处。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;先别急着填完整配置，写一个最小 &lt;code&gt;config/config.yml&lt;/code&gt; 把容器拉起来验证硬件直通：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mqtt:
  enabled: false

detectors:
  coral:
  # OpenVINO 用户把这一段换成：
  # ov:
  #   type: openvino
  #   device: GPU
    type: edgetpu
    device: usb

cameras:
  test_cam:
    ffmpeg:
      inputs:
        - path: rtsp://admin:{FRIGATE_RTSP_PASSWORD}@192.168.1.64:554/Streaming/Channels/102
          roles:
            - detect
    detect:
      width: 1280
      height: 720
      fps: 5
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker logs -f frigate
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;日志里看到检测器初始化成功（Coral 会打印 TPU 打开信息）、摄像头帧率稳定在 5fps 左右，就说明硬件链路通了。打开 &lt;code&gt;http://服务器IP:5000&lt;/code&gt; 能看到测试画面，接着再上完整配置。&lt;/p&gt;
&lt;h2&gt;config.yml 逐段详解&lt;/h2&gt;
&lt;p&gt;完整配置按功能拆成五段，一段一段说清楚。以一台装在门口的摄像头 &lt;code&gt;front_door&lt;/code&gt; 为例。&lt;/p&gt;
&lt;h3&gt;第一段：mqtt 与全局开关&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;mqtt:
  enabled: true
  host: 192.168.1.10        # 你的 MQTT Broker 地址，比如 Mosquitto
  port: 1883
  topic_prefix: frigate
  user: frigate
  password: &quot;broker密码&quot;
  stats_interval: 60
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;MQTT 是 Frigate 对外发事件的嘴：每次检测到目标、事件开始/结束、截图就绪，都会往 &lt;code&gt;frigate/events&lt;/code&gt; 等主题发消息。没有 Broker 可以先 &lt;code&gt;enabled: false&lt;/code&gt; 关掉，Web 界面功能不受影响，联动部分后面单独讲。&lt;/p&gt;
&lt;h3&gt;第二段：detectors 检测器&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;detectors:
  coral:
    type: edgetpu
    device: usb
    num_threads: 3
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;Coral：&lt;code&gt;type: edgetpu&lt;/code&gt;，USB 版 &lt;code&gt;device: usb&lt;/code&gt;，PCIe/M.2 版写 &lt;code&gt;device: pci&lt;/code&gt;。&lt;code&gt;num_threads&lt;/code&gt; 建议 3，给多路摄像头留并行余量。&lt;/li&gt;
&lt;li&gt;OpenVINO：换成 &lt;code&gt;type: openvino&lt;/code&gt;、&lt;code&gt;device: GPU&lt;/code&gt;（核显），并在顶层加一段模型路径配置，官方文档有现成模板。&lt;/li&gt;
&lt;li&gt;NVIDIA：&lt;code&gt;type: onnx&lt;/code&gt; 并指定 CUDA 模型，配置最繁琐，跟着官方 GPU 章节抄即可。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;一台机器可以同时挂多个检测器（比如 Coral 加核显分流），但家庭场景一个就够，复杂度留给有需要的人。&lt;/p&gt;
&lt;h3&gt;第三段：cameras 与双码流分工&lt;/h3&gt;
&lt;p&gt;这是整个配置的心脏。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;双码流分工是 Frigate 性能的地基：检测吃子码流、录像吃主码流，两条路互不干扰。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ffmpeg:
  hwaccel_args: preset-vaapi     # Intel 核显解码；NVIDIA 用 preset-nvidia，无加速删掉这行

cameras:
  front_door:
    ffmpeg:
      inputs:
        - path: rtsp://admin:{FRIGATE_RTSP_PASSWORD}@192.168.1.64:554/Streaming/Channels/102
          input_args: preset-rtsp-restream
          roles:
            - detect
        - path: rtsp://admin:{FRIGATE_RTSP_PASSWORD}@192.168.1.64:554/Streaming/Channels/101
          input_args: preset-rtsp-restream
          roles:
            - record
    detect:
      width: 1280
      height: 720
      fps: 5
    motion:
      threshold: 30
      contour_area: 15
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐项说明：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;海康的通道号约定：&lt;code&gt;101&lt;/code&gt; 是主码流、&lt;code&gt;102&lt;/code&gt; 是子码流；大华是 &lt;code&gt;subtype=0/1&lt;/code&gt;，Reolink 是 &lt;code&gt;stream0/stream1&lt;/code&gt;，换品牌时对照说明书改路径即可。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;roles&lt;/code&gt; 决定每路流的用途。detect 路的分辨率和帧率由 &lt;code&gt;detect&lt;/code&gt; 段决定：720P、5fps 是甜点值——足够模型认出人形，又不给解码和检测器添负担。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;hwaccel_args&lt;/code&gt; 把 RTSP 解码交给核显或独显，省下的 CPU 留给运动检测。没有硬件解码也能跑，但每路要多吃半个核心左右。&lt;/li&gt;
&lt;li&gt;同一台摄像头的两路流是两个独立连接，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;子码流参数必须和摄像头后台的实际设置一致&amp;lt;/span&amp;gt;（分辨率、帧率对不上，检测画面会拉伸或报错），改了摄像头后台记得回头同步这里。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;第四段：record 与 snapshots 保留策略&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;record:
  enabled: true
  retain:
    days: 3
    mode: motion          # 连续录像只留 3 天，且只留有运动的片段
  events:
    retain:
      default: 30         # 事件录像留 30 天
      mode: active_objects
    pre_capture: 5        # 事件录像往前多带 5 秒
    post_capture: 5

snapshots:
  enabled: true
  timestamp: true
  bounding_box: true
  retain:
    default: 30
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两级保留是省空间的核心设计：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;连续录像（retain）&lt;/strong&gt; 是「全量底片」，按 &lt;code&gt;mode: motion&lt;/code&gt; 只保留有运动的时段，留 3 天足够应对「前天夜里好像有动静」的回查。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;事件录像（events.retain）&lt;/strong&gt; 是 AI 确认过有目标的片段，价值最高，留 30 天甚至更久。&lt;code&gt;pre_capture&lt;/code&gt; 把目标出现前的 5 秒也带上，回放时能看到人是从哪走进画面的，排查问题时非常关键。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;snapshots&lt;/strong&gt; 是事件截图，带时间戳和目标框，通知推送时附的就是它。截图单张才几百 KB，保留期可以和事件录像对齐。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;第五段：objects 过滤与置信度&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;objects:
  track:
    - person
    - car
    - dog
    - cat
  filters:
    person:
      min_area: 5000
      max_area: 1000000
      min_score: 0.7
      threshold: 0.85
    car:
      min_score: 0.65
      threshold: 0.8

zones:
  front_door:
    driveway:
      coordinates: 0,720,1280,720,1280,400,700,350,0,450
      objects:
        - car
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;track&lt;/code&gt; 是全局白名单：只追踪这四类，其余目标（鸟、自行车、公交车）直接忽略，误报和算力一起降。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;min_score&lt;/code&gt; 是单帧置信度门槛：某一帧里模型对「这是人」的把握低于 0.7 就丢弃。&lt;code&gt;threshold&lt;/code&gt; 是整个事件的综合门槛：一闪而过的低置信度影子凑不够分，成不了事件。这两个值是后面误报调优的主战场。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;min_area / max_area&lt;/code&gt; 按目标在画面里的像素面积过滤：贴脸大的多半是飞虫或蜘蛛网，远处小的可能是树影，先框一刀。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;zones&lt;/code&gt; 是区域：车道区域只关心 car，院门区域只关心 person。区域还能单独设门槛和触发「有人进入区域」的事件，是精细化告警的基础。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;改完配置后在 Web 界面的 Settings 里可以直接校验并重启，也可以 &lt;code&gt;docker compose restart frigate&lt;/code&gt;。配置语法错了容器会起不来，&lt;code&gt;docker logs&lt;/code&gt; 第一行就会指出错在哪一行，改配置前先 &lt;code&gt;cp config.yml config.yml.bak&lt;/code&gt; 是个好习惯。&lt;/p&gt;
&lt;h2&gt;事件与回放：日常使用长什么样&lt;/h2&gt;
&lt;p&gt;Web 界面（5000 端口）主要就三个视图：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Live&lt;/strong&gt;：所有摄像头的实时画面（走子码流，流畅优先），点开单个摄像头看主码流高清直播。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Events&lt;/strong&gt;：事件流，按日期、摄像头、目标类型、区域筛选。每条事件有带框截图、开始/结束时间、最高置信度，点开就是事件前后的录像片段，可以下载导出。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Recording&lt;/strong&gt;：按小时铺开的连续录像时间轴，用来回查没有触发事件的时段（比如只想看看昨晚车库有没有动静）。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;日常体验里，Events 是 95% 的使用场景：手机收到「门口检测到人」的推送，点开就是那段十几秒的录像，不需要像传统 NVR 那样拖时间轴大海捞针。觉得某条是误报，可以在界面里标记，后面调 &lt;code&gt;min_score&lt;/code&gt; 时就有依据了。&lt;/p&gt;
&lt;h2&gt;检测性能调优：准、稳、省，三者怎么平衡&lt;/h2&gt;
&lt;h3&gt;检测分辨率与帧率：别贪高&lt;/h3&gt;
&lt;p&gt;detect 的 5fps、720P 不是随便定的：人走过门口通常持续 2 秒以上，5fps 能抓到 10 帧以上的有效画面，足够模型确认。把 fps 拉到 10 甚至 15，检测器负载翻倍，识别率却几乎不涨——模型缺的不是帧数，是清晰的目标轮廓。子码流分辨率同理：720P 下人形轮廓清晰；降到 D1（704×576）也能用，但远处小目标容易漏检；升到 1080P 做检测纯属浪费算力。&lt;/p&gt;
&lt;h3&gt;mask 遮罩：把注定误报的区域提前 mute&lt;/h3&gt;
&lt;p&gt;画面里总有几个「永久运动区」：随风晃的树冠、马路边的车流倒影、空调外机的抖动。在摄像头配置里给运动检测和目标追踪分别打遮罩：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cameras:
  front_door:
    motion:
      mask:
        - 0,0,1280,120          # 顶部树冠区域：x1,y1,x2,y2 矩形
    objects:
      filters:
        person:
          mask:
            - 900,300,1280,300,1280,720,900,720   # 右侧邻居院子，不追踪人
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Web 界面的 Mask &amp;amp; Zone 编辑器可以可视化涂抹，涂完直接生成坐标串粘回配置，比手算坐标省事得多。遮罩是降误报性价比最高的一招，比反复调阈值管用。&lt;/p&gt;
&lt;h3&gt;阈值调整的节奏&lt;/h3&gt;
&lt;p&gt;误报和漏报是一对跷跷板，调参的正确姿势是：先保召回（门槛宁低勿高，漏报比误报危险），跑一周收集误报样本，再针对性地上遮罩、提 &lt;code&gt;min_score&lt;/code&gt;、加 &lt;code&gt;min_area&lt;/code&gt;。一次只动一个参数，动完观察两天，否则永远不知道是哪个参数起的作用。&lt;/p&gt;
&lt;h2&gt;与 MQTT、Home Assistant 联动：从「录像机」到「安防节点」&lt;/h2&gt;
&lt;p&gt;Frigate 单独用已经是一个好 NVR，但它的事件流一旦接进消息系统，玩法就完全不同了。&lt;/p&gt;
&lt;p&gt;联动链条很短：Frigate 检测到事件 → 往 MQTT Broker 发消息（主题 &lt;code&gt;frigate/events&lt;/code&gt;，内容是 JSON，含事件 ID、摄像头、目标类型、置信度、区域、截图路径）→ 订阅方按需消费。&lt;/p&gt;
&lt;p&gt;最典型的订阅方是 Home Assistant：它有官方 Frigate 集成，装上之后每个摄像头会自动变成一组实体——实时画面、各类目标的计数传感器（「门口当前有人：是/否」）、事件通知。自动化就可以写成大白话：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;天黑后，门口区域检测到 person 且置信度大于 0.8 → 开院灯、给手机推带截图的通知。&lt;/li&gt;
&lt;li&gt;车库检测到 car 离开超过 10 分钟 → 检查门磁状态，没关就报警。&lt;/li&gt;
&lt;li&gt;猫出现在厨房区域 → 只记录不通知（这种分级正是 zones 加 filters 的用武之地）。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;没有 Home Assistant 也不影响：任何能订阅 MQTT 的工具（Node-RED、自写脚本、消息推送服务）都能消费同一套事件。告警的送达方式可以和本系列&lt;a href=&quot;/posts/selfhost-monitoring-alerts/&quot;&gt;自建服务监控告警实战&lt;/a&gt;里聊过的通道复用：监控告警和安防事件本质都是「事件 → 分级 → 推送」，分级原则通用——深夜的人形事件值得叫醒你，下午的快递车只配进事件列表躺着。&lt;/p&gt;
&lt;p&gt;需要注意的是，MQTT 联动只传「事件元数据和截图」，录像本体仍在 Frigate 里，推送通知里附的是截图和回放链接，点开回内网看完整片段，这也是它和云端方案在隐私上的根本区别。&lt;/p&gt;
&lt;h2&gt;存储容量估算与保留策略&lt;/h2&gt;
&lt;p&gt;录像吃多少盘，取决于码率、保留模式和保留天数。先算单路摄像头的账（主码流 4MP、H.265、平均码率 4Mbps）：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;保留方式&lt;/th&gt;
&lt;th&gt;单路日均占用&lt;/th&gt;
&lt;th&gt;4 路摄像头 × 30 天&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;24 小时全量录像&lt;/td&gt;
&lt;td&gt;约 43GB&lt;/td&gt;
&lt;td&gt;约 5.2TB&lt;/td&gt;
&lt;td&gt;4Mbps × 86400 秒 ÷ 8，传统 NVR 模式&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;只留 motion 片段&lt;/td&gt;
&lt;td&gt;约 8–15GB&lt;/td&gt;
&lt;td&gt;约 1–1.4TB&lt;/td&gt;
&lt;td&gt;取决于环境活跃程度，门口比室内高&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;只留事件录像&lt;/td&gt;
&lt;td&gt;约 1–3GB&lt;/td&gt;
&lt;td&gt;约 120–360GB&lt;/td&gt;
&lt;td&gt;AI 确认有目标才存，家庭场景最常用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;估算公式可以自己套：&lt;code&gt;日占用（GB）= 码率（Mbps）× 3600 × 24 ÷ 8 ÷ 1000 × 保留比例&lt;/code&gt;。保留比例全量是 1，motion 模式家庭场景一般在 0.2–0.35，纯事件模式在 0.05 以内。&lt;/p&gt;
&lt;p&gt;落到配置上就是前面 &lt;code&gt;record&lt;/code&gt; 段的两级保留：连续录像 3 天 motion 模式兜底回查，事件录像 30 天精确保留。按上表，4 路摄像头配一块 2TB 盘，这个组合能跑得很宽裕；如果盘只有 500GB，就把连续录像降到 1 天、事件保留降到 14 天，或者只对门口、车库这两路开连续录像，室内摄像头只存事件。&lt;/p&gt;
&lt;p&gt;还有两个细节：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Frigate 会按保留策略自动清理过期片段，不需要你写定时脚本删文件；但它&lt;strong&gt;不会&lt;/strong&gt;在磁盘满时替你兜底乱删未过期录像，所以容量规划要留至少 15% 的余量。&lt;/li&gt;
&lt;li&gt;存储目录的健康要纳入日常巡检：磁盘剩余空间、SMART 状态值得和服务器的其他指标一起盯，具体做法在&lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全与访问控制&lt;/a&gt;同系列的监控篇里有现成方案，这里不展开。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;h3&gt;摄像头拉流失败，画面黑屏或日志刷 &lt;code&gt;Unable to read frames&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;按顺序排查：先在宿主机上用 ffplay 或 VLC 直接打开同一条 RTSP 地址，能播说明流没问题，锅在配置；不能播就查摄像头侧。常见原因有四个：密码里的特殊字符没做 URL 编码（用 &lt;code&gt;{FRIGATE_RTSP_PASSWORD}&lt;/code&gt; 占位也救不了 &lt;code&gt;@&lt;/code&gt;、&lt;code&gt;#&lt;/code&gt; 这类字符本身，建议摄像头密码只用字母数字）；摄像头后台关了 RTSP 或 ONVIF 开关；摄像头限制了最大连接数，被你手机 App 和 Frigate 抢满了；主/子码流通道号写反。再就是跨网段时防火墙拦了 554 端口。日志里如果报的是解码错误而不是连接错误，把 &lt;code&gt;hwaccel_args&lt;/code&gt; 先删掉用软解验证，能通就是硬件解码的兼容问题，多见于 H.265 子码流，改回 H.264 最稳。&lt;/p&gt;
&lt;h3&gt;CPU 占用爆高，加速器像没装一样&lt;/h3&gt;
&lt;p&gt;先看 Web 界面首页的检测器统计：推理耗时是否正常（Coral 应为个位数到十几毫秒，OpenVINO 在几十毫秒量级）。如果推理耗时正常但 CPU 还是满，大概率是&lt;strong&gt;解码&lt;/strong&gt;在吃 CPU——检查 &lt;code&gt;hwaccel_args&lt;/code&gt; 是否生效、核显设备是否真的直通进了容器（&lt;code&gt;docker exec frigate ls /dev/dri&lt;/code&gt; 看不到设备就是 Compose 里 devices 没写对）。另一个高频原因是手滑把 detect 角色挂到了主码流上：4MP 画面做运动检测，光 OpenCV 那一关就能吃掉一个多核心，对照配置里两路流的 roles 逐字核对。如果是 Coral 掉设备（日志报 &lt;code&gt;No EdgeTPU was detected&lt;/code&gt;），先换 USB 3.0 口和线，再查供电，别在软件里瞎折腾。&lt;/p&gt;
&lt;h3&gt;误报太多，一天几百条事件&lt;/h3&gt;
&lt;p&gt;不要一上来就拉高 &lt;code&gt;min_score&lt;/code&gt; 一刀切，按这个顺序处理：先看误报样本的共性——固定区域的（树影、反光、蜘蛛网）用 mask 遮掉，这是治本；固定类型的（把晾晒的衣服认成 person、把狗认成 bear）靠 &lt;code&gt;min_area&lt;/code&gt; 和区域 filters 排除；剩下零星的再把对应目标的 &lt;code&gt;min_score&lt;/code&gt; 从 0.7 提到 0.75、&lt;code&gt;threshold&lt;/code&gt; 提到 0.9。蜘蛛和飞虫是夜视模式的特产：红外灯会把贴镜头的小虫照成「巨兽」，除了 mask 镜头正前方区域，还可以在摄像头侧把红外强度调低一档，或者外加一盏独立红外灯把光源移开镜头。调完观察两天再动下一刀，一周左右能收敛到个位数。&lt;/p&gt;
&lt;h3&gt;录像把磁盘写满，容器或宿主机异常&lt;/h3&gt;
&lt;p&gt;这是最危险的一个故障：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;录像盘写满后，轻则 Frigate 录制中断，重则宿主机日志和 Docker 一起被拖死&amp;lt;/span&amp;gt;。先应急：&lt;code&gt;du -sh /mnt/nvr/frigate/*&lt;/code&gt; 看是 recordings 还是 clips 占的，手动删最旧日期的目录腾空间。根因通常是三个：保留天数按全量录像的体量估错了（新摄像头码率比旧的高一倍，账要重算）；某路摄像头环境太活跃，motion 比例远超预估（对着马路的摄像头尤其如此，这一路应改成纯事件保留）；存储目录被别的服务误用（备份脚本、下载目录写进了同一块盘）。修好之后把这块盘的剩余空间加进监控告警，低于 20% 就推送提醒，别等写满了才发现。&lt;/p&gt;
&lt;h3&gt;检测延迟大，人都走过去了才报事件&lt;/h3&gt;
&lt;p&gt;事件通知天然有几秒延迟：要等目标离开或事件确认结束才发完整事件，这是机制不是故障。如果延迟到十几秒，先看检测器推理耗时是否劣化（Coral 挂在 USB 2.0 口上会慢一个量级），再看 detect 的 fps 是否被改低了，以及宿主机是否同时在跑转码等重活抢 CPU。直播画面延迟大则是另一回事，多半是播放器走了 RTSP 转码路径，换 WebRTC（8555 端口）能压到一秒以内。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Frigate 这套系统搭下来，真正花心思的就三件事：&lt;strong&gt;硬件上给检测找个加速器、配置上把双码流分工做对、调优上用遮罩和阈值把误报压下去&lt;/strong&gt;。做完这三件，你得到的是一套画面不出内网、没有订阅费、事件秒级可查的本地安防系统，门口有谁来过、快递几点到的、猫半夜去哪儿了，全是结构化事件而不是几个小时的录像带。&lt;/p&gt;
&lt;p&gt;往后扩展的路径也很清楚：路数变多就加一块盘、换更强的检测器；想玩智能家居就把 MQTT 事件接进 Home Assistant 做自动化；想异地备份重要事件，就把 events 目录单独同步一份到其他存储——本系列的备份篇里的方法都通用。监控这件事，数据在自己手里，才谈得上安心。&lt;/p&gt;
</content:encoded></item><item><title>自建服务入门：从一台 VPS 开始的完整规划</title><link>https://www.anexns.cloudns.org/posts/selfhost-getting-started/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-getting-started/</guid><description>想自建服务却不知道从哪下手？这篇从 VPS 选型、域名规划、目录规范讲到监控备份安全的整体路线，帮你把第一台自建服务器规划明白再动手。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：自建服务最容易死在「没规划」上&lt;/h2&gt;
&lt;p&gt;很多人自建服务的第一步，是搜到一篇教程，复制一段 Docker Compose，跑起来一个服务，兴奋三天。然后呢？第二个服务端口冲突了，第三个服务忘了数据卷挂在哪，半年后想迁移，翻遍 shell 历史也拼不出一份完整的部署清单。服务越装越多，机器越来越像一团乱麻，最后一次系统更新把环境搞坏，连修都不敢修。&lt;/p&gt;
&lt;p&gt;这篇是整个「自建服务实战系列」的总纲，不讲某个具体软件的安装，而是先把全局规划做对：机器怎么选、域名怎么分、目录怎么放、入口怎么统一、监控备份安全怎么提前安排。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;自建服务的核心竞争力不是装得多，而是每个服务都可控、可迁移、可恢复。&amp;lt;/span&amp;gt;后面的每一篇具体部署，都会回到这篇的规范上来。&lt;/p&gt;
&lt;h2&gt;自建服务到底能解决什么问题&lt;/h2&gt;
&lt;p&gt;先想清楚自己要什么，再决定装什么。下面是自建场景里最常见的需求和对应方案，也是本系列后续篇目的地图：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;需求&lt;/th&gt;
&lt;th&gt;自建方案&lt;/th&gt;
&lt;th&gt;对应篇目&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;多台服务器状态一目了然&lt;/td&gt;
&lt;td&gt;Komari 监控面板&lt;/td&gt;
&lt;td&gt;第 3 篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;服务挂了第一时间知道&lt;/td&gt;
&lt;td&gt;Uptime Kuma 可用性监控&lt;/td&gt;
&lt;td&gt;第 4 篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件自己掌控、跨设备同步&lt;/td&gt;
&lt;td&gt;Cloudreve / Alist / Syncthing&lt;/td&gt;
&lt;td&gt;第 6、7、8 篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;家里媒体库随时看&lt;/td&gt;
&lt;td&gt;Jellyfin&lt;/td&gt;
&lt;td&gt;第 9 篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;密码不再复用、不再记脑子里&lt;/td&gt;
&lt;td&gt;Vaultwarden&lt;/td&gt;
&lt;td&gt;第 11 篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;订阅内容自己聚合&lt;/td&gt;
&lt;td&gt;FreshRSS&lt;/td&gt;
&lt;td&gt;第 11 篇&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;团队/家人私有沟通&lt;/td&gt;
&lt;td&gt;Rocket.Chat&lt;/td&gt;
&lt;td&gt;第 10 篇&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;没有出现在你需求清单里的服务，先不要装。每一个跑着的服务都是维护成本：要更新、要备份、要盯安全公告。够用主义是自建长期主义的第一原则。&lt;/p&gt;
&lt;h2&gt;第一步：选一台合适的 VPS&lt;/h2&gt;
&lt;p&gt;自建入门不需要多强的机器。本系列涉及的服务绝大多数是轻量 Web 应用，一台 2 核 2 GB 内存的 VPS 就能同时跑五六个。选型时按这个顺序看：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;规模&lt;/th&gt;
&lt;th&gt;典型服务组合&lt;/th&gt;
&lt;th&gt;建议配置&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;轻量起步&lt;/td&gt;
&lt;td&gt;监控 + 云盘 + RSS + 密码库&lt;/td&gt;
&lt;td&gt;1–2 核 / 2 GB / 40 GB SSD&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;影音进阶&lt;/td&gt;
&lt;td&gt;上述 + Jellyfin 直播直出&lt;/td&gt;
&lt;td&gt;2 核 / 4 GB / 大容量盘或外挂存储&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;影音转码&lt;/td&gt;
&lt;td&gt;Jellyfin 实时转码&lt;/td&gt;
&lt;td&gt;带核显或独显的机器，优先考虑家用设备&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;多节点监控&lt;/td&gt;
&lt;td&gt;面板机 + 多台被监控机&lt;/td&gt;
&lt;td&gt;面板机最低配即可，Agent 占用极小&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个容易忽略的点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;流量比带宽峰值更重要&lt;/strong&gt;。云盘和影音是吃流量的大户，先算月流量额度，再看标称带宽。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;磁盘先看 IOPS 再看容量&lt;/strong&gt;。数据库类服务跑在高延迟盘上会全面卡顿，SSD 是底线。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;IP 质量影响 HTTPS 与邮件&lt;/strong&gt;。被污染过的 IP 段可能触发各种风控，拿到机器先测一下连通性。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;系统统一用 Debian 或 Ubuntu LTS&lt;/strong&gt;。本系列所有命令以 Debian 系为准，版本越主流，踩坑越少。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;拿到 VPS 后的系统初始化、SSH 加固、防火墙配置，本站 Linux 系列已经有完整流程，这里不重复。装好 Docker 与 Docker Compose 之后再继续，安装方法见 &lt;a href=&quot;/posts/linux-docker-compose/&quot;&gt;如何在 Linux 部署 Docker &amp;amp; Compose&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;第二步：域名与 DNS 规划&lt;/h2&gt;
&lt;p&gt;自建服务强烈建议绑定域名，而不是用 &lt;code&gt;IP:端口&lt;/code&gt; 访问。原因很实际：HTTPS 证书需要域名、换机器时只改解析不用改所有客户端配置、给家人朋友分享时也体面得多。&lt;/p&gt;
&lt;p&gt;规划方式是一个主域名加子域名，每个服务一个：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;子域名示例&lt;/th&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;npm.example.com&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;反向代理管理后台（仅自己访问）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;status.example.com&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;监控面板与状态页&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;drive.example.com&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;云盘&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;media.example.com&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;影音服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;vault.example.com&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;密码库&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;所有子域名解析到同一台 VPS 的 IP 即可，区分服务的工作交给反向代理。DNS 侧只需要为每个子域名加一条 A 记录（或一条通配符记录 &lt;code&gt;*.example.com&lt;/code&gt;，但通配符会让「不存在的服务」也解析过去，入门阶段建议逐个添加，心里有数）。&lt;/p&gt;
&lt;p&gt;证书方面，后续篇目会用反向代理内置的 Let&apos;s Encrypt 自动申请与续期，不需要手动管理证书文件。&lt;/p&gt;
&lt;h2&gt;第三步：目录与编排规范&lt;/h2&gt;
&lt;p&gt;这是全篇最值得照抄的部分。所有服务统一放在 &lt;code&gt;/opt/apps&lt;/code&gt; 下，一个服务一个目录，目录里放它自己的 &lt;code&gt;docker-compose.yml&lt;/code&gt; 和数据：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/opt/apps/
├── nginx-proxy-manager/
│   ├── docker-compose.yml
│   ├── data/
│   └── letsencrypt/
├── komari/
│   ├── docker-compose.yml
│   └── data/
├── uptime-kuma/
│   └── docker-compose.yml
└── cloudreve/
    ├── docker-compose.yml
    └── data/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;配套的约定：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;一个服务一份 Compose 文件&lt;/strong&gt;，不把所有服务塞进一个巨型 Compose。这样单个服务的启停、升级、迁移互不影响。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;数据用相对路径挂载到本目录的 &lt;code&gt;data/&lt;/code&gt; 下&lt;/strong&gt;，不用 Docker 命名卷。迁移时整个目录打包带走即可，不用去猜数据在 &lt;code&gt;/var/lib/docker&lt;/code&gt; 的哪个角落。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;密码等敏感信息写在同目录的 &lt;code&gt;.env&lt;/code&gt; 文件里&lt;/strong&gt;，Compose 用 &lt;code&gt;${VAR}&lt;/code&gt; 引用，&lt;code&gt;.env&lt;/code&gt; 不进任何公开仓库。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;每个目录放一个 &lt;code&gt;README.md&lt;/code&gt;&lt;/strong&gt;，记三件事：这个服务干什么、数据在哪、恢复命令是什么。三个月后的你会感谢现在的你。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;日常管理的命令也就固定下来了，进任意服务目录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/apps/uptime-kuma
docker compose pull      # 拉新镜像
docker compose up -d     # 启动/更新
docker compose logs -f   # 看日志
docker compose down      # 停止
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;切忌把服务数据直接写在容器可写层里&amp;lt;/span&amp;gt;——容器一删，数据就没了。所有需要留存的数据，必须通过 volumes 挂载到上面规划的 &lt;code&gt;data/&lt;/code&gt; 目录，这一点在每一篇部署里都会再强调。&lt;/p&gt;
&lt;h2&gt;第四步：统一入口，只开三个端口&lt;/h2&gt;
&lt;p&gt;规划阶段就要定下整台机器的暴露面：对外只开放 80、443（Web 流量）和一个 SSH 端口。所有服务的 Web 界面都通过反向代理按域名分发，服务自身的端口只监听本机或只在 Docker 内网里存在。&lt;/p&gt;
&lt;p&gt;这样做的好处是决定性的：HTTPS 证书只在一处管理、访问控制只在一处配置、防火墙规则简单到一眼能看完。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把每个服务的端口都直接暴露到公网，是自建事故最常见的源头&amp;lt;/span&amp;gt;——你永远不知道哪个小众服务下一次爆出未授权访问漏洞。&lt;/p&gt;
&lt;p&gt;统一入口的具体实现是下一篇的 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager：所有自建服务的统一入口&lt;/a&gt;，它提供图形化界面管理反代与证书，是整套自建体系的地基，建议装完 Docker 后第一个部署它。&lt;/p&gt;
&lt;h2&gt;第五步：监控、备份、安全，必须提前安排&lt;/h2&gt;
&lt;p&gt;这三件事的共同点是：出事之后再补，全都来不及。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;监控分两层&lt;/strong&gt;。一层看机器：CPU、内存、磁盘、流量，多台机器汇总到一个面板，用 &lt;a href=&quot;/posts/selfhost-komari/&quot;&gt;Komari：轻量服务器监控探针部署与多节点接入&lt;/a&gt; 实现；一层看服务：每个 Web 服务是否还能正常响应，用第 4 篇的 Uptime Kuma 盯着。监控发现问题后怎么通知到人、怎么处理，是第 5 篇的内容。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;备份跟着服务一起上线&lt;/strong&gt;，而不是「等有空了再说」。最低标准是：每个服务的 &lt;code&gt;data/&lt;/code&gt; 目录和 Compose 文件定期打包，存一份到机器之外的地方。第 11 篇 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移实战&lt;/a&gt; 会给出完整的备份与迁移流程，包括异地副本与恢复演练。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;安全做减法&lt;/strong&gt;。暴露面最小化、后台加访问控制、密码库里的凭据不复用，这些原则贯穿全系列，第 11 篇 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全加固：最小暴露与访问控制&lt;/a&gt; 会系统收尾。&lt;/p&gt;
&lt;h2&gt;推荐的上手顺序&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;VPS 初始化 + Docker（Linux 系列与 Docker 系列已覆盖）&lt;/li&gt;
&lt;li&gt;Nginx Proxy Manager 统一入口（第 2 篇）&lt;/li&gt;
&lt;li&gt;Komari + Uptime Kuma 监控双件套（第 3、4 篇），并配好告警（第 5 篇）&lt;/li&gt;
&lt;li&gt;按需逐个加业务服务：云盘、影音、密码库、RSS（第 6–13 篇）&lt;/li&gt;
&lt;li&gt;备份流程跑通并做一次恢复演练（第 11 篇）&lt;/li&gt;
&lt;li&gt;安全加固自查（第 11 篇）&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::warning
不要在第一天就把所有服务一口气全装上。每加一个服务，先确认三件事：数据挂载对不对、备份包不包含它、监控盯没盯上它。节奏慢一天，省的是将来整晚的排障。
:::&lt;/p&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：家里有 NAS/小主机，还需要 VPS 吗？&lt;/strong&gt;
看服务性质。对公网提供访问的服务（状态页、聊天、分享链接）放 VPS 更稳；大容量影音、转码这类吃硬件和电费的，可以放家里设备，再通过内网穿透或组网接入。本系列以 VPS 为主线，Compose 文件在家用 Docker 上同样能跑。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：2 GB 内存跑这么多服务会不会爆？&lt;/strong&gt;
本系列的轻量服务单个内存占用多在 50–300 MB 之间，2 GB 跑五六个没问题。真正吃内存的是影音转码和大文件索引，那类需求按前面的表格升配即可。另外记得给系统留 swap 兜底。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：服务装多了，更新会不会很累？&lt;/strong&gt;
按本文的规范（一服务一 Compose），更新就是进目录 &lt;code&gt;pull + up -d&lt;/code&gt; 两条命令。镜像自动更新工具（如 Watchtower）本站 Docker 系列讲过，但数据库与密码库这类关键服务建议手动更新、先看 changelog。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：域名还没备案/没有域名，能先练手吗？&lt;/strong&gt;
可以先用 IP 加端口把服务跑通验证功能，但正式使用前务必切到域名加 HTTPS，尤其是密码库这类敏感服务。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;自建服务的成败在动手之前就决定了一大半：一台配置够用的 VPS、一个规划好的域名体系、&lt;code&gt;/opt/apps&lt;/code&gt; 下一服务一目录的编排规范、只开 80/443 的统一入口，再加上与服务同步上线的监控、备份与安全。这套骨架立住之后，后面每一篇都是往骨架上挂一个具体服务而已。下一篇，我们先把地基打好：部署 Nginx Proxy Manager，让所有服务从同一个大门进出。&lt;/p&gt;
</content:encoded></item><item><title>Gitea：自建 Git 代码托管与仓库备份</title><link>https://www.anexns.cloudns.org/posts/selfhost-gitea/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-gitea/</guid><description>在自己的服务器上搭一套轻量 Git 代码托管：Gitea 的 Compose 部署（内置与外接数据库两种方案）、SSH 与域名配置、组织权限、从 GitHub 迁移仓库，以及完整的备份策略。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：代码放在别人家，心里总有一块不踏实&lt;/h2&gt;
&lt;p&gt;把代码全托管在公共平台上当然方便，但有几件事始终捏在别人手里：私有仓库的可见性规则说改就改，平台故障或账号异常时你连拉都拉不下来，内网项目、脚本仓库、配置仓库这类「不想出门」的东西根本没地方放。更现实的一点：给 GitHub 上的重要仓库做一份自己能掌控的镜像备份，是很多人在吃过一次亏之后才想起来的事。&lt;/p&gt;
&lt;p&gt;Gitea 就是为这个场景准备的：一个用 Go 写的轻量 Git 托管服务，功能对标 GitHub 的核心部分——仓库、议题、拉取请求、组织与团队、软件包、Wiki 一应俱全，但资源占用只有 GitLab 的零头，一台小 VPS 就能流畅跑全家桶。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;自建 Gitea 的定位通常不是取代 GitHub，而是给私有代码安个家、给公开仓库留一份自己的备份。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Docker Compose 部署，先讲内置数据库、再讲外接数据库&lt;/li&gt;
&lt;li&gt;初始化管理员，关掉公开注册&lt;/li&gt;
&lt;li&gt;把 SSH 端口和域名配对，让克隆地址一次正确&lt;/li&gt;
&lt;li&gt;组织与团队权限怎么分&lt;/li&gt;
&lt;li&gt;从 GitHub 批量迁移与镜像同步&lt;/li&gt;
&lt;li&gt;备份策略：官方 dump、数据卷与 Git 镜像三层&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;两种数据库方案，先选再装&lt;/h2&gt;
&lt;p&gt;Gitea 支持 SQLite、PostgreSQL、MySQL 三种数据库。个人自建就两条路线：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方案&lt;/th&gt;
&lt;th&gt;适合人群&lt;/th&gt;
&lt;th&gt;代价&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;内置 SQLite&lt;/td&gt;
&lt;td&gt;个人使用、仓库不多、图省事&lt;/td&gt;
&lt;td&gt;数据库就是一个文件，备份最简单；并发写入能力弱&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;外接 PostgreSQL&lt;/td&gt;
&lt;td&gt;多人协作、仓库多、想长期经营&lt;/td&gt;
&lt;td&gt;多一个数据库容器要维护，性能和可靠性上限更高&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;判断标准很简单：只有你自己用，SQLite 足够；要拉家人或小团队进来，直接上 PostgreSQL，别等迁移的那天。两种方案的 Compose 只差数据库部分，下面先给 SQLite 版全量，外接版只列差异。&lt;/p&gt;
&lt;h2&gt;部署一：内置 SQLite 版&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/gitea &amp;amp;&amp;amp; cd ~/gitea
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;docker-compose.yml&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    restart: unless-stopped
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__server__DOMAIN=git.example.com
      - GITEA__server__ROOT_URL=https://git.example.com/
      - GITEA__server__SSH_DOMAIN=git.example.com
      - GITEA__server__SSH_PORT=2222
      - GITEA__service__DISABLE_REGISTRATION=true
      - GITEA__security__INSTALL_LOCK=true
      - GITEA__security__SECRET_KEY=改成一长串随机字符串
    volumes:
      - ./data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - &quot;3000:3000&quot;
      - &quot;2222:22&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;说明几个容易埋雷的配置：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;容器内的 Git SSH 服务监听 22 端口，映射到宿主机的 2222；&lt;code&gt;GITEA__server__SSH_PORT&lt;/code&gt; 必须写映射后的 2222，Gitea 生成克隆地址时用的就是这个值，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;写错会导致页面上复制的 SSH 克隆地址永远连不上&amp;lt;/span&amp;gt;。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;INSTALL_LOCK=true&lt;/code&gt; 表示跳过网页安装向导、直接以配置为准；代价是没有网页初始化流程，管理员账号要靠命令行创建（下一节）。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;SECRET_KEY&lt;/code&gt; 参与加密数据库里的敏感字段，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;上线后不要再更换&amp;lt;/span&amp;gt;，换了之后已存的令牌、两步验证等数据会解不开。它要和数据一起备份。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;DISABLE_REGISTRATION=true&lt;/code&gt; 关掉公开注册，自建服务的基本动作，开放注册的 Gitea 很快会变成垃圾仓库集散地。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;正式对外时 3000 端口同样只作调试，网页访问走 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager&lt;/a&gt; 反代加 HTTPS；SSH 的 2222 端口需要直连暴露（或按安全篇的思路改到非标准端口并做限源）。&lt;/p&gt;
&lt;p&gt;:::warning
Gitea 里躺着的是全部代码、部署密钥和访问令牌，是被扫描器盯得最紧的服务类型之一。上线第一件事就是确认公开注册已经关闭、管理员开了两步验证；历史上大量自建 Git 服务被入侵，都是从「忘了关注册」开始的。
:::&lt;/p&gt;
&lt;h2&gt;部署二：外接 PostgreSQL 版&lt;/h2&gt;
&lt;p&gt;在上面基础上加一个数据库服务，并给 Gitea 补数据库环境变量：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;  db:
    image: docker.io/library/postgres:16-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=改成强密码
      - POSTGRES_DB=gitea
    volumes:
      - ./db-data:/var/lib/postgresql/data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Gitea 服务里追加：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=与上面一致的密码
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;并在 Gitea 服务下加 &lt;code&gt;depends_on: [db]&lt;/code&gt;。已经用 SQLite 跑了一段想迁过去的，可以用 Gitea 的数据库转换工具，但更稳妥的做法是新实例装好后逐个仓库用镜像推过去，账号和权限重新建——个人量级这条路反而省事。&lt;/p&gt;
&lt;h2&gt;创建管理员与第一次登录&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;INSTALL_LOCK&lt;/code&gt; 模式下执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec -u git gitea gitea admin user create \
  --admin \
  --username admin \
  --email admin@example.com \
  --password &apos;你的强密码&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意必须带 &lt;code&gt;-u git&lt;/code&gt;，用 root 身份执行会在数据目录里留下属主错误的文件，后续服务读写会出莫名其妙的问题。创建成功后打开站点，用这个账号登录，第一件事是去个人设置里打开两步验证，并到站点管理面板里再确认一遍注册确实关闭、默认仓库可见性符合预期（建议设为私有优先）。&lt;/p&gt;
&lt;p&gt;SSH 克隆测试一把：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git clone ssh://git@git.example.com:2222/admin/test.git
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;先在网页上建个测试仓库、把本机 SSH 公钥加到个人设置里再克隆。地址里端口是 2222、用户是 &lt;code&gt;git&lt;/code&gt;，对得上就说明 SSH 链路和前面配置都正确。&lt;/p&gt;
&lt;h2&gt;组织与团队：多人协作时的权限骨架&lt;/h2&gt;
&lt;p&gt;单人使用可以跳过这一节，但只要有第二个人进来，就该用组织来管仓库，而不是把仓库堆在个人名下再逐个加协作者。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;组织（Organization）&lt;/strong&gt;：仓库的归属主体，类似 GitHub 上的 org，所有者、管理员、普通成员三档组织级角色。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;团队（Team）&lt;/strong&gt;：组织内的权限分组，每个团队单独设置能访问哪些仓库、以及对代码、议题、拉取请求、发布、Wiki、软件包这些单元的权限级别（无 / 读取 / 写入 / 管理员）。&lt;/li&gt;
&lt;/ul&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;推荐分法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;家人共享脚本与配置&lt;/td&gt;
&lt;td&gt;一个组织，成员全部进「家庭」团队，写入权限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;小团队项目&lt;/td&gt;
&lt;td&gt;按项目建团队，只给对应仓库的写入，其余只读&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;只读访客（如部署机拉代码）&lt;/td&gt;
&lt;td&gt;单独建机器人账号或只读团队，配合部署密钥使用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;原则和本系列 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;安全加固篇&lt;/a&gt; 一致：权限按最小够用给，部署拉代码用只读的部署密钥，不要图省事到处用管理员账号的令牌。&lt;/p&gt;
&lt;h2&gt;从 GitHub 迁移仓库与镜像同步&lt;/h2&gt;
&lt;p&gt;这是自建 Gitea 最大的实用价值之一。网页右上角「+」→「新建迁移」，选择 GitHub，填仓库地址和访问令牌，可以勾选要一并搬过来的内容：议题、标签、里程碑、拉取请求、发布、Wiki；仓库用了 Git LFS 的记得勾上 LFS 选项，否则大文件只会剩指针。&lt;/p&gt;
&lt;p&gt;更关键的是「将此仓库设为镜像」：勾上之后 Gitea 会定时从 GitHub 拉取同步（拉取镜像），默认同步间隔可以在仓库设置里调。这样 GitHub 仍是主力，Gitea 是一份自动更新的完整备份，某天平台出问题或者账号出状况，你手里始终有一份能直接切换的副本。&lt;/p&gt;
&lt;p&gt;批量迁移没有官方一键全账号搬运，仓库多的做法是拿 GitHub API 拉出仓库清单，写个小脚本循环调 Gitea 的迁移 API 建仓。几十个仓库的量级，脚本跑一晚上也就完了。&lt;/p&gt;
&lt;h2&gt;备份：三层都要有&lt;/h2&gt;
&lt;p&gt;Gitea 的数据分三块：&lt;code&gt;/data&lt;/code&gt; 里的仓库与附件、数据库里的账号议题等元数据、配置文件里的密钥。三层备份对应着做：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一层：官方 dump。&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec -u git gitea gitea dump -c /data/gitea/conf/app.ini
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;在数据目录生成一个包含仓库、数据库和配置的 zip，是官方推荐的整体备份方式，恢复时解压回对应位置即可。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二层：数据卷整目录备份。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;停服或低峰期把 &lt;code&gt;./data&lt;/code&gt;（外接版再加 &lt;code&gt;./db-data&lt;/code&gt;）整目录打包，和本系列其他服务一起进 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;备份与迁移篇&lt;/a&gt; 的统一备份节奏。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;只备份仓库目录、不备份数据库是最常见的自欺欺人&amp;lt;/span&amp;gt;——仓库文件还在，但用户、权限、议题全没了，等于只剩一堆裸仓库要手工认领。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三层：Git 镜像异地冗余。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Git 本身就是分布式的：对最重要的几个仓库，在另一台机器或另一个平台留一份镜像，&lt;code&gt;git push --mirror&lt;/code&gt; 定期推一次。这层备份不依赖 Gitea 能否恢复，任何 Git 工具都能直接读，是最后的兜底。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;SSH 克隆提示 Permission denied 或连接超时。&lt;/strong&gt;
按顺序查：公钥是否加到了当前登录账号而不是管理员账号；克隆地址里的端口是不是 2222；服务器防火墙有没有放行 2222；&lt;code&gt;SSH_DOMAIN&lt;/code&gt; 与实际访问域名是否一致。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;反向代理后页面样式错乱、链接跳回内网地址。&lt;/strong&gt;
&lt;code&gt;ROOT_URL&lt;/code&gt; 没配对的典型表现。改成最终对外访问的完整地址（含 https），重启容器。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;推送大仓库被中断。&lt;/strong&gt;
多半是反向代理的请求体大小限制：在 NPM 对应站点的 Advanced 里放开 &lt;code&gt;client_max_body_size&lt;/code&gt;，或改走 SSH 推送绕开 HTTP 层限制。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;网页迁移 GitHub 仓库失败。&lt;/strong&gt;
令牌权限不够是最常见原因：迁移议题和拉取请求需要令牌能读对应仓库的这些内容；私有仓库要确认令牌覆盖该仓库。网络层面确认服务器能正常访问 GitHub，拉取大仓库超时可以在仓库设置的镜像同步里改重试。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;管理员密码忘了。&lt;/strong&gt;
宿主机执行 &lt;code&gt;docker exec -u git gitea gitea admin user change-password --username admin --password &apos;新密码&apos;&lt;/code&gt; 即可重置，这也是自建服务的好处——最高权限始终在自己手里。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Gitea 的部署难度在自建服务里属于最低的一档，一个 Compose 文件、一个数据目录就全齐了；真正的价值在部署之外的三件事：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;SSH 与域名一次配对、GitHub 仓库开镜像同步、备份三层都做满。&amp;lt;/span&amp;gt;做到这三点，它既是私有代码的家，也是公开仓库的一份保险，平台风云再变，你的代码始终有一份握在自己手里。&lt;/p&gt;
&lt;p&gt;同属本系列扩充篇的还有文档归档的 &lt;a href=&quot;/posts/selfhost-paperless-ngx/&quot;&gt;Paperless-ngx&lt;/a&gt;、本地 AI 界面 Open WebUI 与照片备份 Immich，可以按需取用。&lt;/p&gt;
</content:encoded></item><item><title>自建服务实战：Home Assistant 打造智能家居中枢</title><link>https://www.anexns.cloudns.org/posts/selfhost-home-assistant/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-home-assistant/</guid><description>用 Docker 部署 Home Assistant 智能家居中枢：讲清容器版与 HAOS 的取舍、host 网络与设备直通、集成与 MQTT 接入、自动化三段式实战、仪表盘、安全远程访问与备份排障。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：智能家居为什么需要一个「中枢」&lt;/h2&gt;
&lt;p&gt;智能家居玩到最后，家里往往是这个局面：灯是米家的，插座是涂鸦的，空调伴侣是博联的，摄像头又是另一个 App。每个品牌一套云、一套 App，设备之间互不说话——想让「开门亮灯」这种跨品牌联动跑起来，光靠各家自己的云服务基本没戏。更麻烦的是断网即残废：宽带一断，全屋智能退回手动时代；厂商云服务关停，设备直接变砖的新闻也出过不止一次。&lt;/p&gt;
&lt;p&gt;Home Assistant（下文简称 HA）就是为了解决这件事而生的开源中枢。它跑在你自己家里的服务器、NAS 或小主机上，把各品牌设备统一接进来，用一套规则做联动。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;HA 的核心理念是本地优先：设备控制和自动化逻辑全部在局域网内完成，不依赖任何厂商云，断网照样跑。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;它的家底也确实厚：官方与社区集成超过两千个，Zigbee、Z-Wave、蓝牙、Wi-Fi、MQTT 各种协议都能收编；更新节奏是每月一个大版本，社区活跃度在自建圈里数一数二。&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;对比三种部署方式并选定 Docker 版 → Compose 部署与设备直通 → 初始化与核心概念 → 接入设备（含 MQTT 与 Frigate 联动）→ 自动化三段式实战 → 仪表盘 → 安全远程访问 → 备份与排障&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;部署方式对比：Docker 版、HAOS、树莓派&lt;/h2&gt;
&lt;p&gt;HA 有四种官方安装形态，选错了后面全是别扭。先拉个表：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;部署方式&lt;/th&gt;
&lt;th&gt;形态&lt;/th&gt;
&lt;th&gt;优点&lt;/th&gt;
&lt;th&gt;缺点&lt;/th&gt;
&lt;th&gt;适合人群&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;HAOS（虚拟机）&lt;/td&gt;
&lt;td&gt;完整操作系统镜像跑在虚拟机里&lt;/td&gt;
&lt;td&gt;功能最全：带 Supervisor、插件商店、一键备份恢复&lt;/td&gt;
&lt;td&gt;独占一台虚拟机，资源开销大，与其他服务隔离&lt;/td&gt;
&lt;td&gt;有 PVE/ESXi 环境、想省心&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HAOS（树莓派/小主机裸装）&lt;/td&gt;
&lt;td&gt;镜像直接刷进 SD 卡或硬盘&lt;/td&gt;
&lt;td&gt;同上，且即插即用&lt;/td&gt;
&lt;td&gt;整台设备被 HA 独占；SD 卡寿命是隐患&lt;/td&gt;
&lt;td&gt;愿意给 HA 一台专属设备&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Docker 容器版（Container）&lt;/td&gt;
&lt;td&gt;单个容器跑核心服务&lt;/td&gt;
&lt;td&gt;轻量、与现有 Docker 服务共存、迁移就是搬目录&lt;/td&gt;
&lt;td&gt;没有 Supervisor 和插件商店，附加服务要自己用容器补&lt;/td&gt;
&lt;td&gt;已经有 Docker 宿主机/NAS&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Core（Python 虚拟环境）&lt;/td&gt;
&lt;td&gt;直接装 Python 包&lt;/td&gt;
&lt;td&gt;最灵活&lt;/td&gt;
&lt;td&gt;依赖全靠自己维护，升级容易翻车&lt;/td&gt;
&lt;td&gt;开发者，不推荐日常用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;本文走 &lt;strong&gt;Docker 容器版&lt;/strong&gt;，理由很实际：看这篇的朋友多半已经有一台跑着 Docker 的 NAS 或小主机，HA 作为一个普通容器塞进去即可，不用为它单独开虚拟机，更不用独占一台设备。代价是没有插件商店——但插件的本质就是预打包的容器（比如 Mosquitto、Zigbee2MQTT），自己写进 Compose 里反而更透明可控。排障一节会再细说这个差异。&lt;/p&gt;
&lt;p&gt;:::warning
先泼盆冷水：HA 对宿主机的时间、网络发现协议都比较敏感。如果你的 Docker 宿主机本身网络环境复杂（多层 NAT、VLAN 隔离），设备自动发现会打折扣，这类问题在后面排障里有对应条目。
:::&lt;/p&gt;
&lt;h2&gt;Docker Compose 部署&lt;/h2&gt;
&lt;p&gt;先建目录，再写 Compose 文件：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p /opt/homeassistant/config
cd /opt/homeassistant
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;docker-compose.yml&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    restart: unless-stopped
    network_mode: host
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0   # Zigbee/Z-Wave USB 协调器，没有可删掉这一段
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose logs -f homeassistant   # 看到启动完成字样后 Ctrl+C 退出
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个关键点逐个说清：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;为什么用 &lt;code&gt;network_mode: host&lt;/code&gt;？&lt;/strong&gt; HA 大量依赖局域网广播协议做设备发现：mDNS、SSDP、DHCP 嗅探全是广播包。容器走默认 bridge 网络时这些广播进不来，自动发现会残废一片。host 模式让容器直接共用宿主机网络栈，8123 端口直接落在宿主机上，省去端口映射，发现协议也全部通畅。代价是少了网络隔离，所以宿主机本身的防火墙要管好，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;千万不要图省事再把 8123 端口从路由器映射到公网&amp;lt;/span&amp;gt;，远程访问的正确姿势在后面专门讲。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;时区要双保险。&lt;/strong&gt; 环境变量 &lt;code&gt;TZ&lt;/code&gt; 和挂载 &lt;code&gt;/etc/localtime&lt;/code&gt; 两个都写上。HA 里大量自动化是按时间触发的，时区错了，所有定时都会跟着错位，排障一节有真实翻车场景。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;设备直通按需加。&lt;/strong&gt; 如果你用 USB 的 Zigbee 协调器（比如 Sonoff ZBDongle、CC2652 系列），就用 &lt;code&gt;devices&lt;/code&gt; 把串口透传进容器。先在宿主机上确认设备路径：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ls -l /dev/serial/by-id/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;强烈建议在集成里填 &lt;code&gt;by-id&lt;/code&gt; 路径而不是 &lt;code&gt;/dev/ttyUSB0&lt;/code&gt;——后者会随着插拔顺序漂移，今天认的是协调器，明天可能就变成别的 USB 设备了。&lt;/p&gt;
&lt;h2&gt;初始化与核心概念&lt;/h2&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;http://宿主机IP:8123&lt;/code&gt;，首次访问进入初始化向导：创建管理员账号（这就是你以后登录 HA 的主账号，密码强度别马虎）、设置家庭名称与地理位置（经纬度用于算日出日落，自动化里要用）、选择上报与否的匿名统计。向导走完进入主界面，系统通常已经自动发现了局域网里的一部分设备，先别急着点，理解四个概念再动手：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;设备（Device）&lt;/strong&gt;：一个物理硬件，比如一盏灯、一个传感器，在「设置 → 设备与服务」里以卡片形式存在。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;实体（Entity）&lt;/strong&gt;：设备提供的每一个可读可控的「点」。一盏灯可能有开关、亮度、色温三个实体；一个温湿度传感器有温度、湿度、电量三个实体。&lt;strong&gt;自动化和仪表盘操作的都是实体&lt;/strong&gt;，实体 ID 形如 &lt;code&gt;light.living_room&lt;/code&gt;、&lt;code&gt;sensor.temperature&lt;/code&gt;，后面写 YAML 全靠它。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;区域（Area）&lt;/strong&gt;：客厅、卧室、书房这样的逻辑分组，把设备归到区域里，仪表盘和语音控制都会清爽很多。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;集成（Integration）&lt;/strong&gt;：连接某个品牌或协议的「驱动」，在「设置 → 设备与服务 → 添加集成」里安装。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;接入设备：发现、集成与 MQTT&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;自动发现&lt;/strong&gt;：host 网络模式下，HA 会把局域网里支持的设备直接推到「设置 → 设备与服务」页面的待配置区，点进去按提示走完即可，米家、Yeelight、HomeKit 设备、飞利浦 Hue 桥等常见硬件大多能这样进来。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;手动添加集成&lt;/strong&gt;：没被发现的设备，在同一页面右下角「添加集成」，搜品牌名，按官方文档填 IP、Token 等参数。局域网直连类集成（如小米的 Xiaomi Miot）优先选本地模式，能不走云就别走云。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;MQTT 接入&lt;/strong&gt;：大量 DIY 设备和第三方网关走 MQTT 协议。HA 容器版没有插件商店，自备一个 Mosquitto 容器即可，写进同一个 Compose：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - &quot;1883:1883&quot;
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;mosquitto/config/mosquitto.conf&lt;/code&gt; 最小配置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;listener 1883
allow_anonymous false
password_file /mosquitto/config/pwfile
persistence true
persistence_location /mosquitto/data/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;生成密码文件后重启容器，再在 HA 里「添加集成 → MQTT」，填宿主机 IP 与账号密码完成对接。之后 Zigbee2MQTT、Tasmota 刷机设备、ESPHome 之外的自制传感器都能经这条通道进来。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;与监控联动&lt;/strong&gt;：如果你按本系列上一篇部署了 &lt;a href=&quot;/posts/selfhost-frigate/&quot;&gt;Frigate AI 监控&lt;/a&gt;，它原生就通过 MQTT 把「检测到人/车」的事件发出来，HA 订阅后就能实现「院子里检测到人 → 自动开院灯并推送通知」，两个系统是天生一对。&lt;/p&gt;
&lt;h2&gt;自动化实战：先搞懂三段式&lt;/h2&gt;
&lt;p&gt;HA 自动化的骨架永远是三段：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;trigger（什么事发生了）→ condition（现在满不满足条件）→ action（执行什么动作），三段齐全才是一条能跑的自动化。&amp;lt;/span&amp;gt;界面上可以可视化拖拽创建，但写 YAML 更直观也便于备份，配置都落在 &lt;code&gt;config/automations.yaml&lt;/code&gt; 里（在 &lt;code&gt;configuration.yaml&lt;/code&gt; 中需有 &lt;code&gt;automation: !include automations.yaml&lt;/code&gt;，默认模板已包含）。&lt;/p&gt;
&lt;h3&gt;例一：日落自动开玄关灯&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;- id: sunset_entry_light
  alias: 日落开玄关灯
  description: 太阳落山后自动打开玄关灯
  trigger:
    - platform: sun
      event: sunset
      offset: &quot;-00:15:00&quot;      # 提前 15 分钟，天刚擦黑就亮灯
  condition: []
  action:
    - service: light.turn_on
      target:
        entity_id: light.entry_light
      data:
        brightness_pct: 80
  mode: single
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;sun&lt;/code&gt; 触发器用的就是初始化时填的经纬度，这也是为什么向导那一步不能乱填。&lt;code&gt;offset&lt;/code&gt; 为负表示日落前触发，天没全黑灯先亮，体验好得多。&lt;/p&gt;
&lt;h3&gt;例二：夜间人体感应开夜灯&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;- id: night_motion_light
  alias: 夜间人体感应夜灯
  trigger:
    - platform: state
      entity_id: binary_sensor.hallway_motion
      to: &quot;on&quot;
  condition:
    - condition: time
      after: &quot;23:00:00&quot;
      before: &quot;06:00:00&quot;
    - condition: state
      entity_id: light.hallway_night_light
      state: &quot;off&quot;
  action:
    - service: light.turn_on
      target:
        entity_id: light.hallway_night_light
      data:
        brightness_pct: 15        # 深夜只给 15% 亮度，不晃眼
    - delay: &quot;00:02:00&quot;
    - service: light.turn_off
      target:
        entity_id: light.hallway_night_light
  mode: restart                   # 期间再次感应到人，重新计时
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这条把三段式用全了：触发是人体传感器状态变 &lt;code&gt;on&lt;/code&gt;；条件双保险——只在 23 点到次日 6 点之间、且灯当前是关着的才执行；动作是低亮度开灯、延时两分钟、关灯。&lt;code&gt;mode: restart&lt;/code&gt; 是关键细节：人还在走廊里活动时传感器会重复触发，计时从头来，避免灯在人眼前熄灭。&lt;/p&gt;
&lt;p&gt;改完 YAML 不用重启容器，在「开发者工具 → YAML」里点「重新加载自动化」即可生效。&lt;/p&gt;
&lt;h2&gt;仪表盘 Lovelace 基础&lt;/h2&gt;
&lt;p&gt;仪表盘（Lovelace）是 HA 的门面，默认会自动按区域生成概览页。想自己掌控，就在任意仪表盘右上角点「编辑仪表盘 → 原始配置编辑器」，或者直接写 YAML。最常用的几类卡片：实体卡、按钮卡、温湿度图表卡、摄像头卡。一个最小的自定义视图示例：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;views:
  - title: 客厅
    path: living
    cards:
      - type: entities
        title: 灯光
        entities:
          - light.living_room_main
          - light.living_room_ambient
      - type: sensor
        entity: sensor.living_room_temperature
        graph: line
        hours_to_show: 24
      - type: tile
        entity: binary_sensor.hallway_motion
        name: 走廊人体感应
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;建议节奏：先用自动生成的概览页跑一阵子，摸清自己每天真正看的是哪几个实体，再动手做精简版仪表盘——一上来就追求花哨大屏，多半是给自己挖坑。&lt;/p&gt;
&lt;h2&gt;远程访问：走反代，不裸奔&lt;/h2&gt;
&lt;p&gt;人在外面想看家里状态，需求很正当，但做法分高下。最差的做法是路由器端口映射把 8123 直接怼到公网：HA 的登录页这些年被扫描器盯得很紧，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;8123 裸奔公网约等于把家门钥匙挂在门把手上&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;正确姿势是走本系列讲过的 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager 反向代理&lt;/a&gt;：给 HA 配一个子域名（如 &lt;code&gt;ha.example.com&lt;/code&gt;），由 NPM 终止 HTTPS 再转发到内网 8123。HA 侧需要告诉它自己身后有反代，在 &lt;code&gt;configuration.yaml&lt;/code&gt; 里加：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.17.0.1        # 改成你 NPM 容器实际所在的网段/网关地址
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;少了这段，HA 会因为代理头不被信任而拒绝登录或日志里刷屏报错，这是反代接入 HA 最常见的坑。账号侧再补两道锁：管理员密码用密码管理器生成的长随机串，并在「个人资料 → 安全性」里开启双因素认证。更多自建服务的暴露面收敛思路，可以连同 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全与访问控制&lt;/a&gt; 一起看。&lt;/p&gt;
&lt;p&gt;:::warning
注意：如果你的 NPM 和 HA 不在同一台机器、或不在同一 Docker 网络里，&lt;code&gt;trusted_proxies&lt;/code&gt; 要填的是「NPM 向 HA 发起连接时，HA 看到的来源 IP」。填错的表现是登录时报 400 或反复跳回登录页，先查这个，不要先怀疑密码。
:::&lt;/p&gt;
&lt;h2&gt;备份：配置目录就是全部家当&lt;/h2&gt;
&lt;p&gt;容器版备份思路异常简单：HA 的全部状态——配置、自动化、仪表盘、集成凭据、历史数据库——都在挂载出来的 &lt;code&gt;config&lt;/code&gt; 目录里。停容器后整目录打包，就是一份完整备份：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/homeassistant
docker compose stop
tar czf ha-backup-$(date +%F).tar.gz config/
docker compose start
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意两点：一是打包前最好停容器，运行中直接拷 &lt;code&gt;home-assistant_v2.db&lt;/code&gt; 可能拷到写一半的数据库；二是这个压缩包里有各设备的 Token 和你的账号哈希，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;备份文件本身就是敏感数据，存放和传输都要当密钥对待&amp;lt;/span&amp;gt;。异地留存、版本保留策略这类通用方法论，本系列的 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移&lt;/a&gt; 讲得更系统，建议照着那套给 HA 也排上日程。HAOS 版自带的一键快照在容器版没有对应物，但整目录打包恢复起来同样是一条命令的事，并不吃亏。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：为什么我的 HA 里没有「插件商店」（加载项）？&lt;/strong&gt;
这是容器版与 HAOS 的固有差异，不是装坏了。Supervisor 和加载项只属于 HAOS。容器版的解法是把需要的附加服务（Mosquitto、Zigbee2MQTT、ESPHome、Node-RED 等）各自用 Docker 容器部署，再通过集成接入 HA——本文的 Mosquitto 就是这么来的。功能一个不少，只是管理入口分散在 Compose 文件里。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：设备频繁掉线、状态不更新怎么办？&lt;/strong&gt;
按顺序查：先看设备本身是否在线（品牌 App 或路由器客户端列表里确认）；再看协议通道——Zigbee 设备查协调器日志和信号强度（LQI），很多掉线是距离与干扰（协调器插在 USB 3.0 口旁边是经典干扰源，加一根 USB 延长线往往立竿见影）；Wi-Fi 设备查是不是路由器开了 AP 隔离或设备被分到了访客网络；最后才去怀疑 HA 本身，看「设置 → 系统 → 日志」里对应集成的报错。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：自动化写了却不触发，怎么排查？&lt;/strong&gt;
固定四步：一查触发器实体 ID 是否写对（去「开发者工具 → 状态」里核对实体当前状态与 ID，一个字母都不能错）；二查条件是否把自己拦了（在「设置 → 自动化」里打开这条自动化的「跟踪」功能，能看到每次触发在哪一段被挡下）；三查自动化本身是否被禁用、或 &lt;code&gt;mode&lt;/code&gt; 设置导致还在运行中拒绝新触发；四手动点自动化的「运行」按钮验证动作段本身能执行——动作能跑、自动不跑，问题一定在触发或条件段。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：定时自动化总是差几个小时执行？&lt;/strong&gt;
九成是时区问题。依次确认：宿主机 &lt;code&gt;timedatectl&lt;/code&gt; 显示的时区、Compose 里 &lt;code&gt;TZ&lt;/code&gt; 环境变量、HA「设置 → 系统 → 常规」里的时区三者必须一致，都是 &lt;code&gt;Asia/Shanghai&lt;/code&gt;。只改了 HA 界面没改容器时区的，日出日落类触发器会继续按 UTC 算，表现就是定时错乱但时钟显示正常，特别有迷惑性。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：改了 configuration.yaml 后 HA 起不来？&lt;/strong&gt;
先看日志定位：&lt;code&gt;docker compose logs homeassistant&lt;/code&gt; 会明确指出哪个文件哪一行语法错误。养成习惯：改 YAML 前在「开发者工具 → YAML」点「检查配置」，通过了再重载或重启。YAML 对缩进零容忍，混用 Tab 和空格是最常见死因。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇把 Home Assistant 的容器版从选型一路走到了能长期跑的状态：host 网络保住设备发现、设备直通收编 Zigbee、MQTT 打通 DIY 设备、自动化用 trigger/condition/action 三段式写、远程访问只走反代加双因素、备份就是定期打包 &lt;code&gt;config&lt;/code&gt; 目录。它和本系列其他服务的关系也顺手打通了：Frigate 供事件、NPM 管入口、备份体系兜底。&lt;/p&gt;
&lt;p&gt;HA 的水很深，仪表盘美化、能源管理、语音助手、复杂场景联动都还能再各写一篇。但把这一篇的骨架立稳，家里设备从「各管各的」变成「一个中枢说了算」，智能家居才算真正入了门。&lt;/p&gt;
</content:encoded></item><item><title>Immich：自建照片备份与智能相册</title><link>https://www.anexns.cloudns.org/posts/selfhost-immich/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-immich/</guid><description>按官方四容器架构用 Docker Compose 部署 Immich：手机照片自动备份、人脸识别与智能搜索、外部图库挂载，把全家人的照片从云端相册接回自己的服务器。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：全家人的照片，正在替别人交「房租」&lt;/h2&gt;
&lt;p&gt;手机相册是普通人最大的一笔数字资产：孩子的成长记录、旅行照片、证件扫描件，一年几千张往上走。云端相册看着方便，代价也明确：免费空间早就不够用，订阅按月扣费；原图可能被压缩；哪天账号出问题或服务调整政策，十几年的照片说没就没。更现实的是，很多人家里其实躺着一台 7×24 开机的服务器或者 NAS，硬盘空间大把，却没用在最该用的地方。&lt;/p&gt;
&lt;p&gt;Immich 就是把这件事接回来的工具：开源、自建，体验对标 Google 相册——时间线浏览、人脸分组、地图视图、智能搜索、手机 App 自动备份一应俱全，照片原图躺在你自己的硬盘上。本篇按官方推荐的 Docker Compose 架构完整部署一套，并把手机备份、外部图库、机器配置这些真正影响长期使用体验的环节讲透。部署前的整机规划可以先看 &lt;a href=&quot;/posts/selfhost-getting-started/&quot;&gt;自建服务入门：从一台 VPS 开始的完整规划&lt;/a&gt;；如果你已经有网盘类服务在跑，也可以先读系列里的 Cloudreve 私人云盘篇，想清楚照片到底归哪套系统管——结论先说：通用文件归网盘，照片和视频交给 Immich，两者分工不重叠。&lt;/p&gt;
&lt;h2&gt;架构先行：四个容器，各干一件事&lt;/h2&gt;
&lt;p&gt;Immich 不是单容器应用，官方 Compose 是四个服务协同，先理解架构再动手，后面排障会轻松很多：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;容器&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;immich-server&lt;/td&gt;
&lt;td&gt;主服务&lt;/td&gt;
&lt;td&gt;提供 Web 界面与 API、处理上传、管理图库，监听 2283 端口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;immich-machine-learning&lt;/td&gt;
&lt;td&gt;机器学习&lt;/td&gt;
&lt;td&gt;人脸识别、智能搜索的向量计算，独立容器方便单独加速或迁移&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;database&lt;/td&gt;
&lt;td&gt;PostgreSQL 数据库&lt;/td&gt;
&lt;td&gt;存照片元数据、向量数据，用的是带向量扩展的定制镜像&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;redis&lt;/td&gt;
&lt;td&gt;缓存/队列&lt;/td&gt;
&lt;td&gt;任务队列与缓存，官方新版 Compose 已换成 Valkey 镜像，作用相同&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;两个关键点先记住：第一，数据库用的是 Immich 官方定制的 PostgreSQL 镜像（带 VectorChord 等向量扩展），&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要图省事换成通用 postgres 镜像&amp;lt;/span&amp;gt;，智能搜索会直接罢工，升级时也不要擅自跨大版本换数据库镜像；第二，机器学习容器是整套系统里最吃资源的，模型文件要单独缓存，它慢不等于主服务坏了。&lt;/p&gt;
&lt;h2&gt;部署：官方 Compose 落地&lt;/h2&gt;
&lt;p&gt;新建一个目录，比如 &lt;code&gt;/opt/immich&lt;/code&gt;，在里面放两个文件。先是 &lt;code&gt;.env&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 照片库存放位置（原图+缩略图，空间要留足）
UPLOAD_LOCATION=./library
# 数据库存放位置（务必放在本地 SSD 上）
DB_DATA_LOCATION=./postgres
# 镜像版本，release 表示跟随最新正式版
IMMICH_VERSION=release
# 数据库密码，换成你自己的强密码
DB_PASSWORD=请换成强密码
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再是 &lt;code&gt;docker-compose.yml&lt;/code&gt;（结构与官方仓库当前版本一致，细节以官方最新文件为准）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - .env
    ports:
      - 2283:2283
    depends_on:
      - redis
      - database
    restart: always

  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    volumes:
      - model-cache:/cache
    env_file:
      - .env
    restart: always

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:8-bookworm
    restart: always

  database:
    container_name: immich_postgres
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: &apos;--data-checksums&apos;
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    restart: always

volumes:
  model-cache:
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/immich
docker compose up -d
docker compose logs -f immich-server
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;日志滚动到服务监听后，浏览器打开 &lt;code&gt;http://服务器IP:2283&lt;/code&gt;，第一个注册的账号就是管理员。和所有自建服务一样，这个位置要第一时间自己占住，并设强密码。&lt;/p&gt;
&lt;p&gt;:::warning
Immich 官方在文档里明确提醒：该软件仍在快速开发中，不应被视为照片的唯一存放方式。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Immich 是相册系统，不是备份系统本身&amp;lt;/span&amp;gt;——原图目录和数据库必须再有一份独立备份（见下文），否则硬盘坏掉时，相册做得再漂亮也救不回来。另外，数据库目录千万不要放在 NFS、SMB 这类网络盘上，PostgreSQL 在网络文件系统上极易损坏；照片库目录相对宽容，但为了缩略图生成速度，同样建议本地盘。
:::&lt;/p&gt;
&lt;h2&gt;机器配置要求：别让老硬件拖垮体验&lt;/h2&gt;
&lt;p&gt;Immich 的资源消耗主要来自三处：上传时的转码与缩略图生成、机器学习的人脸/向量计算、PostgreSQL 数据库。参考配置：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;项目&lt;/th&gt;
&lt;th&gt;最低可用&lt;/th&gt;
&lt;th&gt;舒适推荐&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;CPU&lt;/td&gt;
&lt;td&gt;2 核（支持 AVX 的 x86 或 ARM64）&lt;/td&gt;
&lt;td&gt;4 核以上&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;内存&lt;/td&gt;
&lt;td&gt;4 GB（官方下限附近，需加 swap 兜底）&lt;/td&gt;
&lt;td&gt;6–8 GB 以上&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据库盘&lt;/td&gt;
&lt;td&gt;本地 SSD&lt;/td&gt;
&lt;td&gt;NVMe SSD&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;照片盘&lt;/td&gt;
&lt;td&gt;按存量 + 未来 3 年增量预留&lt;/td&gt;
&lt;td&gt;机械盘阵列或大容量 SSD 均可&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GPU&lt;/td&gt;
&lt;td&gt;不需要&lt;/td&gt;
&lt;td&gt;可选：给机器学习容器换 CUDA 镜像加速识别&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;两个经验值：第一，老 CPU 没有 AVX2 时机器学习会明显变慢甚至跑不动部分模型，批量导入几万张照片时尤其明显，耐心等或错峰跑；第二，&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;数据库盘的速度直接决定时间线滑动和搜索的跟手程度，把 DB_DATA_LOCATION 放在 SSD 上，是整套系统性价比最高的一笔投入&amp;lt;/span&amp;gt;，照片原图放机械盘完全没问题。&lt;/p&gt;
&lt;h2&gt;手机 App 自动备份：装好之后就不用再管&lt;/h2&gt;
&lt;p&gt;Immich 的手机 App（iOS / Android 官方应用商店均可下载）是整套体验的核心，配置一次，之后全自动：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;打开 App，服务器地址填 &lt;code&gt;http://服务器IP:2283&lt;/code&gt;（内网）或后面配好的 HTTPS 域名；&lt;/li&gt;
&lt;li&gt;用管理员或自己的账号登录；&lt;/li&gt;
&lt;li&gt;点右上角云朵图标进入备份设置，打开「自动备份」，勾选要备份的相册（相机胶卷必选，微信、截图相册按需）；&lt;/li&gt;
&lt;li&gt;按需开启「仅 Wi-Fi 时备份」「仅充电时后台备份」，避免流量和电量焦虑；&lt;/li&gt;
&lt;li&gt;首次备份建议连着充电器、亮着屏跑完存量，之后增量都是秒传。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;备份完成后，Web 端时间线里就能按年月日浏览全部照片，同一张照片在手机删掉本地副本也不影响服务器上的原图——这才是「备份」该有的样子。给家人开账号时，每个人独立账号、独立图库，管理员在后台创建即可，互不可见。&lt;/p&gt;
&lt;h2&gt;外部图库：把已有的照片盘接进来&lt;/h2&gt;
&lt;p&gt;很多人部署 Immich 之前，照片已经躺在某个目录里了（比如 NAS 的共享盘、从旧网盘导出的存档），没必要重新上传一遍。用外部图库只读挂载进来即可。先给 immich-server 服务追加一行挂载：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /mnt/photos-archive:/mnt/photos-archive:ro
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意末尾的 &lt;code&gt;:ro&lt;/code&gt; 只读标记不能省。然后 &lt;code&gt;docker compose up -d&lt;/code&gt; 重建服务，再到 Web 界面：右上角头像 → 管理 → 外部图库 → 创建图库，导入路径填容器内路径 &lt;code&gt;/mnt/photos-archive&lt;/code&gt;，指定归属用户，保存后手动触发一次扫描。Immich 只读取和建立索引，不改动原文件，原始目录结构原封不动。后续往这个目录里丢新照片，Immich 会按计划自动重新扫描；也可以在图库设置里做排除规则，跳过缓存目录之类的杂项。&lt;/p&gt;
&lt;p&gt;外部图库和上传图库的区别要拎清：上传的照片归 Immich 全权管理（包括 App 里删除即真删），外部图库只读索引、不能在 Immich 里删原文件。珍贵存档用外部图库挂载更稳妥，日常手机照片走 App 备份，两条线并行不悖。&lt;/p&gt;
&lt;h2&gt;智能功能：人脸分组与智能搜索&lt;/h2&gt;
&lt;p&gt;机器学习容器就绪后（首次启动要下载模型，耐心等它跑完，&lt;code&gt;docker compose logs -f immich-machine-learning&lt;/code&gt; 能看到进度），两个能力会陆续生效：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;人脸识别&lt;/strong&gt;：自动把同一人的人脸聚成一组，在「探索」页给人物命名之后，就能按人翻照片，给孩子建一个从出生到现在的自动相册毫无压力；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;智能搜索&lt;/strong&gt;：基于 CLIP 模型的语义搜索，搜「海边」「雪」「猫」这类场景词就能出结果，不依赖文件名和标签。默认模型对中文支持一般，可以在管理后台的机器学习设置里更换为多语言 CLIP 模型，中文搜索会准很多。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;批量导入后的第一个晚上，建议让机器通宵跑任务队列：缩略图、人脸、向量都在排队生成，期间界面能用但搜索结果不全，这是正常现象，不是故障。&lt;/p&gt;
&lt;h2&gt;对外访问与 HTTPS&lt;/h2&gt;
&lt;p&gt;手机在外面也要能自动备份，就需要一个 HTTPS 入口，做法与系列其他服务一致：用 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager：所有自建服务的统一入口&lt;/a&gt; 新增 Proxy Host 指向 2283 端口并申请证书。Immich 会上传原图视频，体积大，记得在 NPM 的高级配置里放开请求体大小限制：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;client_max_body_size 0;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;同时把代理超时调大，避免长视频上传中途被掐断。安全方面，Immich 是全家照片的总仓，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;管理后台和图库绝不能裸奔在公网弱口令之下&amp;lt;/span&amp;gt;：强密码、关闭不必要的公开分享、只给家人开账号，具体原则见 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全加固：最小暴露与访问控制&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;备份：相册系统的备份要备两样东西&lt;/h2&gt;
&lt;p&gt;Immich 的完整备份 = 照片库目录 + 数据库导出，缺一不可：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;照片库&lt;/strong&gt;：&lt;code&gt;UPLOAD_LOCATION&lt;/code&gt; 指向的目录，含原图、缩略图、转码视频，直接按目录打包或用同步工具做异地副本；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;数据库&lt;/strong&gt;：存着相册结构、人物、标签等全部元数据，用容器内的 pg_dump 导出：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;docker exec -t immich_postgres pg_dumpall -c -U postgres | gzip &amp;gt; immich-db-$(date +%F).sql.gz
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;（容器名以你自己的 Compose 为准。）把两样东西按 3-2-1 原则纳入整机备份计划，脚本化方法见 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移实战&lt;/a&gt;。另外 Immich 自身升级较频繁，升级前先做一次完整备份，跨版本回滚时数据库能救命。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;App 连不上服务器。&lt;/strong&gt; 先在手机浏览器里直接打开同一个地址验证可达；内网用 IP+2283，走域名要确认 HTTPS 证书有效；公司或校园网拦截非标端口时，统一走 443 反向代理最省心。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;照片上传了但没有缩略图、人脸识别不动。&lt;/strong&gt; 十有八九是机器学习容器没正常工作：&lt;code&gt;docker compose logs immich-machine-learning&lt;/code&gt; 看是否在反复报错或还在下载模型；内存不足被 OOM 杀掉也会这样，&lt;code&gt;docker compose ps&lt;/code&gt; 看它是不是在反复重启，小内存机器先加 swap。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;时间线滑动卡顿、搜索很慢。&lt;/strong&gt; 检查数据库是不是被你放在了机械盘或网络盘上，迁回本地 SSD 立竿见影；照片量特别大时，也可以适当调高 PostgreSQL 的共享内存配置。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;数据库容器起不来。&lt;/strong&gt; 常见原因是数据目录权限不对或放在了不支持的文件系统上；确认 &lt;code&gt;DB_DATA_LOCATION&lt;/code&gt; 是本地目录、属主正确，再看 &lt;code&gt;docker compose logs database&lt;/code&gt; 的第一条报错。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;升级之后 Web 界面 500 或功能异常。&lt;/strong&gt; Immich 有时要求 server 与 machine-learning 镜像版本严格一致，两边都用同一个 &lt;code&gt;IMMICH_VERSION&lt;/code&gt;；先看官方发布说明有没有破坏性变更，再决定是否升级，出问题就用升级前的备份回滚，别在故障现场硬修数据库。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Immich 是自建服务里最能提升全家人幸福感的一个：按官方四容器架构部署，数据库放 SSD，手机 App 打开自动备份存量一次跑完，再把旧照片盘用外部图库只读挂进来，人脸分组和智能搜索会让翻照片从「找文件」变成「逛相册」。最后记住那句官方提醒——它再好用也只是相册系统，原图和数据库的独立备份一天都不能少。做到这几点，云端相册的订阅就可以停了。&lt;/p&gt;
</content:encoded></item><item><title>Jellyfin：私人影音库与硬件转码</title><link>https://www.anexns.cloudns.org/posts/selfhost-jellyfin/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-jellyfin/</guid><description>把硬盘里的电影、剧集和音乐做成一个真正的私人影音库：Jellyfin 的 Docker 部署、媒体目录规范与刮削、用户与权限、硬件转码（Intel 核显/NVIDIA）的开启与验证、客户端生态与远程访问。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说主线：硬盘里躺着的影片，值得一个像样的家&lt;/h2&gt;
&lt;p&gt;自建玩家走到影音这一步，手里多半已经攒了一堆资源：硬盘里按文件夹堆着的电影、剧集、演唱会和家庭录像。直接开文件夹找文件播，能播，但体验约等于没有：没有海报墙、没有简介、没有续播进度，电视上更是没法优雅地看。&lt;/p&gt;
&lt;p&gt;Jellyfin 就是把这堆文件变成「私人版流媒体平台」的工具：开源免费（它是 Emby 分叉出来的自由软件，没有任何会员和授权费用），自动刮削海报与元数据，按剧集整理季和集，多用户各自进度，几乎所有平台都有客户端。服务器负责整理与串流，电视、手机、平板打开 App 就能接着看。&lt;/p&gt;
&lt;p&gt;先把定位说清楚：Jellyfin 管的是&lt;strong&gt;你自己硬盘里已有的媒体文件&lt;/strong&gt;，把它变成一个带海报墙的私人流媒体平台。本文主线：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Docker 部署 Jellyfin&lt;/li&gt;
&lt;li&gt;媒体目录命名规范——这是刮削成功率的决定因素&lt;/li&gt;
&lt;li&gt;硬件转码：让核显或显卡干活，别让 CPU 硬扛&lt;/li&gt;
&lt;li&gt;用户、远程访问与备份&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;部署前：媒体文件从哪来、放哪&lt;/h2&gt;
&lt;p&gt;Jellyfin 本身不存媒体，它只是读取你指定的目录。所以先规划目录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;/media
├── movies/        # 电影
├── tv/            # 剧集
├── music/         # 音乐
└── homevideo/     # 家庭录像（不刮削，单独建库）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;媒体目录可以是本机硬盘，也可以是 NAS 挂载、甚至是 Cloudreve 网盘目录的本地落点。VPS 磁盘小的玩家更常见的组合是：媒体放家里 NAS 或大硬盘机器上，Jellyfin 也装在那台机器上，VPS 只做入口——影音这种大流量、吃硬件的活儿，本来就更适合放在家里。本文按「Jellyfin 与媒体在同一台机器」写，容器需要对媒体目录的读权限。&lt;/p&gt;
&lt;h2&gt;Docker Compose 部署&lt;/h2&gt;
&lt;p&gt;官方镜像 &lt;code&gt;jellyfin/jellyfin&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
      - PUID=1000
      - PGID=1000
    ports:
      - &quot;127.0.0.1:8096:8096&quot;
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /media:/media:ro
    # 硬件转码（二选一，见下文）：
    # Intel 核显：
    devices:
      - /dev/dri:/dev/dri
    # NVIDIA 显卡改用 runtime 方式，见下文
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;媒体目录用 &lt;code&gt;:ro&lt;/code&gt; 只读挂载是好习惯：Jellyfin 只需要读文件，刮削产生的海报和元数据都存在它自己的 &lt;code&gt;/config&lt;/code&gt; 里，给只读权限可以彻底避免误删原片。启动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;http://服务器IP:8096&lt;/code&gt; 走初始化向导：建管理员账号 → 添加媒体库（电影选 &lt;code&gt;/media/movies&lt;/code&gt;、剧集选 &lt;code&gt;/media/tv&lt;/code&gt;，类型别选错）→ 元数据语言设中文 → 完成。之后入口走 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager&lt;/a&gt; 反代到 8096 并套 HTTPS，远程观看必须走加密连接。&lt;/p&gt;
&lt;h2&gt;命名规范：刮削成功率全看它&lt;/h2&gt;
&lt;p&gt;Jellyfin 靠文件名和目录名去匹配在线数据库（TheMovieDB 等）的条目，命名乱就刮错、刮不到。规范很简单，照着改一遍文件名，后面全是省心：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;电影：
/media/movies/流浪地球 (2019)/流浪地球 (2019).mkv
/media/movies/Inception (2010)/Inception (2010).mkv

剧集：
/media/tv/权力的游戏 (2011)/Season 01/权力的游戏 S01E01.mkv
/media/tv/Breaking Bad (2008)/Season 02/Breaking Bad S02E03.mkv
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;文件夹名用「片名 (年份)」，集数用 &lt;code&gt;S01E02&lt;/code&gt; 这种国际通用标记，识别率最高&lt;/li&gt;
&lt;li&gt;一部电影一个文件夹，外挂字幕同名放旁边（&lt;code&gt;片名.zh.srt&lt;/code&gt; 这样带语言标记更稳）&lt;/li&gt;
&lt;li&gt;刮不到时进条目页用「识别」功能手动搜，或在文件夹名里加 TMDB ID，如 &lt;code&gt;片名 (2019) [tmdbid=xxxxxx]&lt;/code&gt; 强制指定&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;命名规范花一下午整理一次，胜过之后每次刮错了手动改一百次。&amp;lt;/span&amp;gt;整理文件名可以用 FileBot 这类工具批量处理，但改之前先备份目录清单，别批量改错了没法回滚。&lt;/p&gt;
&lt;h2&gt;硬件转码：这一篇的技术核心&lt;/h2&gt;
&lt;h3&gt;为什么需要转码&lt;/h3&gt;
&lt;p&gt;客户端能不能播某个文件，取决于它的解码能力。电视不支持片源的编码、手机在外网带宽不够、字幕是图片格式需要烧录——这些情况服务器都要把视频实时转成客户端能吃的格式，这就是转码。纯 CPU 软件转码压一部 4K 片源能把 CPU 跑满还卡顿；硬件转码把活交给核显/显卡的专用单元，功耗低、速度快，是影音服务器能不能用的分水岭。&lt;/p&gt;
&lt;p&gt;当然，最好的情况是&lt;strong&gt;直接播放（Direct Play）&lt;/strong&gt;：客户端能力够、带宽够，服务器只传文件不做任何处理，零负担。折腾转码是为了兜底那些播不动的场景。&lt;/p&gt;
&lt;h3&gt;Intel 核显（QSV / VAAPI）&lt;/h3&gt;
&lt;p&gt;Compose 里已经挂了 &lt;code&gt;/dev/dri&lt;/code&gt;。还要两步：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;确认宿主机能看到核显：&lt;code&gt;ls /dev/dri&lt;/code&gt; 应有 &lt;code&gt;renderD128&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Jellyfin 后台 → 控制台 → 播放 → 转码 → 硬件加速选 &lt;code&gt;Intel QuickSync (QSV)&lt;/code&gt;（或 VAAPI），勾选要硬解的编码格式，保存&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;权限报错是最常见的坑：容器里的用户要有权访问 &lt;code&gt;/dev/dri/renderD128&lt;/code&gt;。宿主机上查它的属组（一般是 &lt;code&gt;render&lt;/code&gt; 或 &lt;code&gt;video&lt;/code&gt; 组），把该组 ID 通过 Compose 的 &lt;code&gt;group_add&lt;/code&gt; 或环境变量给到容器：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    group_add:
      - &quot;105&quot;    # 换成宿主机上 render 组的实际 GID，用 getent group render 查
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;NVIDIA 显卡&lt;/h3&gt;
&lt;p&gt;NVIDIA 走容器运行时，Compose 写法不同：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=compute,video,utility
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;宿主机需先装好驱动和 NVIDIA Container Toolkit。后台硬件加速选 &lt;code&gt;NVIDIA NVENC&lt;/code&gt;。老显卡对新编码（如 AV1）的支持有限，能硬解哪些格式以显卡世代为准，勾选时只勾硬件真正支持的，不支持的会自动回落软解。&lt;/p&gt;
&lt;h3&gt;验证转码真的在工作&lt;/h3&gt;
&lt;p&gt;随便播一个需要转码的文件（比如把客户端画质手动调低到 720p 强制触发），然后：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Jellyfin 后台 → 控制台 → 活动，播放条目会标注转码原因&lt;/li&gt;
&lt;li&gt;播放详情（ffprobe/信息）里能看到转码方式&lt;/li&gt;
&lt;li&gt;Intel 核显：宿主机执行 &lt;code&gt;intel_gpu_top&lt;/code&gt; 能看到 Video 引擎有占用；NVIDIA：&lt;code&gt;nvidia-smi&lt;/code&gt; 能看到 jellyfin 的 ffmpeg 进程&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要没验证就默认硬转在工作&amp;lt;/span&amp;gt;——很多人装好后其实一直在软转，CPU 长期满载都不知道原因。活动页的转码信息和 GPU 占用是唯一可靠的证据。&lt;/p&gt;
&lt;p&gt;:::warning
4K HDR 转 SDR 的色调映射（Tone Mapping）非常吃性能，且需要额外的运行时库支持。低配机器建议：4K 片源单独建库、只在支持直放的设备上看，不要指望实时转码兜底，否则全家人一起卡。
:::&lt;/p&gt;
&lt;h2&gt;用户、权限与远程访问&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;多用户&lt;/strong&gt;：家里每人一个账号，各自的观看进度、收藏互不干扰；给孩子建单独账号，配合媒体库的访问控制和分级（年龄分级）限制可见内容&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;媒体库可见性&lt;/strong&gt;：用户设置里可按库授权，比如儿童账号只放动画库&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;远程访问&lt;/strong&gt;：Jellyfin 自带的「远程访问」设置允许外网连接，但&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把 8096 端口直接暴露到公网&amp;lt;/span&amp;gt;，走 NPM 的 HTTPS 反代是底线；只给家人用的话，再加一层访问控制更稳，做法见 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全加固&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;带宽限制&lt;/strong&gt;：后台可给远程播放设码率上限，避免一个人看片把家宽上行打满，影响全家网络&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;客户端生态&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;平台&lt;/th&gt;
&lt;th&gt;客户端&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Android / iOS&lt;/td&gt;
&lt;td&gt;Jellyfin 官方 App&lt;/td&gt;
&lt;td&gt;免费，支持下载离线&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Android TV / Apple TV&lt;/td&gt;
&lt;td&gt;官方 TV 客户端&lt;/td&gt;
&lt;td&gt;遥控器体验完整&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Windows / macOS&lt;/td&gt;
&lt;td&gt;Jellyfin Media Player&lt;/td&gt;
&lt;td&gt;解码能力强，最容易实现直放&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;网页&lt;/td&gt;
&lt;td&gt;任意浏览器&lt;/td&gt;
&lt;td&gt;免安装，但浏览器解码能力最弱、最容易触发转码&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;一个经验：同一部片在网页端卡、在桌面客户端流畅，通常不是服务器不行，而是浏览器不支持片源编码触发了转码。选客户端优先选解码能力强的，直放比例越高，服务器越轻松。&lt;/p&gt;
&lt;h2&gt;备份&lt;/h2&gt;
&lt;p&gt;Jellyfin 要备份的是 &lt;code&gt;./config&lt;/code&gt;：里面有全部用户、媒体库配置、元数据和观看记录。媒体文件本体不在备份范围（它们该有自己的存储冗余）。把 &lt;code&gt;config&lt;/code&gt; 纳入 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移实战&lt;/a&gt; 的常规节奏即可；注意备份时最好停一下容器或用其内置的数据库一致性方式，避免拷到写一半的数据库文件。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;媒体库扫描不到新文件&lt;/strong&gt;
先确认容器内能看到文件（&lt;code&gt;docker exec jellyfin ls /media/movies&lt;/code&gt;）；看不到是挂载问题，能看到则查命名规范和文件权限；手动在媒体库设置里点「扫描所有媒体库」。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;刮削出来全是错的或英文信息&lt;/strong&gt;
元数据语言和国家/地区在媒体库设置里改成中文；个别条目用「识别」手动指定；顽固的用文件夹名加 TMDB ID 锁定。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;播放卡顿、CPU 100%&lt;/strong&gt;
先看活动页是否在软转码。是软转的，按上文验证硬转配置；是直放还卡，查网络（远程走公网时上行带宽是瓶颈）和客户端解码。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;字幕不显示或乱码&lt;/strong&gt;
外挂字幕文件名要与视频同名并带语言后缀；编码以 UTF-8 为准，老的 GBK 字幕转码后再放进去。图片字幕（PGS）需要烧录，会强制触发转码，这是正常现象。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;容器里没有 /dev/dri&lt;/strong&gt;
宿主机层面核显被禁用或驱动没装好，先在宿主机 &lt;code&gt;ls /dev/dri&lt;/code&gt; 确认设备存在，容器才谈得上映射；云 VPS 大多没有核显，这类机器不适合做转码服务器，老老实实只直放，或者把 Jellyfin 装回家里有核显的机器。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Jellyfin 的三板斧：目录命名规范决定刮削、硬件转码决定播放流畅度、只读挂载加 config 备份决定数据安全。这三件做好，它就是全家人打开电视就能用的私人影音库，零会员费、零广告、进度全打通。&lt;/p&gt;
</content:encoded></item><item><title>Komari：轻量服务器监控探针部署与多节点接入</title><link>https://www.anexns.cloudns.org/posts/selfhost-komari/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-komari/</guid><description>手里三五台 VPS，状态全靠登录上去看？这篇部署开源轻量监控 Komari：一个面板汇总所有节点的 CPU、内存、磁盘与流量，再把 Agent 接入流程和多节点管理一次讲清。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：机器多了，状态不能靠「登上去看看」&lt;/h2&gt;
&lt;p&gt;自建服务上了规模之后，手里往往不止一台机器：主力 VPS 跑业务、家里小主机跑影音、还有一两台吃灰的小鸡做备份节点。平时风平浪静，直到某天服务打不开，登上机器才发现磁盘三天前就满了——这种教训，经历过一次就够了。&lt;/p&gt;
&lt;p&gt;监控要解决的其实是两个问题：&lt;strong&gt;现在怎么样&lt;/strong&gt;（实时状态）和&lt;strong&gt;刚才发生了什么&lt;/strong&gt;（历史曲线）。本篇主角 Komari 是一个开源的轻量级服务器监控：一个 Web 面板 + 每台机器一个 Agent，汇总展示 CPU、内存、磁盘、网络流量与在线状态，附带延迟 Ping 任务和历史图表。它的定位是「个人多节点看板」，部署五分钟，资源占用小到可以忽略，正合本系列的自建场景。&lt;/p&gt;
&lt;h2&gt;选型对比：Komari 放在什么位置&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方案&lt;/th&gt;
&lt;th&gt;部署成本&lt;/th&gt;
&lt;th&gt;资源占用&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Komari&lt;/td&gt;
&lt;td&gt;低，单容器面板 + 脚本装 Agent&lt;/td&gt;
&lt;td&gt;极低&lt;/td&gt;
&lt;td&gt;个人多台 VPS 状态汇总&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;哪吒监控&lt;/td&gt;
&lt;td&gt;低，生态成熟&lt;/td&gt;
&lt;td&gt;低&lt;/td&gt;
&lt;td&gt;节点多、需要丰富告警与任务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Zabbix&lt;/td&gt;
&lt;td&gt;高，组件多&lt;/td&gt;
&lt;td&gt;中高&lt;/td&gt;
&lt;td&gt;企业级、成百上千节点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Prometheus + Grafana&lt;/td&gt;
&lt;td&gt;中高，要写配置&lt;/td&gt;
&lt;td&gt;中&lt;/td&gt;
&lt;td&gt;指标深挖、自定义大盘&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;本站 Docker 系列写过 Prometheus 方案，那是「指标系统」的打法；Komari 是「看板」的打法。本篇不纠结谁更强：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;个人自建的监控第一诉求是所有机器一眼看全、异常有历史可查，Komari 用最低成本满足这两点。&amp;lt;/span&amp;gt;服务本身是否可用（HTTP 层面）则交给第 4 篇的 Uptime Kuma，两者分工不同、互不替代。&lt;/p&gt;
&lt;h2&gt;部署面板：一份 Compose&lt;/h2&gt;
&lt;p&gt;按系列规范装在 &lt;code&gt;/opt/apps/komari/&lt;/code&gt;，官方镜像来自 GitHub Container Registry：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  komari:
    image: ghcr.io/komari-monitor/komari:latest
    container_name: komari
    restart: unless-stopped
    ports:
      - &quot;25774:25774&quot;
    volumes:
      - ./data:/app/data
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/apps/komari
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Komari 的全部数据（节点信息、监控历史、账号配置）都存在 &lt;code&gt;/app/data&lt;/code&gt; 里，已经按规范挂到本目录的 &lt;code&gt;data/&lt;/code&gt; 下，备份时整个目录带走即可。面板默认端口 &lt;code&gt;25774&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;首次访问 &lt;code&gt;http://你的IP:25774&lt;/code&gt; 进入初始化：设置管理员用户名和密码。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;这个密码就是所有服务器状态的总钥匙，必须用独立强密码&amp;lt;/span&amp;gt;，不要和任何其他服务复用——密码该怎么管，第 11 篇的 Vaultwarden 会给出答案，先从不复用做起。&lt;/p&gt;
&lt;h2&gt;套上域名：通过 NPM 反代&lt;/h2&gt;
&lt;p&gt;裸奔的 &lt;code&gt;IP:25774&lt;/code&gt; 只是临时入口。按第 2 篇 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager：所有自建服务的统一入口&lt;/a&gt; 的流程，给 Komari 加一条 Proxy Host：子域名如 &lt;code&gt;status.example.com&lt;/code&gt;，转发到 &lt;code&gt;172.17.0.1:25774&lt;/code&gt;，申请证书并 Force SSL。Komari 面板有实时数据推送，添加时记得打开 Websockets Support，否则实时曲线可能不刷新。&lt;/p&gt;
&lt;p&gt;反代完成后，宿主机防火墙只放行 80/443/SSH，25774 不再对公网开放。注意一个细节：Agent 与面板之间的通信也走这个域名（下一节），所以这个子域名等于监控系统的生命线，DNS 解析要保持稳定。&lt;/p&gt;
&lt;h2&gt;接入节点：Agent 安装&lt;/h2&gt;
&lt;p&gt;面板装好只是空壳，数据来自每台机器上的 Agent。接入流程是「面板生成命令，节点执行命令」：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;登录面板后台，进入节点管理，添加一个节点，给它起个能认出来的名字（如 &lt;code&gt;主力-HK&lt;/code&gt;、&lt;code&gt;家里-NAS&lt;/code&gt;）。&lt;/li&gt;
&lt;li&gt;面板会为该节点生成一条专属的 Agent 安装命令，形如：&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code&gt;bash &amp;lt;(curl -sL https://raw.githubusercontent.com/komari-monitor/komari-agent/main/install.sh) -e https://status.example.com -t &amp;lt;该节点的令牌&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;ol&gt;
&lt;li&gt;到被监控的机器上以 root 执行这条命令。脚本会下载 Agent、写入配置并注册为系统服务，开机自启、掉线自动重连。&lt;/li&gt;
&lt;li&gt;回到面板，节点状态变绿，实时数据开始上报。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;命令里两个参数：&lt;code&gt;-e&lt;/code&gt; 是面板地址（Endpoint），&lt;code&gt;-t&lt;/code&gt; 是节点令牌（Token）。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;令牌等同于该节点的身份凭证，不要截图外发、不要写进公开仓库&amp;lt;/span&amp;gt;；怀疑泄露时在面板里删除该节点重新添加，旧令牌立即失效。&lt;/p&gt;
&lt;p&gt;Agent 的通信方向是「节点主动连面板」，所以被监控机器不需要开放任何入站端口，NAT 后面的家用设备也能接入，只要它能访问面板域名。这一点让 Komari 特别适合「VPS + 家里小主机」的混合舰队。&lt;/p&gt;
&lt;h2&gt;面板能看什么&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;实时状态&lt;/strong&gt;：每台节点的 CPU、内存、磁盘、网络速率与在线状态，首页卡片式排布，多台机器一屏看全。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;历史曲线&lt;/strong&gt;：负载、流量等指标的历史图表——排障时先看这里，「服务是几点开始变慢的」往往曲线上写着答案。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;流量统计&lt;/strong&gt;：按节点统计流量消耗，对有月流量额度的 VPS 尤其重要，超额前心里有数。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Ping 任务&lt;/strong&gt;：可以配置从各节点向指定目标发起的延迟探测，用来观察不同线路到某个地址的延迟与丢包，比如多台机器到你家宽带、或到常用服务的线路质量。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;公开访问方面，面板支持以访客模式展示（不登录也能看状态页）。是否开放看个人：状态页方便随时瞄一眼，但也等于公开了你的机器配置与在线规律，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;节点备注里不要写真实 IP、机房账号等敏感信息&amp;lt;/span&amp;gt;，名字用代号即可。&lt;/p&gt;
&lt;h2&gt;多节点接入的实务要点&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;时间要同步。&lt;/strong&gt; 各节点系统时间偏差会让曲线对不齐、历史数据错位。所有机器开启 NTP 自动同步（&lt;code&gt;timedatectl set-ntp true&lt;/code&gt;），面板机尤其要准。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;命名先行统一。&lt;/strong&gt; 节点一旦多起来，「new-server-3」这种名字会让你在凌晨排障时崩溃。建议一开始就定好规则：&lt;code&gt;用途-地区&lt;/code&gt;，如 &lt;code&gt;业务-香港&lt;/code&gt;、&lt;code&gt;影音-家里&lt;/code&gt;、&lt;code&gt;备份-洛杉矶&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;面板本身也要被监控。&lt;/strong&gt; Komari 挂了不会有人通知你——它就是通知系统的一部分解。把面板域名加进第 4 篇 &lt;a href=&quot;/posts/selfhost-uptime-kuma/&quot;&gt;Uptime Kuma：服务可用性监控与公开状态页&lt;/a&gt; 的监控列表，用外部视角盯它。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;告警别指望面板单打独斗。&lt;/strong&gt; Komari 擅长展示，告警与通知策略（离线多久算故障、通知发给谁、半夜要不要吵醒人）是第 5 篇 &lt;a href=&quot;/posts/selfhost-monitoring-alerts/&quot;&gt;监控告警实战：通知、值班与故障处理流程&lt;/a&gt; 的主题，两篇配合才算完整的监控闭环。&lt;/p&gt;
&lt;h2&gt;排障：节点不上线怎么办&lt;/h2&gt;
&lt;p&gt;按这个顺序查，基本能覆盖九成情况：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Agent 服务在不在跑&lt;/strong&gt;：在节点上执行 &lt;code&gt;systemctl status komari-agent&lt;/code&gt;（服务名以安装脚本实际注册为准），不在跑就看它的日志报错。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;端点通不通&lt;/strong&gt;：在节点上 &lt;code&gt;curl -v https://status.example.com&lt;/code&gt;，看 DNS 解析、证书、连通性哪一步断。面板若刚换过证书或反代配置，这里最容易出问题。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;令牌对不对&lt;/strong&gt;：命令是不是从当前节点的详情里复制的、粘贴时有没有少字符。删了重加节点是最快的验证办法。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;时间对不对&lt;/strong&gt;：节点时间偏差过大可能导致连接被拒，先 &lt;code&gt;date&lt;/code&gt; 对一眼。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;面板侧问题则先看容器日志：&lt;code&gt;cd /opt/apps/komari &amp;amp;&amp;amp; docker compose logs -f&lt;/code&gt;，再确认 &lt;code&gt;data/&lt;/code&gt; 目录可写、磁盘没满——监控数据写不进去时面板会表现得像「所有节点都离线」。&lt;/p&gt;
&lt;p&gt;:::warning
监控系统最危险的失效模式不是报错，而是「静默死亡」：面板进程还在，但数据停了，你看着昨天的绿色状态以为一切正常。养成习惯：每次打开面板先扫一眼数据更新时间；同时用 Uptime Kuma 从外部盯住面板本身，让两个系统互相守夜。
:::&lt;/p&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：Agent 占用多少资源？&lt;/strong&gt;
极小，常态 CPU 接近 0、内存十几 MB 量级，老机器、便宜小鸡都能放心装。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：节点离线多久面板会标记离线？&lt;/strong&gt;
Agent 保持长连接上报，断连后很快就会显示离线。是否要为此发通知、等多久发，属于告警策略问题，放到第 5 篇统一设计，避免短暂抖动半夜连环轰炸。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：Windows 或 NAS 能接入吗？&lt;/strong&gt;
Agent 有多平台版本，官方仓库提供对应安装方式；NAS 若支持 SSH 与脚本执行一般也能装。实在装不了 Agent 的设备，用第 4 篇的可用性监控盯它的服务端口即可。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：数据保留多久？磁盘会不会被监控数据吃满？&lt;/strong&gt;
Komari 是轻量设计，历史数据体积增长缓慢。稳妥起见把 &lt;code&gt;data/&lt;/code&gt; 纳入第 11 篇的备份与容量巡检范围，磁盘告警线设在 80%，别等满了才发现。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Komari 的部署可以概括为：一份 Compose 起面板、NPM 套上域名证书、每台机器执行一条面板生成的命令接入 Agent。十分钟之后，你的所有服务器从「各自为政」变成「一屏看全」，历史曲线和流量统计也都有了。但监控的价值一半在看、另一半在报——服务真挂了，谁在什么时候以什么方式通知你？下一篇先用 Uptime Kuma 把「服务可用性」这条线补上，再往后一篇专门讲告警与处理流程。&lt;/p&gt;
</content:encoded></item><item><title>自建服务实战：LibreGet 万能下载管理器</title><link>https://www.anexns.cloudns.org/posts/selfhost-libreget/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-libreget/</guid><description>LibreGet 开源免费桌面下载管理器实战：一个窗口下载课程、YouTube、Bilibili、Instagram 等 1800 多个站点的内容，断点续传、浏览器扩展取登录态、158 个内置工具与给 AI 助手调用的 MCP 接口。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：下载这件事，工具为什么越攒越多&lt;/h2&gt;
&lt;p&gt;想把自己买的网课存到本地慢慢看，要装一个课程下载工具；想存 YouTube 视频，得记住 yt-dlp 那一长串参数，隔两个月不用就忘光；想存 Instagram 的动态、X 上的视频、Pinterest 的图板，又得各找一个网页下载站，界面全是广告，还动不动失效。工具散落一地，每个只管一摊，下载完的文件还得自己另外找播放器、找转码工具、找字幕工具。&lt;/p&gt;
&lt;p&gt;LibreGet 的思路是把这一摊事收进一个桌面窗口：&lt;strong&gt;粘贴链接 → 预览选清晰度 → 下载 → 在同一个应用里播放、阅读、转录、转换、管理&lt;/strong&gt;。底层该用 yt-dlp 的地方用 yt-dlp，该用原生解析的地方用原生解析，全部封装好，不用碰终端。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/OpenSelena/libreget&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;它是什么 → 能下什么 → 核心工作流 → 浏览器扩展配对 → 下完之后的管理与工具 → 给 AI 助手用的接口 → 三平台安装与首次启动排障 → 便携模式&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;它是什么&lt;/h2&gt;
&lt;p&gt;LibreGet 是一个开源免费的桌面下载管理器，用 Tauri 2.0 + Rust + Svelte 编写，GPL-3.0 协议，Windows、macOS、Linux 三平台全覆盖。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;它的定位很明确：免费、无账号、无广告、不收集你的下载记录，所有文件只落在你自己的电脑上。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;几个关键设计先交代清楚：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;引擎自动托管&lt;/strong&gt;：yt-dlp 和 FFmpeg 由应用自己下载、校验 SHA-256、保持更新，你不需要装 Python、不需要配环境变量、不需要开终端。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;原生解析优先&lt;/strong&gt;：课程、Instagram、X、Pinterest、Bilibili、Telegram、种子这些高频场景有原生解析器，其余 1800 多个站点交给 yt-dlp 兜底。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;纯本地运行&lt;/strong&gt;：没有官方服务器在中间中转。应用自己发起的网络请求只有三类——你让它下载的站点、去 GitHub 检查更新、以及你配置的 AI 服务（用 AI 工具时）。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;能下什么&lt;/h2&gt;
&lt;h3&gt;在线课程：38 个平台&lt;/h3&gt;
&lt;p&gt;内置的课程插件支持 38 个学习平台，包括 Udemy、Hotmart、Coursera、Domestika、Skillshare、Kiwify、Rocketseat 等。在应用内登录你的账号后，它会列出你已购买的课程，打开课程大纲勾选要下的章节，连同课件附件一起下载，支持断点续下和连续编号整理。这里的口径要说清：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;它只能下载你自己账号已经购买、能正常打开的课程，带 DRM 保护的课时会被自动跳过并报告，不做任何破解。&amp;lt;/span&amp;gt;买过的课趁平台还在先备份到本地，是这类工具最正当的用途。&lt;/p&gt;
&lt;h3&gt;视频与音频：1800 多个站点&lt;/h3&gt;
&lt;p&gt;YouTube（视频、播放列表、频道、直播回放、章节、SponsorBlock 跳过）、Instagram、TikTok、X、Reddit、Twitch（点播、剪辑、直播）、Vimeo、Bluesky、Threads、Pinterest、抖音等热门站点有专门优化，其余长尾站点由 yt-dlp 覆盖，总数 1800 以上。保存格式上，视频可存 MP4、MKV、WebM，音频可存 MP3、M4A、Opus、FLAC、WAV，字幕可存 SRT、VTT、ASS，可内嵌也可旁挂。&lt;/p&gt;
&lt;h3&gt;Bilibili：登录后的完整体验&lt;/h3&gt;
&lt;p&gt;登录自己的 Bilibili 账号后，按账号权限下载 4K、HDR、杜比视界、高清无损音频；弹幕可导出为 XML、ASS 或 JSON，还能生成供 Kodi 和 Jellyfin 识别的 NFO 文件，支持番剧、课程、收藏夹、稍后再看、历史记录等 11 类链接。&lt;/p&gt;
&lt;h3&gt;图库与其它&lt;/h3&gt;
&lt;p&gt;图库走 gallery-dl 引擎，覆盖 DeviantArt、Pixiv、ArtStation、Flickr、Tumblr、Imgur 等 250 多个站点，可整站、整画师、整图板备份。另外还支持 &lt;code&gt;.torrent&lt;/code&gt; 文件与磁力链接（内置 BitTorrent 客户端）、Telegram 频道与群组里的文件（内置 Telegram 插件，按频道自动归档到 &lt;code&gt;LibreGram/&amp;lt;频道名&amp;gt;/&lt;/code&gt; 文件夹）、批量粘贴链接或导入 &lt;code&gt;.txt&lt;/code&gt; 批量下载、两台 LibreGet 之间用短口令互传文件。&lt;/p&gt;
&lt;h2&gt;和其它方案比一比&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;LibreGet&lt;/th&gt;
&lt;th&gt;裸用 yt-dlp&lt;/th&gt;
&lt;th&gt;单站网页下载站&lt;/th&gt;
&lt;th&gt;付费课程下载器&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;站点覆盖&lt;/td&gt;
&lt;td&gt;课程、Instagram、X、Pinterest、Bilibili、Telegram、种子原生支持，另加 yt-dlp 的 1800+&lt;/td&gt;
&lt;td&gt;1800+&lt;/td&gt;
&lt;td&gt;一个&lt;/td&gt;
&lt;td&gt;一两个平台&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;安装门槛&lt;/td&gt;
&lt;td&gt;下载一个文件打开即用&lt;/td&gt;
&lt;td&gt;Python、PATH、FFmpeg、记参数&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;安装包加许可证密钥&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;登录内容&lt;/td&gt;
&lt;td&gt;浏览器扩展转发你的登录态&lt;/td&gt;
&lt;td&gt;手动导出 &lt;code&gt;--cookies&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;基本不行&lt;/td&gt;
&lt;td&gt;部分支持&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;下载队列&lt;/td&gt;
&lt;td&gt;断点续传、退避重试、规则分流、订阅频道自动下新&lt;/td&gt;
&lt;td&gt;一次一条命令&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;不一定&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;下完之后&lt;/td&gt;
&lt;td&gt;播放器、阅读器、闪卡、笔记、158 个工具&lt;/td&gt;
&lt;td&gt;只有文件&lt;/td&gt;
&lt;td&gt;只有文件，还常被转码&lt;/td&gt;
&lt;td&gt;只有文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;价格与协议&lt;/td&gt;
&lt;td&gt;免费，GPL-3.0&lt;/td&gt;
&lt;td&gt;免费，Unlicense&lt;/td&gt;
&lt;td&gt;免费但带广告&lt;/td&gt;
&lt;td&gt;订阅付费&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;结论很直白：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;如果你就住在终端里、只要文件本身，裸用 yt-dlp 就够了；如果你想要一个窗口管完下载加整理，LibreGet 是目前开源里完成度最高的那个。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;核心工作流：一分钟下第一个文件&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;打开 LibreGet，首次启动选好语言和主题，点一下它就自动装好 yt-dlp 和 FFmpeg（下载后先验 SHA-256 再运行）。&lt;/li&gt;
&lt;li&gt;复制任意链接：YouTube 视频、Instagram 短视频、X 帖子、Pinterest 图板、磁力链接、直链文件都行。&lt;/li&gt;
&lt;li&gt;粘贴到主页的输入框，它自动识别站点，展示标题、缩略图和可选清晰度，选好按回车开下。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;下载页会实时显示速度、阶段和预计剩余时间（数据直接读自下载引擎，卡住就是卡住，不会假装还剩 3 秒）。几个用顺手之后回不去的设计：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;断点续传&lt;/strong&gt;：中断的任务保留部分文件，下次接着下；遇到限流自动退避重试；每个站点的并发连接数自适应——YouTube 可以拉到 16 路分片并行，返回 429 的站点自动降速。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;全局热键&lt;/strong&gt;：在任何地方复制链接后按 &lt;code&gt;Ctrl+Shift+D&lt;/code&gt;（macOS 是 &lt;code&gt;Cmd+Shift+D&lt;/code&gt;），后台直接开下，不用切窗口；&lt;code&gt;Ctrl+Shift+M&lt;/code&gt; 只抓音频，YouTube 链接直接变 MP3。这两个热键默认关闭，在「设置 → 下载 → 剪贴板与热键」里开启，也可以改键。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;一次设置长期生效&lt;/strong&gt;：默认清晰度、纯音频格式、字幕语言与格式、文件名模板、按平台分文件夹、跳过已存在文件、限速、并发数都可以预设；规则功能可以把某个频道或站点固定分流到指定文件夹和清晰度；订阅的频道会在后台检查更新，有新内容自动下载并托盘通知。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;每条任务留底&lt;/strong&gt;：每个下载任务都保存它实际执行的 yt-dlp 命令，打开就能看，想改参数重试不用重新拼命令。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;命令行党也有份：每次发布都带 &lt;code&gt;libreget-cli&lt;/code&gt;，常用法如下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;libreget info &amp;lt;url&amp;gt;                        # 只看标题、格式和大小，不下载
libreget download &amp;lt;url&amp;gt; -q 1080 -o ~/Videos
libreget download &amp;lt;url&amp;gt; --audio-only --subs en,zh
libreget batch links.txt -m 3              # 一行一个链接，3 个并发
libreget import-cookies cookies.txt        # Netscape 格式
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;浏览器扩展：登录内容的关键一环&lt;/h2&gt;
&lt;p&gt;很多内容不登录看不到：你买的课、仅粉丝可见的视频、Instagram 的限时动态。LibreGet 处理登录态的方式是装一个浏览器扩展，由它把你在浏览器里的登录 Cookie 和来源页一起转发给应用——前提永远是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;那是你自己的账号、你自己的浏览器会话，它不绕过任何登录墙和付费墙&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;扩展在已识别的站点（YouTube、Instagram、TikTok、X、Reddit、Twitch、Pinterest、Bluesky、Telegram、Vimeo、Udemy、Hotmart、Bilibili、SoundCloud 等）上点图标或按 &lt;code&gt;Alt+O&lt;/code&gt; 一键发送当前页；对其它站点，它会嗅探页面里的 MP4、HLS、DASH、WebM 和音频流列在弹窗里供你挑。装法分三档，由简到繁：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一档：应用内安装（推荐，不用下载任何压缩包）&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;打开 LibreGet，进入「设置 → 插件 → 浏览器扩展」，点 Chrome 旁边的「更新/安装」，它会把内置的扩展复制到一个文件夹并自动打开。&lt;/li&gt;
&lt;li&gt;在 Chrome（Edge、Brave 等 Chromium 浏览器同理）地址栏输入 &lt;code&gt;chrome://extensions&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;打开右上角的「开发者模式」。&lt;/li&gt;
&lt;li&gt;点「加载已解压的扩展程序」，选中刚才打开的文件夹。&lt;/li&gt;
&lt;li&gt;工具栏出现 LibreGet 图标，一个选项页会自动打开并寻找应用。&lt;/li&gt;
&lt;li&gt;回到 LibreGet 同一设置页，点「配对扩展」，几秒后显示「扩展已连接」，选项页变绿，完成。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;第二档：用发布包里的 zip&lt;/strong&gt;。每个版本都附带 &lt;code&gt;libreget-chrome-extension-vX.Y.Z.zip&lt;/code&gt;，解压后按第一档第 3 步往下走即可。适合浏览器和应用不在同一台机器，或者帮别人装的场景。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第三档：Firefox 与手动配对&lt;/strong&gt;。Firefox 在同样的设置页点 Firefox 的「更新/安装」，再打开 &lt;code&gt;about:debugging#/runtime/this-firefox&lt;/code&gt;，点「临时加载附加组件」选导出文件夹里的 &lt;code&gt;manifest.json&lt;/code&gt;（注意 Firefox 临时组件重启后会掉，要重装一次，等上架官方商店后就没这问题；Safari 暂不支持）。如果自动配对超时，打开扩展的选项页，把 LibreGet 里显示的配对令牌粘贴进去即可——应用只监听本机 &lt;code&gt;127.0.0.1&lt;/code&gt; 的 47720–47729 端口，令牌每台机器独立生成，数据不出本机。&lt;/p&gt;
&lt;p&gt;小提醒：如果扩展装了但 LibreGet 没开着，点击会走 &lt;code&gt;libreget://&lt;/code&gt; 链接唤起应用排队，但带不了 Cookie；Chrome 第一次问是否允许时记得勾「始终允许」。&lt;/p&gt;
&lt;h2&gt;下完之后：不只是个下载器&lt;/h2&gt;
&lt;p&gt;LibreGet 真正和其它下载工具拉开差距的是下载之后：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;内置播放器与阅读器&lt;/strong&gt;：下完的课程直接在应用里播，PDF 直接在应用里读，还有闪卡和笔记功能，备份下来的课不用再倒腾到别的软件里。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;158 个内置小工具（25 类）&lt;/strong&gt;：每个工具是一个独立的 Rust 命令，全部在本机运行。挑最实用的几类说：
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;语音与字幕（8 个）&lt;/strong&gt;：用 whisper.cpp 本地离线转录音视频成字幕（模型按需下载）、字幕翻译、文字转语音、按字幕配音等。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;视频编辑（14 个）&lt;/strong&gt;：截取片段、转码换容器/编码/分辨率、精确压缩到指定大小（如 10 MB 发 Discord）、视频转 GIF、剪静音段、字幕格式互转与烧录、字幕对轴、画面防抖与修复、录屏。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;PDF（13 个）&lt;/strong&gt;：合并、拆分、压缩、转换、OCR、修复、加解密与权限、水印页码、裁边、生成目录、转 Markdown 等。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;平台工具&lt;/strong&gt;：YouTube 工具 11 个（封面、评论导出、双语字幕合并等）、Instagram 24 个、X 10 个、Pinterest 10 个，另有图片、文档、音频（响度标准化、降噪）、系统、CTF 分析等类别。&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;命令面板&lt;/strong&gt;：&lt;code&gt;Ctrl+K&lt;/code&gt;（macOS &lt;code&gt;Cmd+K&lt;/code&gt;）直达任意页面、设置或工具；还有 14 套主题、12 种界面语言（含简体中文）可选。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;下完的影音文件如果量大，建议归档进媒体库统一管理——本系列的 &lt;a href=&quot;/posts/selfhost-jellyfin/&quot;&gt;Jellyfin 影音库&lt;/a&gt; 正是干这个的；散文件想跨设备随时取用，可以放进 &lt;a href=&quot;/posts/selfhost-alist/&quot;&gt;Alist 网盘聚合&lt;/a&gt;；多台设备之间的文件夹同步方案见 &lt;a href=&quot;/posts/selfhost-file-sync/&quot;&gt;文件同步篇&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;给 AI 助手用的接口：MCP 与插件&lt;/h2&gt;
&lt;p&gt;这是 LibreGet 一个很超前的设计：它内置了 MCP 服务器。工具的内部实现本来就是「JSON 进、JSON 出」的独立命令，所以开放给 AI 助手几乎是顺手的事。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;应用内 MCP 服务器&lt;/strong&gt;：在「工具 → AI → MCP 服务器」里开启后，它通过与浏览器扩展相同的本机桥接通道、同一套每机独立令牌，对外提供 37 个工具。助手可以把链接加入下载队列并查看、暂停、恢复、取消任务，可以合并拆分 PDF、转录文件、文字转语音、OCR、图片缩放去重、文件搜索等。设置页直接给出 Claude Code、Claude Desktop、Cursor、VS Code、Goose、Codex 的现成配置片段，复制粘贴即可，不用自己拼。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Claude Code 插件&lt;/strong&gt;：仓库里的 &lt;code&gt;claude-plugin/&lt;/code&gt; 文件夹提供一个不需要桌面应用的插件，粘贴视频、音频或社交帖子链接并说明需求，&lt;code&gt;libreget-fetch&lt;/code&gt; 与 &lt;code&gt;libreget-transcribe&lt;/code&gt; 两个技能会自动触发；也可以用斜杠命令显式调用：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;/plugin marketplace add /path/to/libreget/claude-plugin
/plugin install libreget
/libreget:setup                    # 一次确认后装好 yt-dlp、ffmpeg 与 libreget-cli
/libreget:fetch &amp;lt;url&amp;gt; [--audio]    # 下载媒体到 ~/Downloads/libreget
/libreget:transcribe &amp;lt;url|file&amp;gt;    # 先取字幕，再本地 whisper.cpp，最后才用云端
/libreget:research &amp;lt;url&amp;gt;           # 字幕加转录整理成带 [mm:ss] 引用的 Markdown 笔记
/libreget:doctor                   # 检查装了什么、缺什么、怎么补
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
MCP 服务器和浏览器扩展共用同一个本机令牌，令牌只在本机使用、不要外发给任何人或粘贴到在线服务里；给助手开 MCP 等于允许它调用你电脑上的下载与文件工具，装好后先在小任务上试一轮，确认行为符合预期再放手批量使用。
:::&lt;/p&gt;
&lt;h2&gt;安装：三平台各自的拿法&lt;/h2&gt;
&lt;p&gt;所有版本都在 GitHub 的 Releases 页发布，应用内可自动更新。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;系统&lt;/th&gt;
&lt;th&gt;下载什么&lt;/th&gt;
&lt;th&gt;其它装法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Windows 10 / 11&lt;/td&gt;
&lt;td&gt;&lt;code&gt;libreget_x.y.z_x64-setup.exe&lt;/code&gt;（安装版）、&lt;code&gt;libreget_x.y.z_x64-portable.exe&lt;/code&gt;（便携版）、&lt;code&gt;libreget_x.y.z_x64_en-US.msi&lt;/code&gt;（批量部署）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;winget install -e --id OpenSelena.LibreGet&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;macOS 10.15+&lt;/td&gt;
&lt;td&gt;Apple 芯片用 &lt;code&gt;libreget_x.y.z_aarch64.dmg&lt;/code&gt;，Intel 用 &lt;code&gt;libreget_x.y.z_x64.dmg&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;brew install --cask OpenSelena/tap/libreget&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Linux&lt;/td&gt;
&lt;td&gt;Debian/Ubuntu 用 &lt;code&gt;.deb&lt;/code&gt;，Fedora/openSUSE/RHEL 系用 &lt;code&gt;.rpm&lt;/code&gt;，其它发行版用 &lt;code&gt;.AppImage&lt;/code&gt;（均含 x86_64 与 ARM64）&lt;/td&gt;
&lt;td&gt;AppImage 靠随附的 &lt;code&gt;.zsync&lt;/code&gt; 文件自更新&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;命令行一把梭的装法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;winget install -e --id OpenSelena.LibreGet
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;brew install --cask OpenSelena/tap/libreget
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;务必只从 GitHub 官方 Releases、winget 或上述 Homebrew 仓库安装，不要从来路不明的下载站拿安装包——这类热门免费工具最容易被捆绑恶意软件重新打包。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;便携模式：整个应用装进 U 盘&lt;/h2&gt;
&lt;p&gt;Windows 下在便携版 &lt;code&gt;.exe&lt;/code&gt; 同目录新建一个空文件 &lt;code&gt;portable.txt&lt;/code&gt;（或 &lt;code&gt;.portable&lt;/code&gt;），重新启动后，设置、数据库、Cookie、插件、缓存以及 yt-dlp 和 FFmpeg 全部搬到 exe 旁边的 &lt;code&gt;data&lt;/code&gt; 文件夹，不碰系统的 &lt;code&gt;AppData&lt;/code&gt;。整个文件夹拷进 U 盘，换台电脑插上就能用，自己的下载环境随身走。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：Windows 第一次打开弹出 SmartScreen 蓝色警告，怎么办？&lt;/strong&gt;
A：这是因为应用没有购买付费代码签名证书，开源桌面软件常见。点「更多信息」→「仍要运行」即可，只需处理一次。前提是你从官方渠道下载的安装包。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：macOS 提示应用「已损坏」打不开？&lt;/strong&gt;
A：把应用拖进「应用程序」后，打开终端执行下面两行去掉隔离属性并本地签名，之后正常从启动台打开，同样只需一次：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;xattr -cr /Applications/libreget.app
codesign --force --deep --sign - /Applications/libreget.app
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;Q：Linux 上 AppImage 报 libfuse 错误起不来？&lt;/strong&gt;
A：Debian 12+、Ubuntu 24.04+ 不再自带 FUSE 2。装一下 &lt;code&gt;sudo apt install libfuse2&lt;/code&gt;，或者用 &lt;code&gt;./libreget.AppImage --appimage-extract-and-run&lt;/code&gt; 方式运行；用 &lt;code&gt;.deb&lt;/code&gt; 包则完全没有这个问题。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：Linux 下播放器黑屏或应用直接闪退？&lt;/strong&gt;
A：界面用 WebKitGTK 渲染，音视频走 GStreamer 解码，缺插件会导致播放器一出现就崩。多数桌面发行版自带，Arch 和精简镜像需手动装齐（&lt;code&gt;.deb&lt;/code&gt;、&lt;code&gt;.rpm&lt;/code&gt; 会自动带依赖，主要是 AppImage 和手动构建会遇到）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sudo apt install gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-libav   # Debian、Ubuntu
sudo dnf install gstreamer1-plugins-good gstreamer1-plugins-bad-free gstreamer1-plugin-libav   # Fedora
sudo pacman -S gst-plugins-good gst-plugins-bad gst-libav   # Arch
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;Q：需要装 Python 或 Node 吗？平时要开终端吗？&lt;/strong&gt;
A：都不需要。下载应用、打开、粘贴链接三步完事；唯一的终端操作就是上面 macOS 那次性的两行命令。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：登录后才能看的内容下不了？&lt;/strong&gt;
A：先确认浏览器扩展已装好且显示「扩展已连接」——登录 Cookie 靠它转发；再确认你在浏览器里确实处于登录状态且能正常打开那个页面。应用只能取到你自己会话能打开的内容，带 DRM 的课时会明确跳过并报告，这是设计如此，不是故障。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：下载到一半断了、或者站点返回 429？&lt;/strong&gt;
A：直接在下载页点继续即可断点续传；429 是站点限流，应用会自动退避重试并降低该站点的并发，挂着等它自己恢复，不要手动连点重试火上浇油。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：它和裸用 yt-dlp 到底什么关系？&lt;/strong&gt;
A：yt-dlp 是它长尾站点的下载引擎，由它内置、校验并自动更新；课程、Instagram、X、Pinterest、Bilibili、Telegram、种子走原生解析。在这之上是队列续传、工具区和格式转换。你在任务详情里能看到每条任务实际跑的 yt-dlp 命令，想接管随时接管。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：从源码构建要注意什么？&lt;/strong&gt;
A：需要 Rust（工具链版本被 &lt;code&gt;rust-toolchain.toml&lt;/code&gt; 锁定，因为插件 ABI 依赖它）、Node.js 18+ 和 pnpm：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git clone https://github.com/OpenSelena/libreget.git
cd libreget
pnpm install
pnpm tauri dev
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;正式构建要用 &lt;code&gt;pnpm tauri build --config &apos;{&quot;bundle&quot;:{&quot;createUpdaterArtifacts&quot;:false}}&apos;&lt;/code&gt;，否则会因为缺少发布签名私钥在生成更新包那步停住。普通使用直接下 Releases 就好，不必自己构建。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;下载这件事的麻烦从来不在「下不动」，而在工具散、参数多、下完还要二次整理。LibreGet 把课程备份、1800 多站点的视频音频图库下载、断点续传队列、浏览器登录态、播放阅读、转录转换等 158 个小工具，连同给 AI 助手调用的 MCP 接口，全部收进一个免费开源、纯本地运行的桌面窗口里。如果你手上正攒着一堆买过的课和散落各处的下载小工具，它值得成为那个唯一的入口。&lt;/p&gt;
</content:encoded></item><item><title>Lsky Pro 兰空图床：自建图床与博客配图工作流</title><link>https://www.anexns.cloudns.org/posts/selfhost-lsky-pro/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-lsky-pro/</guid><description>用 Lsky Pro 在 VPS 上自建图床：Docker Compose 部署、本地与 S3 兼容对象存储策略、游客与用户组权限防滥用、PicGo 一键上传对接，以及给博客和论坛发帖供图的完整工作流与备份方法。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：文章里的图片，凭什么寄人篱下&lt;/h2&gt;
&lt;p&gt;写博客、发帖子都绕不开配图。最省事的做法是把图片传到第三方图床，或者干脆引用别家网站的图片链接。省事的代价是：&lt;strong&gt;你的文章寿命，被别人的服务器决定了&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;这类教训这些年一再重演：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;免费图床说关就关。运营方成本撑不住、政策变了、域名到期了，图片一夜之间全部变裂图，文章还躺在那里，配图已经没了。&lt;/li&gt;
&lt;li&gt;大厂图床搞防盗链。某社交平台的图片外链先是加 Referer 校验，后来直接 403，几年间无数博客的配图集体失效，只能一篇篇回头修。&lt;/li&gt;
&lt;li&gt;引用别人站点的图片更不可控。对方改版、删图、换域名，你的文章就跟着遭殃，而且你连通知都不会收到。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;图床这件事的本质是：图片文件不大、流量不高，完全在个人 VPS 的能力范围内，没必要把命门交出去。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;自建图床的核心价值就一句话：链接永远长在自己的域名上，文件永远躺在自己的磁盘里。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;Compose 部署 Lsky Pro → 配存储策略 → 关好权限防滥用 → PicGo 对接实现一键上传 → 串起博客与发帖的供图工作流 → 把数据备好&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;选型：为什么是 Lsky Pro&lt;/h2&gt;
&lt;p&gt;自建图床的常见选择，先拉个表对齐一下：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方案&lt;/th&gt;
&lt;th&gt;数据库&lt;/th&gt;
&lt;th&gt;存储后端&lt;/th&gt;
&lt;th&gt;权限/用户组&lt;/th&gt;
&lt;th&gt;API 上传&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Lsky Pro（兰空）&lt;/td&gt;
&lt;td&gt;MySQL / SQLite&lt;/td&gt;
&lt;td&gt;本地、S3、OSS、COS、WebDAV 等多种&lt;/td&gt;
&lt;td&gt;有，多用户组配额&lt;/td&gt;
&lt;td&gt;有，Token 鉴权&lt;/td&gt;
&lt;td&gt;个人到小团队的正经图床&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;EasyImage&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;仅本地&lt;/td&gt;
&lt;td&gt;弱&lt;/td&gt;
&lt;td&gt;有&lt;/td&gt;
&lt;td&gt;极简自用，不想维护数据库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Chevereto&lt;/td&gt;
&lt;td&gt;MySQL&lt;/td&gt;
&lt;td&gt;本地、S3 等&lt;/td&gt;
&lt;td&gt;有&lt;/td&gt;
&lt;td&gt;有&lt;/td&gt;
&lt;td&gt;英文社区老牌，中文生态弱&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;对象存储＋静态托管&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;单一云存储&lt;/td&gt;
&lt;td&gt;靠云厂商策略&lt;/td&gt;
&lt;td&gt;靠 SDK&lt;/td&gt;
&lt;td&gt;图片量大、愿意绑一家云&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Git 仓库当图床&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;仓库&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;靠 Git 操作&lt;/td&gt;
&lt;td&gt;玩票，仓库膨胀后很难受&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;Lsky Pro 是国内开源图床里维护最久的一批：PHP 开发，后台中文，多存储策略、多用户组、相册管理、水印、API Token 一应俱全，正好卡在「个人用不过剩、团队用也够」的点上。本篇以开源版 V2 为准，Docker 镜像用社区维护的 &lt;code&gt;dko0/lsky-pro&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;Docker Compose 部署&lt;/h2&gt;
&lt;p&gt;Lsky Pro 本体加一个 MySQL，是最稳妥的组合。数据量小的话安装向导里也可以选 SQLite，那就连数据库容器都省了；但既然要长期当生产图床用，建议一步到位上 MySQL，后续迁移和备份都更规整。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  lsky-pro:
    image: dko0/lsky-pro:latest
    container_name: lsky-pro
    restart: unless-stopped
    ports:
      - &quot;8080:80&quot;
    volumes:
      - ./lsky-data:/var/www/html
    environment:
      - MYSQL_HOST=lsky-db
      - MYSQL_DATABASE=lsky
      - MYSQL_USER=lsky
      - MYSQL_PASSWORD=换成你的强密码
    depends_on:
      - lsky-db

  lsky-db:
    image: mysql:8.0
    container_name: lsky-db
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=换成你的强密码
      - MYSQL_DATABASE=lsky
      - MYSQL_USER=lsky
      - MYSQL_PASSWORD=换成你的强密码
    volumes:
      - ./mysql-data:/var/lib/mysql
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动并确认两个容器都正常：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose ps
docker compose logs -f lsky-pro
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;http://你的IP:8080&lt;/code&gt; 进入安装向导：环境检查通过后选 MySQL，数据库地址填&lt;strong&gt;容器名&lt;/strong&gt; &lt;code&gt;lsky-db&lt;/code&gt;（不是 localhost，也不是宿主机 IP），库名、用户名、密码与上面 Compose 里写的保持一致，最后设置管理员账号完成安装。&lt;/p&gt;
&lt;p&gt;装完先把入口收好：图床是要对外供图的服务，域名和 HTTPS 按 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager：所有自建服务的统一入口&lt;/a&gt; 那篇的套路配上，假设最终地址是 &lt;code&gt;https://img.example.com&lt;/code&gt;。后面所有配置都以这个地址为准。&lt;/p&gt;
&lt;p&gt;:::warning
图床走反向代理时，如果上传稍大的图片报 413，多半是代理层把请求体拦了。在 NPM 的 Proxy Host 高级设置里补一行 &lt;code&gt;client_max_body_size 20m;&lt;/code&gt;（按你后台设的单图上限放大一圈），再检查 Lsky Pro 后台的单图大小限制，两边对齐才不会互相打架。
:::&lt;/p&gt;
&lt;h2&gt;存储策略：本地盘还是对象存储&lt;/h2&gt;
&lt;p&gt;Lsky Pro 的图片实体不绑死在本地，后台「存储策略」里可以建多个策略再分配给不同用户组，支持本地、AWS S3、阿里云 OSS、腾讯云 COS、七牛云、又拍云、FTP/SFTP、WebDAV、MinIO 等。怎么选，看图片的量和你的机器：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;本地存储&lt;/th&gt;
&lt;th&gt;S3 兼容对象存储&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;成本&lt;/td&gt;
&lt;td&gt;只有 VPS 磁盘&lt;/td&gt;
&lt;td&gt;按量付费，便宜但有账单&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;速度&lt;/td&gt;
&lt;td&gt;取决于 VPS 带宽&lt;/td&gt;
&lt;td&gt;云厂商带宽＋可叠 CDN&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;扩容&lt;/td&gt;
&lt;td&gt;受磁盘上限约束&lt;/td&gt;
&lt;td&gt;几乎无限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;备份负担&lt;/td&gt;
&lt;td&gt;图片文件要自己全量备&lt;/td&gt;
&lt;td&gt;实体在云端，自己只备数据库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;掌控感&lt;/td&gt;
&lt;td&gt;文件就在手边&lt;/td&gt;
&lt;td&gt;依赖云厂商账号安全&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;个人博客量级，一天几张图，本地存储完全够用，简单直接。图片开始以 GB 计、或者 VPS 带宽小得可怜时，再把新策略切到对象存储：S3 兼容接口是通用语，MinIO 自建、Cloudflare R2、以及国内各家云的兼容模式都走这一套，配置项无非是 Endpoint、Bucket、AccessKey、SecretKey 和访问域名这五件套。&lt;/p&gt;
&lt;p&gt;两个和图片质量相关的设置顺手在后台配好：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;图片压缩&lt;/strong&gt;：开启上传压缩并给个合理质量（比如 85），截图和照片能省下三到五成体积，肉眼基本看不出差别。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;水印&lt;/strong&gt;：怕图被盗用就开文字或图片水印，设好位置和透明度。注意水印是&lt;strong&gt;压在原图上不可逆的&lt;/strong&gt;，介意留原图的话就关掉，或者只给特定用户组开。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;权限与防滥用：图床最怕变成别人的免费仓库&lt;/h2&gt;
&lt;p&gt;图床一旦开放游客上传，扫描器和羊毛党几天之内就会找上门：轻则磁盘被垃圾图塞满，重则有人传违法图片，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;服务器在你名下，出了事第一个被找的是你&amp;lt;/span&amp;gt;。所以部署完的第一件事不是美化界面，而是把门关对：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;游客上传默认关掉&lt;/strong&gt;。自己用、家人朋友用，走账号体系足够了；确实要开放，先想清楚审核谁来做。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;注册设为关闭或人工审核&lt;/strong&gt;。在后台把开放注册关掉，需要账号就由管理员手动建，别让任何人自助注册进来传图。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;用用户组分层&lt;/strong&gt;。管理员组不限量，普通组给死配额：单图大小、总容量、每日上传数都设上限，单个账号被滥用时损失可控。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;黑名单用起来&lt;/strong&gt;。后台支持按 IP 和邮箱拉黑，遇到批量灌图的来源直接封段处理。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;后台路径和管理员账号独立强密码&lt;/strong&gt;，再叠加 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全加固：最小暴露与访问控制&lt;/a&gt; 里讲的访问控制，图床的「写入口」只留给该来的人。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;原则就一条：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;图床可以公开读，但写入必须只对自己人开放。&amp;lt;/span&amp;gt;读是分享，写是责任，分清楚这两件事，图床就能长期安稳跑下去。&lt;/p&gt;
&lt;h2&gt;PicGo 对接：写文章时一键上传贴图&lt;/h2&gt;
&lt;p&gt;图床装好只是仓库，真正决定日常体验的是上传姿势。手动开网页、选文件、复制链接，一篇文章十张图能把人点烦。PicGo 就是干这个的：截图或复制图片后按快捷键，自动上传并把 Markdown 链接写进剪贴板，回到编辑器粘贴即可。&lt;/p&gt;
&lt;h3&gt;第一步：给 PicGo 发一张「通行证」&lt;/h3&gt;
&lt;p&gt;Lsky Pro 的 API 用 Token 鉴权。用你自己的账号调一次令牌接口即可拿到：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -X POST &apos;https://img.example.com/api/v1/tokens&apos; \
  -H &apos;Content-Type: application/json&apos; \
  -d &apos;{&quot;email&quot;:&quot;你的邮箱&quot;,&quot;password&quot;:&quot;你的密码&quot;}&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回的 &lt;code&gt;data.token&lt;/code&gt; 形如 &lt;code&gt;1|aBcDeFg...&lt;/code&gt;，整段保存好。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;这个 Token 等于账号的上传钥匙，泄露了别人就能借你的图床传图&amp;lt;/span&amp;gt;，只放在自己设备的 PicGo 配置里，别写进任何公开仓库或截图里。&lt;/p&gt;
&lt;h3&gt;第二步：装插件并配置&lt;/h3&gt;
&lt;p&gt;PicGo 本体不带兰空支持，去插件设置里搜索并安装 &lt;code&gt;lankong&lt;/code&gt; 插件（也有 &lt;code&gt;lsky-uploader&lt;/code&gt; 等同类插件，配置项大同小异），然后在图床设置里找到它，填：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;配置项&lt;/th&gt;
&lt;th&gt;填法&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Version&lt;/td&gt;
&lt;td&gt;V2（与自建版本对应，选错会直接上传失败）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Server&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://img.example.com&lt;/code&gt;（只填到域名，不要带多余路径）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Auth token&lt;/td&gt;
&lt;td&gt;`Bearer 1&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;策略 ID&lt;/td&gt;
&lt;td&gt;留空或填 1，即默认存储策略&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;先在终端验证一下接口本身是通的，再回头查 PicGo 配置，能省很多冤枉路：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -X POST &apos;https://img.example.com/api/v1/upload&apos; \
  -H &apos;Authorization: Bearer 1|aBcDeFg...&apos; \
  -H &apos;Accept: application/json&apos; \
  -F &apos;file=@/path/to/test.png&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回 JSON 里 &lt;code&gt;data.links.url&lt;/code&gt; 是图片直链，还同时给了 &lt;code&gt;markdown&lt;/code&gt; 和 &lt;code&gt;html&lt;/code&gt; 格式，看到它们就说明服务端没问题。&lt;/p&gt;
&lt;h3&gt;第三步：接进写作工具&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;PicGo 桌面端&lt;/strong&gt;：把兰空设为默认图床，开启「时间戳重命名」避免同名覆盖，上传快捷键记住，流程就是「截图 → 快捷键 → 回文章里粘贴」。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Typora&lt;/strong&gt;：偏好设置 → 图像 → 上传服务选 PicGo.app，写文档时粘贴图片自动走 PicGo 上传，正文里直接落 Markdown 链接。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;VS Code&lt;/strong&gt;：装 Lsky 系的上传插件、填同一套 Server 和 Token，在编辑器里一键粘贴图片，适合直接在代码仓库里写文档的人。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;完整工作流：从写一篇博客到发一个帖子&lt;/h2&gt;
&lt;p&gt;工具齐了，把日常供图流程串起来，其实就四步：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;写&lt;/strong&gt;：在编辑器里写正文，需要配图时截图或拖入图片，PicGo 自动上传到自建图床，剪贴板里就是 &lt;code&gt;![](https://img.example.com/...)&lt;/code&gt; 格式的链接，粘贴进文章。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;管&lt;/strong&gt;：图片在 Lsky Pro 后台按相册归档，建议按「博客名/年月」粗分即可，找历史图时能按相册和时间过滤；重复图、废图随手删，别让仓库变垃圾场。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;发&lt;/strong&gt;：博客发布时文章带着自有域名的图片链接上线；去论坛、社区发帖同理，编辑器支持 Markdown 的直接粘贴，不支持的用图床返回的 HTML 链接或直链插入。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;稳&lt;/strong&gt;：链接域名是自己的，换博客程序、迁服务器都不影响已发出的图片地址——迁移时只要图床数据跟着走（见下一节），全网旧文的配图一张不裂。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;和 &lt;a href=&quot;/posts/selfhost-cloudreve/&quot;&gt;Cloudreve：私人云盘部署与存储策略&lt;/a&gt; 的分工也说一句：Cloudreve 管的是「文件本身」的存取分享，图床管的是「给文章供图」这一个专门场景，两者别混用——拿网盘分享链接当图床直链用，防盗链和过期策略迟早给你颜色看。&lt;/p&gt;
&lt;h2&gt;备份：数据库和图片文件，缺一个都不算备份&lt;/h2&gt;
&lt;p&gt;图床的数据分两半：一半是 MySQL 里的账号、相册、图片记录和存储策略配置，另一半是图片实体文件（本地策略下在数据目录里，对象存储策略下在云端）。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;只备份数据库，恢复出来的是满屏裂图；只备份图片文件，恢复出来的是对不上号的散图&amp;lt;/span&amp;gt;，两半必须成套走。&lt;/p&gt;
&lt;p&gt;本地存储策略下，一次完整的备份就是打包数据目录加导出数据库：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 导出数据库
docker exec lsky-db mysqldump -u root -p你的密码 lsky &amp;gt; lsky-$(date +%F).sql

# 打包图床数据目录（配置与本地图片都在里面）
tar -czf lsky-data-$(date +%F).tar.gz ./lsky-data ./mysql-data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;对象存储策略下，图片实体在云端、由云厂商负责冗余，你要备的收窄为数据库导出加图床的配置文件，但云端 Bucket 的版本控制或跨区复制建议打开，别把鸡蛋全放在一个桶里。&lt;/p&gt;
&lt;p&gt;备份的节奏、异地副本和恢复演练，按 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移实战&lt;/a&gt; 里的统一框架执行即可，图床无非是多一个「恢复后随机抽查十张老图能不能打开」的验收动作。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;PicGo 上传报 401 或「You must be logged in」。&lt;/strong&gt;
Token 过期、被撤销，或者插件里没带 &lt;code&gt;Bearer &lt;/code&gt; 前缀，再或者 Version 选成了 V1。先用上面的 curl 直调 &lt;code&gt;/api/v1/upload&lt;/code&gt; 验证 Token 本身，接口通了再逐项对插件配置。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;网页端上传大图报 413。&lt;/strong&gt;
代理层请求体上限太小。按前文把 NPM 的 &lt;code&gt;client_max_body_size&lt;/code&gt; 放大，同时确认 Lsky Pro 后台单图上限和用户组配额没有卡得更小，三处取最小值生效。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;安装向导里数据库怎么都连不上。&lt;/strong&gt;
地址填了 localhost 或宿主机 IP。在容器网络里，数据库要按容器名 &lt;code&gt;lsky-db&lt;/code&gt; 访问；再核对库名、用户名、密码与 Compose 环境变量逐字一致。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;图片上传成功，但文章里打开是裂图或被浏览器拦截。&lt;/strong&gt;
多半是地址不一致：站点实际走 HTTPS，但存储策略里配的访问域名还是 HTTP 或内网地址，触发混合内容拦截。把后台站点地址与存储策略的访问域名统一成最终的 HTTPS 域名，再清一次缓存看。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;换了存储策略后，老图还在旧策略里找不到。&lt;/strong&gt;
策略是按图片逐张绑定的，新策略只对新上传生效，老图不会自动迁移。要搬家先在后台确认每张图的归属，别删旧策略的存储端，先迁移校验再收尾。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;第三方图床的风险不在今天传不上去，而在三年后打不开；自建图床把域名和文件都收回自己手里。&lt;/li&gt;
&lt;li&gt;Lsky Pro 用 Compose 加 MySQL 部署，多存储策略让本地盘和对象存储可以按量切换，压缩与水印在后台一次配好。&lt;/li&gt;
&lt;li&gt;安全顺序不能反：先关游客上传、收紧注册、用用户组配额兜底，再谈开放给别人用。&lt;/li&gt;
&lt;li&gt;PicGo 加 Token 是体验的分水岭：配好之后，供图就是「截图、快捷键、粘贴」三下，博客和发帖共用一条流水线。&lt;/li&gt;
&lt;li&gt;备份永远成套：数据库导出加图片文件打包，缺任何一半都恢复不出完整的图床。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>自建服务实战：Mailcow 搭建企业级邮件服务器</title><link>https://www.anexns.cloudns.org/posts/selfhost-mailcow/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-mailcow/</guid><description>用 mailcow-dockerized 在 VPS 上自建全套邮件服务器：从 IP 信誉、PTR 反向解析与 25 端口解封，到 MX/SPF/DKIM/DMARC 全套 DNS 记录、部署、SOGo 邮箱、Rspamd 反垃圾、备份与投递排障的完整实战。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说主线：自建服务里，邮件是公认的毕业题&lt;/h2&gt;
&lt;p&gt;自建服务玩到一定阶段，总会有人动念头：能不能把邮箱也搬回自己手里？注册域名时送的企业邮箱、免费邮箱的各种限制、重要邮件躺在别人服务器上的不踏实，都是真实的驱动力。&lt;/p&gt;
&lt;p&gt;但必须先把话说在前面：&lt;strong&gt;邮件是所有自建服务里最难的一类，没有之一。&lt;/strong&gt; 难的不是把软件装起来——Mailcow 一套 Docker Compose 拉起来只要十分钟；难的是装起来之后，你的邮件能不能进对方的收件箱，而不是垃圾箱，更不是被对方服务器直接拒收。&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;先讲清自建邮件为什么难 → 把 IP、PTR、25 端口这些前置条件逐个落实 → 配齐全套 DNS 记录 → 部署 mailcow-dockerized → 建域建邮箱、配好 Webmail 与反垃圾 → 最后是备份与投递排障&lt;/strong&gt;。顺序不能乱，前置条件没落实就装软件，装得再顺也是白装。&lt;/p&gt;
&lt;h2&gt;为什么自建邮件难：你对抗的是整套信誉体系&lt;/h2&gt;
&lt;p&gt;现代邮件系统防垃圾邮件靠的不是某一项技术，而是一整套互相咬合的信誉体系。新自建的邮局在这套体系面前，天然是「无信用记录的新人」：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;IP 信誉&lt;/strong&gt;。各大接收方（Gmail、Outlook、QQ 邮箱等）都维护着发信 IP 的信誉档案。一个从没发过信的新 IP，初始待遇就是被怀疑；&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;IP 一旦因为历史问题或误伤进了黑名单，或者被前任使用者发垃圾邮件搞臭了，发出的邮件会大面积进垃圾箱甚至被直接拒收&amp;lt;/span&amp;gt;，而且申诉移除往往要数天到数周。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;域名信誉&lt;/strong&gt;。新注册的域名、刚开始发信的域名，同样没有历史积累，需要靠持续、稳定、被正常接收和阅读的发信行为慢慢「养」出信誉。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;身份验证三件套&lt;/strong&gt;。SPF、DKIM、DMARC 是发信域名的身份证：SPF 声明哪些 IP 有权用你的域名发信，DKIM 给邮件加数字签名，DMARC 告诉接收方验证失败时该怎么处理。三者缺一，投递率立刻打折。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;反向解析&lt;/strong&gt;。发信 IP 的 PTR 记录必须能解析回你的邮件服务器主机名，且与 SMTP 握手时的 HELO/EHLO 主机名一致，这是很多大厂的硬性门槛。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;结论先放这里：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;自建邮件的成败，八成取决于开工前的 IP 质量与 DNS 配置，装软件本身反而是最简单的一步。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;前置条件：四件事缺一不可&lt;/h2&gt;
&lt;h3&gt;1. 一个你完全控制的域名&lt;/h3&gt;
&lt;p&gt;域名注册商处要能自由修改全部 DNS 记录。本篇示例使用域名 &lt;code&gt;example.com&lt;/code&gt;，邮件服务器主机名定为 &lt;code&gt;mail.example.com&lt;/code&gt;。DNS 如果托管在 Cloudflare，记录的增删改查可以先参考 &lt;a href=&quot;/posts/cloudflare-dns-records/&quot;&gt;Cloudflare DNS 记录管理&lt;/a&gt; 那篇把操作界面摸熟，本篇的记录表直接照着填即可。&lt;/p&gt;
&lt;h3&gt;2. 一台带干净独立 IP 的 VPS&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;必须是&lt;strong&gt;独立公网 IPv4&lt;/strong&gt;，不能是 NAT 共享出口、不能是家宽动态 IP。家宽 IP 段在各大黑名单数据库里基本是整段标记的，自建邮件无从谈起。&lt;/li&gt;
&lt;li&gt;内存建议 4 GB 起步。Mailcow 全套组件（Postfix、Dovecot、Rspamd、SOGo、MySQL、Redis、ClamAV 等）常驻内存不低，2 GB 机器关掉 ClamAV 也能跑，但余量太小。&lt;/li&gt;
&lt;li&gt;拿到 IP 后先自查一遍黑名单，别等装完才发现 IP 是臭的：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;# 把 203.0.113.10 换成你的服务器 IP，反序拼进黑名单查询域名
dig +short 10.113.0.203.zen.spamhaus.org
dig +short 10.113.0.203.b.barracudacentral.org
dig +short 10.113.0.203.bl.spamcop.net
# 有返回 127.0.0.x 就是在名单里；无返回（空）才是干净
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;也可以直接用 MXToolbox 的 Blacklist Check 页面把主流名单一次查完。查出在名单里，先去对应名单官网走移除流程，或者直接找云厂商换 IP，别带着脏 IP 开工。&lt;/p&gt;
&lt;h3&gt;3. PTR 反向解析&lt;/h3&gt;
&lt;p&gt;在云厂商控制台（注意：不在域名 DNS 里）给服务器 IP 设置反向解析，指向邮件主机名：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;203.0.113.10  →  mail.example.com
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;设置后验证：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;dig +short -x 203.0.113.10
# 期望输出：mail.example.com.
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意，PTR 记录不归域名 DNS 管，而归 IP 的持有方（云厂商）管，找不到设置入口就提工单让厂商代设，这是自建邮件最容易卡住的第一关。&lt;/p&gt;
&lt;h3&gt;4. 25 端口出站解封&lt;/h3&gt;
&lt;p&gt;绝大多数云厂商默认封禁服务器的 &lt;strong&gt;25 端口出站&lt;/strong&gt;（防垃圾邮件滥用），入站一般不封。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;25 端口出站不通，你的服务器连不上任何外部邮局，邮件根本发不出去&amp;lt;/span&amp;gt;，且在服务器内部测试一切正常，极具迷惑性。开工前先实测：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 从服务器上连一个外部邮局的 25 端口（用 Gmail 的 MX 做靶子）
nc -vz gmail-smtp-in.l.google.com 25
# 或者
curl -v telnet://gmail-smtp-in.l.google.com:25
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;不通就去云厂商控制台找「端口解封 / 安全组出站规则」，或提工单申请解封 25 端口出站，部分厂商要求账户注册满一定时长或提交用途说明。工单没批下来之前，后面的步骤都不要做。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;strong&gt;开工前的劝退清单&lt;/strong&gt;：IP 在黑名单里且移除无望、厂商拒绝解封 25 端口出站、只有 NAT 共享 IP、打算用家宽——这四种情况任意命中一条，就不要自建邮件了，改用域名邮箱服务或第三方企业邮局。自建邮件的门槛不在技术，在资源条件，条件不满足时硬上，只会得到一个只能收信、发信全进垃圾箱的半成品。
:::&lt;/p&gt;
&lt;h2&gt;DNS 记录全套：一张表配齐&lt;/h2&gt;
&lt;p&gt;前置条件落实后，把下面这套记录一次性配齐（示例：域名 &lt;code&gt;example.com&lt;/code&gt;，服务器 IP &lt;code&gt;203.0.113.10&lt;/code&gt;，主机名 &lt;code&gt;mail.example.com&lt;/code&gt;）。DKIM 公钥和 DMARC 里的具体值在 Mailcow 装好后生成，这里先把框架占好位：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;主机记录&lt;/th&gt;
&lt;th&gt;记录值&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;A&lt;/td&gt;
&lt;td&gt;mail&lt;/td&gt;
&lt;td&gt;203.0.113.10&lt;/td&gt;
&lt;td&gt;邮件服务器主机名解析，必须灰云/直连，不能套 CDN&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MX&lt;/td&gt;
&lt;td&gt;@&lt;/td&gt;
&lt;td&gt;mail.example.com（优先级 10）&lt;/td&gt;
&lt;td&gt;声明由哪台服务器收信&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TXT&lt;/td&gt;
&lt;td&gt;@&lt;/td&gt;
&lt;td&gt;&lt;code&gt;v=spf1 mx a -all&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;SPF：只允许本域 MX/A 记录的 IP 发信，其余一律拒绝&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TXT&lt;/td&gt;
&lt;td&gt;dkim._domainkey&lt;/td&gt;
&lt;td&gt;&lt;code&gt;v=DKIM1; k=rsa; p=（Mailcow 生成的公钥）&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;DKIM 公钥，部署后在后台复制&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TXT&lt;/td&gt;
&lt;td&gt;_dmarc&lt;/td&gt;
&lt;td&gt;&lt;code&gt;v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com; pct=100&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;DMARC 策略：验证失败进隔离区，报告发到指定邮箱&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TXT&lt;/td&gt;
&lt;td&gt;_mta-sts&lt;/td&gt;
&lt;td&gt;&lt;code&gt;v=STSv1; id=2025111501&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;MTA-STS 版本声明，id 每次改策略时更新&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A&lt;/td&gt;
&lt;td&gt;mta-sts&lt;/td&gt;
&lt;td&gt;203.0.113.10&lt;/td&gt;
&lt;td&gt;MTA-STS 策略文件站点（或指向任意 HTTPS 静态托管）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;CNAME&lt;/td&gt;
&lt;td&gt;autoconfig&lt;/td&gt;
&lt;td&gt;mail.example.com&lt;/td&gt;
&lt;td&gt;客户端自动发现（可选，建议配）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;CNAME&lt;/td&gt;
&lt;td&gt;autodiscover&lt;/td&gt;
&lt;td&gt;mail.example.com&lt;/td&gt;
&lt;td&gt;同上，覆盖另一套自动发现协议&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;几个要点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;MTA-STS 策略文件&lt;/strong&gt;还要在 &lt;code&gt;https://mta-sts.example.com/.well-known/mta-sts.txt&lt;/code&gt; 放一份文本，内容如下，它要求对方邮局必须用 TLS 加密投递到你的 MX，防降级攻击：&lt;/li&gt;
&lt;/ul&gt;
&lt;pre&gt;&lt;code&gt;version: STSv1
mode: enforce
mx: mail.example.com
max_age: 604800
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;DMARC 策略分三档&lt;/strong&gt;：&lt;code&gt;p=none&lt;/code&gt; 只监控不处置、&lt;code&gt;p=quarantine&lt;/code&gt; 失败进垃圾箱、&lt;code&gt;p=reject&lt;/code&gt; 失败直接拒收。新站先用 &lt;code&gt;quarantine&lt;/code&gt; 起步，发信稳定一两周、确认 SPF/DKIM 对齐没问题后，再升到 &lt;code&gt;reject&lt;/code&gt;，这是最稳妥的节奏。一上来就 &lt;code&gt;reject&lt;/code&gt;，配置有任何小错都会让自己人发的信被全网拒收。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A 记录不能开 CDN 代理&lt;/strong&gt;。邮件流量不是 HTTP，套了 CDN 的橙云代理会直接让收发信全灭，这和网站加速是两回事。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;部署 mailcow-dockerized&lt;/h2&gt;
&lt;p&gt;Mailcow 的官方发行形式就是一套 Docker Compose 项目（mailcow-dockerized），把 Postfix、Dovecot、Rspamd、SOGo、数据库等组件全部容器化，统一由一个管理后台操作。本机其他服务如果也用 Compose 管理，整体风格是一致的。&lt;/p&gt;
&lt;h3&gt;拉代码并生成配置&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 前置：已装好 Docker 与 Docker Compose（见 Docker 专题）
cd /opt
git clone https://github.com/mailcow/mailcow-dockerized
cd mailcow-dockerized

# 生成配置文件（交互式：会问主机名和时区）
./generate_config.sh
# Mail server hostname (FQDN): 填 mail.example.com
# Timezone: 填 Asia/Shanghai
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;检查 mailcow.conf 关键项&lt;/h3&gt;
&lt;p&gt;生成的 &lt;code&gt;mailcow.conf&lt;/code&gt; 里，重点核对这几项：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 邮件服务器主机名，必须与 PTR、MX、A 记录完全一致
MAILCOW_HOSTNAME=mail.example.com

# 时区，与 generate 时填的一致
TZ=Asia/Shanghai

# 资源紧张时可关掉杀毒，省下约 1 GB 内存（可选）
# SKIP_CLAMD=n 改为 y 即关闭 ClamAV
SKIP_CLAMD=n

# 管理后台与 Webmail 的 HTTP 端口（默认 80/443 被 Mailcow 自带 Nginx 占用）
HTTP_PORT=80
HTTPS_PORT=443
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果这台机器上 80/443 已经被别的服务占用，需要在这里改成其他端口（比如 8080/8443）再单独处理转发，或者干脆给邮件单独一台机器——邮件服务器独占一台 VPS 是更推荐的做法，故障域隔离，IP 也是专用的。&lt;/p&gt;
&lt;h3&gt;启动&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;docker compose pull
docker compose up -d

# 看全套容器状态，十几个容器全部 Up 才算起来
docker compose ps

# 实时看日志（排障时最常用）
docker compose logs -f postfix-mailcow
docker compose logs -f dovecot-mailcow
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;strong&gt;端口与反代的铁律&lt;/strong&gt;：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;邮件相关端口（25、465、587、993、995、143、110）是 SMTP/IMAP/POP3 原始 TCP 流量，不能走 Nginx Proxy Manager 的普通 HTTP 反向代理&amp;lt;/span&amp;gt;，反代过去协议直接不通。这些端口必须在防火墙和云安全组里直接放行到服务器。NPM 在这套体系里最多只能反代管理后台和 Webmail 的 HTTPS 页面（而且 Mailcow 自带 Nginx 已经处理了证书与页面，通常没必要再套一层），其定位参考 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;自建服务统一入口：Nginx Proxy Manager&lt;/a&gt; 那篇。拿 NPM 反代 25 端口是新手最常见的翻车点，没有之一。
:::&lt;/p&gt;
&lt;p&gt;邮件服务需要放行的端口一览：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;端口&lt;/th&gt;
&lt;th&gt;协议&lt;/th&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;th&gt;是否必需&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;25&lt;/td&gt;
&lt;td&gt;SMTP&lt;/td&gt;
&lt;td&gt;服务器之间收发信（核心端口）&lt;/td&gt;
&lt;td&gt;必需&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;465&lt;/td&gt;
&lt;td&gt;SMTPS&lt;/td&gt;
&lt;td&gt;客户端加密提交发信&lt;/td&gt;
&lt;td&gt;必需&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;587&lt;/td&gt;
&lt;td&gt;Submission&lt;/td&gt;
&lt;td&gt;客户端提交发信（STARTTLS）&lt;/td&gt;
&lt;td&gt;必需&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;993&lt;/td&gt;
&lt;td&gt;IMAPS&lt;/td&gt;
&lt;td&gt;客户端加密收信&lt;/td&gt;
&lt;td&gt;必需&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;995&lt;/td&gt;
&lt;td&gt;POP3S&lt;/td&gt;
&lt;td&gt;POP3 加密收信&lt;/td&gt;
&lt;td&gt;用 POP3 才开&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;143 / 110&lt;/td&gt;
&lt;td&gt;IMAP / POP3 明文&lt;/td&gt;
&lt;td&gt;老协议明文收信&lt;/td&gt;
&lt;td&gt;不建议开&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;80 / 443&lt;/td&gt;
&lt;td&gt;HTTP/HTTPS&lt;/td&gt;
&lt;td&gt;管理后台、Webmail、证书签发&lt;/td&gt;
&lt;td&gt;必需&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4190&lt;/td&gt;
&lt;td&gt;Sieve&lt;/td&gt;
&lt;td&gt;客户端管理过滤规则&lt;/td&gt;
&lt;td&gt;可选&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;Let&apos;s Encrypt 证书&lt;/h2&gt;
&lt;p&gt;Mailcow 自带 ACME 客户端，配置无误时会自动为 &lt;code&gt;mail.example.com&lt;/code&gt; 以及后台里添加的域名签发并续期 Let&apos;s Encrypt 证书，不需要额外部署 Certbot。第一次启动后等几分钟，检查证书状态：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 看 ACME 容器的签发日志
docker compose logs acme-mailcow | tail -30

# 验证 443 端口实际递出的证书域名与有效期
echo | openssl s_client -connect mail.example.com:443 -servername mail.example.com 2&amp;gt;/dev/null | openssl x509 -noout -subject -dates
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;签发失败九成是这两个原因：一是 80 端口没通到服务器（HTTP-01 验证过不来），二是 &lt;code&gt;mail.example.com&lt;/code&gt; 的 A 记录还没生效或指错了 IP。先 &lt;code&gt;dig +short mail.example.com&lt;/code&gt; 确认解析，再看 ACME 日志里的具体报错。&lt;/p&gt;
&lt;p&gt;证书就绪后，IMAP/SMTP 的加密端口递出的也是同一张证书，客户端里把服务器地址填 &lt;code&gt;mail.example.com&lt;/code&gt; 就不会有证书警告。&lt;/p&gt;
&lt;h2&gt;管理后台：建域、建邮箱、别名&lt;/h2&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;https://mail.example.com&lt;/code&gt;，用默认管理员账号 &lt;code&gt;admin&lt;/code&gt; / &lt;code&gt;moohoo&lt;/code&gt; 登录，&lt;strong&gt;登录后第一件事就是改管理员密码&lt;/strong&gt;，并在后台开启管理员的双因素认证。自建服务对外的统一安全基线（强密码、双因素、最小暴露面）可以对照 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全与访问控制&lt;/a&gt; 那篇逐项落实，邮件后台一旦被攻破，等于整个域名的发信权被攻破，后果比单个网站被黑严重得多。&lt;/p&gt;
&lt;h3&gt;建域&lt;/h3&gt;
&lt;p&gt;后台 → Configuration → Mail Setup → Domains → Add Domain，填 &lt;code&gt;example.com&lt;/code&gt;。建域时把容量上限、默认邮箱配额按实际需求给（个人使用单邮箱 10–20 GB 足够）。&lt;/p&gt;
&lt;p&gt;建完域后，在该域名的详情里点 &lt;strong&gt;DKIM&lt;/strong&gt; 生成密钥（长度选 2048），把生成的公钥记录复制出来，回头填进 DNS 的 &lt;code&gt;dkim._domainkey&lt;/code&gt; 那条 TXT 记录——前面 DNS 表里留的占位就是等这一步。&lt;/p&gt;
&lt;h3&gt;建邮箱与别名&lt;/h3&gt;
&lt;p&gt;Mailboxes → Add Mailbox，建几个实际邮箱，例如：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;admin@example.com&lt;/code&gt;：日常主邮箱&lt;/li&gt;
&lt;li&gt;&lt;code&gt;dmarc@example.com&lt;/code&gt;：专门收 DMARC 报告（DNS 里 rua 指向它）&lt;/li&gt;
&lt;li&gt;&lt;code&gt;postmaster@example.com&lt;/code&gt;、&lt;code&gt;abuse@example.com&lt;/code&gt;：邮局的规范保留地址，建议建上或用别名指到主邮箱&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;别名（Alias）&lt;/strong&gt; 是省邮箱数量的利器：&lt;code&gt;contact@&lt;/code&gt;、&lt;code&gt;support@&lt;/code&gt;、&lt;code&gt;noreply@&lt;/code&gt; 这类对外地址都建为别名，统一转发到主邮箱即可，不必每个都开真实邮箱。Catch-all（&lt;code&gt;@example.com&lt;/code&gt; 全域捕获）不要开，它会把发往任意不存在地址的垃圾邮件全收进来，是背压垃圾的重灾区。&lt;/p&gt;
&lt;p&gt;每个邮箱建好后，在邮箱设置里顺手打开该用户的双因素认证，并给一个强密码。Webmail 和客户端登录用的都是这套账号密码（或在后台生成的应用专用密码）。&lt;/p&gt;
&lt;h2&gt;Webmail：SOGo 的日常使用&lt;/h2&gt;
&lt;p&gt;Mailcow 的 Webmail 是 SOGo，地址就是 &lt;code&gt;https://mail.example.com&lt;/code&gt; 登录后跳转，或直达 SOGo 路径。用邮箱账号登录后，邮件、日历、通讯录都在里面，界面是完整的桌面端体验，手机浏览器上也能用。&lt;/p&gt;
&lt;p&gt;几个值得一提的点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;过滤规则&lt;/strong&gt;：SOGo 里可以建服务器端过滤规则（Sieve），比如 DMARC 报告自动归档到某个文件夹、特定发件人自动打标签，规则在服务器端执行，换客户端不丢失。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;客户端接入&lt;/strong&gt;：桌面和手机客户端（Thunderbird、Outlook、手机自带邮件）填服务器 &lt;code&gt;mail.example.com&lt;/code&gt;，IMAP 993、SMTP 587（或 465），配合前面配好的 autoconfig 记录，大多数客户端输完邮箱地址就能自动带出服务器配置。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;发信自测&lt;/strong&gt;：新邮箱建好后，第一封测试信发给自己的 Gmail/QQ 邮箱，再让对方回一封，确认收发双向都通，然后立刻去做后面的投递质量检查。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;Rspamd 反垃圾要点&lt;/h2&gt;
&lt;p&gt;Mailcow 的反垃圾引擎是 Rspamd，它同时负责收信打分拦截和发信时的 DKIM 签名。管理入口在后台的 Rspamd UI（从管理后台跳转，需要单独设置访问密码）。&lt;/p&gt;
&lt;p&gt;日常只需要抓住三个要点：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;看懂分数&lt;/strong&gt;。Rspamd 给每封入站邮件打分：负分是好信，正分越高越像垃圾，超过阈值（默认约 15 分）拒收，中间档进垃圾箱。排障时在 Rspamd 历史里按这封信查命中了哪些规则，比盲猜高效得多。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;黑白名单在后台维护&lt;/strong&gt;。Mail Setup 里的 Blacklist/Whitelist 是给自己域用的：误杀的正常发件人加白名单，狂发垃圾的域加黑名单。不要动不动去改全局评分阈值，默认阈值是社区多年调出来的，乱降会放进来大量垃圾，乱升会误杀正常邮件。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;DKIM 签名归它管&lt;/strong&gt;。前面在域设置里生成的 DKIM 密钥，实际签名动作由 Rspamd 执行；DNS 公钥没填对时，签名验证必然失败——发信后务必用后面排障小节的方法验一次。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;另外，ClamAV 病毒扫描如果关了（&lt;code&gt;SKIP_CLAMD=y&lt;/code&gt;），附件病毒这道防线就没有了，内存实在不够才关，够用就开着。&lt;/p&gt;
&lt;h2&gt;备份策略&lt;/h2&gt;
&lt;p&gt;邮箱数据的特点是&lt;strong&gt;只增不减、丢了不可再生&lt;/strong&gt;——别人不会给你重发三年前的邮件。Mailcow 的全部状态都在 Docker 卷里：邮件本体（vmail 卷）、数据库（mysql 卷）、配置与 DKIM 密钥（项目目录本身）。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;备份 Mailcow 的核心就一句：停机或快照状态下打包全部 Docker 卷，再加一份项目目录，恢复时整套还原。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/mailcow-dockerized

# 官方推荐的冷备方式：停服后打包卷（停机窗口选在深夜，约几分钟）
docker compose down
tar czf /backup/mailcow-volumes-$(date +%F).tar.gz -C /var/lib/docker/volumes mailcowdockerized_vmail-vol-1 mailcowdockerized_mysql-vol-1 mailcowdockerized_redis-vol-1 mailcowdockerized_rspamd-vol-1
tar czf /backup/mailcow-dir-$(date +%F).tar.gz -C /opt mailcow-dockerized
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;卷名以 &lt;code&gt;docker volume ls&lt;/code&gt; 的实际输出为准。备份文件必须&lt;strong&gt;异地存一份&lt;/strong&gt;（对象存储或另一台机器），只备在本机等于没备。整体的备份与迁移思路、异地保留策略，和 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移&lt;/a&gt; 那篇是同一套方法论，邮件只是其中最不能丢的一个实例。恢复演练至少做一次：把备份还原到临时机器、能登录能看到历史邮件，才算备份成立。&lt;/p&gt;
&lt;p&gt;升级 Mailcow 走官方脚本即可，升级前先做一次上面的完整备份：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/mailcow-dockerized
./update.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;h3&gt;1. 发出的信进对方垃圾箱&lt;/h3&gt;
&lt;p&gt;按这个顺序逐项排查，不要跳步：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 第一步：给 mail-tester.com 发一封测试信，按它的报告逐项扣分修复（最快定位）
# 第二步：自查三件套是否都通过 —— 给自己的 Gmail 发信，在 Gmail 里打开「显示原始邮件」
#   看 Authentication-Results 里 SPF / DKIM / DMARC 是否全 pass
# 第三步：查 PTR 与 HELO 是否一致
dig +short -x 203.0.113.10
# 第四步：查 IP 是否新进黑名单（发信量突增、被举报都会触发）
dig +short 10.113.0.203.zen.spamhaus.org
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;常见根因：DKIM 公钥记录填错或未生效、SPF 里漏了实际发信 IP、域名太新且首日就大量发信（新域要&lt;strong&gt;慢热&lt;/strong&gt;：头一两周每天少量、发给真实联系人并让对方回复和移出垃圾箱，是养信誉最有效的方式）。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;千万不要拿新自建的邮局直接群发通知或营销邮件&amp;lt;/span&amp;gt;，一波举报和退订就能把域名信誉打回原形。&lt;/p&gt;
&lt;h3&gt;2. 收不到外部邮件&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# MX 记录是否正确生效
dig +short MX example.com
# 25 端口入站是否通（在另一台机器上测）
nc -vz mail.example.com 25
# Postfix 日志里有没有对方投递的记录
docker compose logs postfix-mailcow | grep -i &quot;from=&amp;lt;&quot; | tail
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;MX 没生效等 DNS 缓存；25 入站不通查云安全组和本机防火墙；日志里完全没有投递记录，问题在对方或 DNS 层，有连接但被拒就看日志里的拒收原因码。&lt;/p&gt;
&lt;h3&gt;3. 客户端连不上（IMAP/SMTP 超时）&lt;/h3&gt;
&lt;p&gt;先在客户端所在网络测端口连通性：&lt;code&gt;nc -vz mail.example.com 993&lt;/code&gt;、&lt;code&gt;nc -vz mail.example.com 587&lt;/code&gt;。不通多半是安全组漏放行；通但登录失败，查 Dovecot 日志看是不是密码错触发了防爆破封禁（Mailcow 的 fail2ban 会封反复试错的 IP，&lt;code&gt;docker compose logs netfilter-mailcow&lt;/code&gt; 可查，管理后台可解封）。&lt;/p&gt;
&lt;h3&gt;4. 证书续期失败&lt;/h3&gt;
&lt;p&gt;看 &lt;code&gt;docker compose logs acme-mailcow&lt;/code&gt;，确认 80 端口从公网可达、A 记录没被改动。套了 CDN 的域名要特别注意：&lt;code&gt;mail&lt;/code&gt; 这条记录必须是直连（灰云），否则 ACME 验证和全部邮件端口一起出问题。&lt;/p&gt;
&lt;h3&gt;5. 磁盘被邮件和日志吃满&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;# 哪个卷在膨胀
docker system df -v
du -sh /var/lib/docker/volumes/mailcowdockerized_vmail-vol-1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;先给老邮箱设配额和自动清理策略（后台可按天数清理垃圾箱/已删邮件），日志侧给 Docker 配日志轮转，避免 json 日志无上限增长。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Mailcow 本身十分钟就能装好，但一套真正能用的自建邮件系统，功夫全在装之前和装之后：装之前落实干净 IP、PTR、25 端口出站和整套 DNS；装之后把 DKIM 对齐、DMARC 分阶段收紧、备份异地化，再用慢热的方式把域名和 IP 信誉养起来。做到这些，自建邮局完全可以稳定承担个人与小团队的日常邮件；做不到前置条件那一关，及时止损改用现成企业邮局，同样是正确的工程判断。&lt;/p&gt;
&lt;p&gt;至此自建服务实战系列的第 20 篇收尾：从入口、监控、文件、影音、工具到压轴的邮件，整条自建链路已经闭环，后续再补新服务，会继续挂在这个专题下。&lt;/p&gt;
</content:encoded></item><item><title>自建服务实战：Matrix（Synapse）搭建去中心化聊天服务器</title><link>https://www.anexns.cloudns.org/posts/selfhost-matrix-synapse/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-matrix-synapse/</guid><description>用 Docker Compose 部署 Synapse＋PostgreSQL 搭建 Matrix 聊天服务器：讲透不可更改的服务器名与 .well-known 委派、反向代理配置、管理员创建、Element Web 客户端接入、联邦互通测试与媒体保留策略。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先分清：Matrix 不是又一个聊天软件，而是一套联邦协议&lt;/h2&gt;
&lt;p&gt;自建聊天这件事，前面已经写过 &lt;a href=&quot;/posts/selfhost-rocketchat/&quot;&gt;Rocket.Chat 篇&lt;/a&gt;：一台服务器、一个团队、装好就能用，数据全在自己手里。但 Rocket.Chat 有个天然边界——它是一座孤岛。你服务器上的用户，只能和同一台服务器上的人聊天，想联系另一台 Rocket.Chat 上的人，做不到。&lt;/p&gt;
&lt;p&gt;Matrix 走的是完全不同的路线。它不是某个软件，而是一套&lt;strong&gt;开放的去中心化通信协议&lt;/strong&gt;，思路和电子邮件一模一样：Gmail 的用户能给 Outlook 的用户发邮件，不需要他们在同一家服务商注册。Matrix 里也一样：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;你的用户 ID 长这样：&lt;code&gt;@anex:example.com&lt;/code&gt;，后半段就是你的服务器域名，天然自带「户口所在地」。&lt;/li&gt;
&lt;li&gt;房间是分布式的：一个房间的数据会同步到所有参与者所在的服务器上，任何一台服务器下线，房间在其他服务器上照常存在。&lt;/li&gt;
&lt;li&gt;任何人按协议实现自己的服务器，都能和全世界其他 Matrix 服务器互通，这个互通网络就叫&lt;strong&gt;联邦（Federation）&lt;/strong&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Synapse 是 Matrix 官方团队用 Python 写的参考服务器实现，生态最成熟、文档最全，本篇就用它。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;Rocket.Chat&lt;/th&gt;
&lt;th&gt;Matrix（Synapse）&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;定位&lt;/td&gt;
&lt;td&gt;团队内部聊天（单机）&lt;/td&gt;
&lt;td&gt;联邦化通信网络的一个节点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;用户 ID&lt;/td&gt;
&lt;td&gt;本服务器内唯一&lt;/td&gt;
&lt;td&gt;&lt;code&gt;@用户:域名&lt;/code&gt;，全网唯一&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;跨服务器互通&lt;/td&gt;
&lt;td&gt;不支持&lt;/td&gt;
&lt;td&gt;协议原生支持（联邦）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;客户端&lt;/td&gt;
&lt;td&gt;官方 App&lt;/td&gt;
&lt;td&gt;Element、FluffyChat 等多款可选&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据模型&lt;/td&gt;
&lt;td&gt;全在本机数据库&lt;/td&gt;
&lt;td&gt;房间状态在参与服务器间复制&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;部署复杂度&lt;/td&gt;
&lt;td&gt;低&lt;/td&gt;
&lt;td&gt;中高，域名与联邦配置是门槛&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;适合场景&lt;/td&gt;
&lt;td&gt;公司/小团队内部沟通&lt;/td&gt;
&lt;td&gt;想拥有全网可达的聊天身份、长期主义&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;一句话结论：Rocket.Chat 是「自建一个聊天室」，Matrix 是「自建一个聊天世界的入口」——你的域名就是你在整个网络里的身份证。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;先把域名设计讲透 → Compose 部署 Synapse＋PostgreSQL → 配好反向代理与 .well-known 委派 → 建管理员账号 → 部署 Element Web 客户端 → 联邦互通测试 → 媒体保留与备份&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;动手前的大坑：域名设计，定下就不能改&lt;/h2&gt;
&lt;p&gt;Matrix 部署里 90% 的翻车都不是装不上，而是域名没想清楚。核心就一条：&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;server_name（服务器名）在生成配置的那一刻就被写死进数据库和签名密钥里，部署之后永远不能更改。&amp;lt;/span&amp;gt;想改名只能推倒重建，所有用户 ID、房间别名全部作废。所以动手前先把下面三件事定死：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第一，服务器名用哪个域名。&lt;/strong&gt; 假设你的主域名是 &lt;code&gt;example.com&lt;/code&gt;，你希望用户 ID 是 &lt;code&gt;@anex:example.com&lt;/code&gt; 这种短域名，那 server_name 就填 &lt;code&gt;example.com&lt;/code&gt;。Synapse 本身可以装在子域名 &lt;code&gt;matrix.example.com&lt;/code&gt; 上，通过 &lt;code&gt;.well-known&lt;/code&gt; 委派把联邦流量指过去——这是官方推荐的标准做法，用户 ID 保持简洁，服务部署又不污染主域名。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;第二，联邦流量怎么进来。&lt;/strong&gt; Matrix 服务器之间通信默认走 &lt;code&gt;8448&lt;/code&gt; 端口：别的服务器找 &lt;code&gt;example.com&lt;/code&gt; 的 Matrix 服务时，先查 DNS 里的委派信息，再决定连哪里。两种正规解法：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;.well-known 委派（本篇方案）&lt;/strong&gt;：在 &lt;code&gt;https://example.com/.well-known/matrix/server&lt;/code&gt; 放一个 JSON，声明 &lt;code&gt;{&quot;m.server&quot;: &quot;matrix.example.com:443&quot;}&lt;/code&gt;，联邦流量就走 443 经反向代理进来，不用额外开端口，证书也好管理。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;直连 8448&lt;/strong&gt;：让 Synapse 自己监听 8448 并配好 TLS，或者反代 8448。证书、续期、防火墙都要多管一摊事，没必要。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;第三，想清楚注册策略。&lt;/strong&gt; 默认关掉公开注册，只用管理员命令建号。原因写在排障一节里——开放注册的 Matrix 服务器是垃圾账号和滥用内容的重灾区。&lt;/p&gt;
&lt;p&gt;域名规划定稿后，DNS 先加好两条记录：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;记录&lt;/th&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;值&lt;/th&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;matrix.example.com&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A&lt;/td&gt;
&lt;td&gt;你的服务器 IP&lt;/td&gt;
&lt;td&gt;Synapse 与 Element 的访问域名&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;example.com&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;已有&lt;/td&gt;
&lt;td&gt;主站 IP（可与上不同）&lt;/td&gt;
&lt;td&gt;只需要能托管 &lt;code&gt;/.well-known/&lt;/code&gt; 两个静态文件&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::warning
如果主域名 &lt;code&gt;example.com&lt;/code&gt; 本身就架在这台服务器上（比如博客也在同一台机），.well-known 文件直接放主站根目录即可；如果主域名在别处（比如托管在静态平台），要确认那个平台能让你自定义 &lt;code&gt;.well-known/matrix/&lt;/code&gt; 路径的文件，否则就只能退回「server_name 直接用 matrix.example.com」的方案，用户 ID 会变长，但功能不受影响。
:::&lt;/p&gt;
&lt;h2&gt;部署：Synapse ＋ PostgreSQL 的 Compose 编排&lt;/h2&gt;
&lt;p&gt;目录规划：所有数据放在 &lt;code&gt;/opt/matrix/&lt;/code&gt; 下，Synapse 的配置、媒体、签名密钥都在 &lt;code&gt;synapse-data/&lt;/code&gt; 里，数据库走独立容器。&lt;/p&gt;
&lt;p&gt;先生成初始配置。Synapse 的镜像提供 &lt;code&gt;generate&lt;/code&gt; 命令，一次性把 &lt;code&gt;homeserver.yaml&lt;/code&gt; 和签名密钥写进数据目录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p /opt/matrix/synapse-data
cd /opt/matrix

docker run -it --rm \
  -v /opt/matrix/synapse-data:/data \
  -e SYNAPSE_SERVER_NAME=example.com \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:latest generate
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;SYNAPSE_SERVER_NAME&lt;/code&gt; 填的是&lt;strong&gt;服务器名 &lt;code&gt;example.com&lt;/code&gt;&lt;/strong&gt;，不是部署域名 &lt;code&gt;matrix.example.com&lt;/code&gt;——这是全篇最容易填错的一个地方，填错了整套重来。&lt;/p&gt;
&lt;p&gt;然后写 &lt;code&gt;docker-compose.yml&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  synapse:
    image: matrixdotorg/synapse:latest
    container_name: synapse
    restart: unless-stopped
    environment:
      - SYNAPSE_CONFIG_PATH=/data/homeserver.yaml
    volumes:
      - ./synapse-data:/data
    ports:
      - &quot;127.0.0.1:8008:8008&quot;
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    container_name: synapse-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=synapse
      - POSTGRES_PASSWORD=换成你的强密码
      - POSTGRES_DB=synapse
      - POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C
    volumes:
      - ./pgdata:/var/lib/postgresql/data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个细节：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Synapse 端口只绑 &lt;code&gt;127.0.0.1&lt;/code&gt;，公网流量统一从反向代理进来，和本系列一贯的做法一致。数据库更是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不要把 PostgreSQL 的 5432 端口映射到公网&amp;lt;/span&amp;gt;，它只和 Synapse 在 Compose 内部网络里通信，连宿主机都不用暴露。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;POSTGRES_INITDB_ARGS&lt;/code&gt; 里的排序规则必须是 &lt;code&gt;C&lt;/code&gt;。Synapse 对数据库的 collation 有硬性要求，用默认语言环境建库，启动时它会直接报错拒绝运行——这是新手最常见的第二个坑。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;接着改 &lt;code&gt;synapse-data/homeserver.yaml&lt;/code&gt;，把 SQLite 换成 PostgreSQL 并定下关键开关。找到并修改这几段：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;server_name: &quot;example.com&quot;
public_baseurl: &quot;https://matrix.example.com/&quot;

listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    resources:
      - names: [client, federation]
        compress: false

database:
  name: psycopg2
  args:
    user: synapse
    password: &quot;换成你的强密码&quot;
    database: synapse
    host: db
    cp_min: 5
    cp_max: 10

enable_registration: false
registration_shared_secret: &quot;用 openssl rand -hex 32 生成一串&quot;

media_store_path: /data/media_store
max_upload_size: 100M
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;要点：&lt;code&gt;x_forwarded: true&lt;/code&gt; 必须开，因为 Synapse 在反代后面，要靠 &lt;code&gt;X-Forwarded-For&lt;/code&gt; 拿到真实客户端 IP，否则限流和日志全记成反代的地址；&lt;code&gt;enable_registration: false&lt;/code&gt; 先关死，后面用共享密钥建管理员号。&lt;/p&gt;
&lt;p&gt;启动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/matrix &amp;amp;&amp;amp; docker compose up -d
docker compose logs -f synapse
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;日志里出现 &lt;code&gt;SynapseSite starting at tcp:8008&lt;/code&gt; 且没有数据库报错，第一关就过了。先别急着配客户端，下一节把入口打通。&lt;/p&gt;
&lt;h2&gt;反向代理与 .well-known：联邦能不能通，全看这一节&lt;/h2&gt;
&lt;p&gt;你如果已经按 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager 篇&lt;/a&gt;搭好了统一入口，思路是一样的：给 &lt;code&gt;matrix.example.com&lt;/code&gt; 建一个反代主机，转发到 &lt;code&gt;127.0.0.1:8008&lt;/code&gt; 并申请好 HTTPS 证书。这里把等价的原生 Nginx 配置写全，方便对照检查每一项：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name matrix.example.com;

    # 证书路径按你的实际情况改
    ssl_certificate     /etc/letsencrypt/live/matrix.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem;

    # 必须大于 homeserver.yaml 里的 max_upload_size，否则大文件上传会被 Nginx 先拦下
    client_max_body_size 110M;

    location / {
        proxy_pass http://127.0.0.1:8008;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        # 同步（长轮询）接口需要长连接，把超时放宽
        proxy_read_timeout 600s;
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后是委派文件。在&lt;strong&gt;主域名&lt;/strong&gt; &lt;code&gt;example.com&lt;/code&gt; 的站点根目录下建两个静态文件。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;/.well-known/matrix/server&lt;/code&gt;（注意：没有扩展名，内容是纯 JSON）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
    &quot;m.server&quot;: &quot;matrix.example.com:443&quot;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;/.well-known/matrix/client&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
    &quot;m.homeserver&quot;: {
        &quot;base_url&quot;: &quot;https://matrix.example.com&quot;
    },
    &quot;m.identity_server&quot;: {
        &quot;base_url&quot;: &quot;https://vector.im&quot;
    }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这两个文件的分工：&lt;code&gt;server&lt;/code&gt; 是给&lt;strong&gt;其他服务器&lt;/strong&gt;看的，告诉联邦「找 example.com 的 Matrix 服务请去 matrix.example.com 的 443」；&lt;code&gt;client&lt;/code&gt; 是给&lt;strong&gt;客户端&lt;/strong&gt;看的，用户在登录框里只输入 &lt;code&gt;@anex:example.com&lt;/code&gt;，Element 就靠它知道该连哪台服务器。&lt;/p&gt;
&lt;p&gt;自查命令，两个地址都必须能匿名访问、返回 200 和正确 JSON，且不能有跳转把 &lt;code&gt;.well-known&lt;/code&gt; 吞掉：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -s https://example.com/.well-known/matrix/server
curl -s https://example.com/.well-known/matrix/client
curl -s https://matrix.example.com/_matrix/client/versions
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;最后一条能返回一串版本号 JSON，说明 Synapse 本身和反代都通了。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;联邦的本质就是「发现」：别人能通过 .well-known 找到你、你的证书有效、/_matrix 接口可达，联邦就通了大半，剩下的多半是细节问题。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;建管理员账号&lt;/h2&gt;
&lt;p&gt;注册关着，建号走 Synapse 自带命令，它会用 &lt;code&gt;registration_shared_secret&lt;/code&gt; 做校验：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec -it synapse register_new_matrix_user \
  -c /data/homeserver.yaml http://localhost:8008
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;交互式地输入用户名、密码，并回答 &lt;code&gt;Make admin? [no]&lt;/code&gt; 时填 &lt;code&gt;yes&lt;/code&gt;，第一个管理员就建好了，你的用户 ID 就是 &lt;code&gt;@anex:example.com&lt;/code&gt;（假设用户名填 anex）。普通用户以后也用同一条命令建（admin 回答 no），或者临时开注册、建完立刻关。&lt;/p&gt;
&lt;p&gt;验证一下管理员能登录并拿到 token：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -s -X POST https://matrix.example.com/_matrix/client/v3/login \
  -H &apos;Content-Type: application/json&apos; \
  -d &apos;{&quot;type&quot;:&quot;m.login.password&quot;,&quot;identifier&quot;:{&quot;type&quot;:&quot;m.id.user&quot;,&quot;user&quot;:&quot;@anex:example.com&quot;},&quot;password&quot;:&quot;你的密码&quot;}&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;返回里有 &lt;code&gt;access_token&lt;/code&gt; 字段即成功。这个 token 相当于账号的完全控制权，别外泄。&lt;/p&gt;
&lt;h2&gt;Element Web 客户端：给用户一个网页入口&lt;/h2&gt;
&lt;p&gt;Element 是 Matrix 生态的官方客户端。部署一个自己的 Element Web，用户打开浏览器就能用，不用装 App，而且服务器地址预填好，登录只需输 ID 和密码。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;  element:
    image: vectorim/element-web:latest
    container_name: element
    restart: unless-stopped
    volumes:
      - ./element-config.json:/app/config.json:ro
    ports:
      - &quot;127.0.0.1:8081:80&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把这个服务加进同一个 Compose 文件。&lt;code&gt;element-config.json&lt;/code&gt; 内容：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{
    &quot;default_server_config&quot;: {
        &quot;m.homeserver&quot;: {
            &quot;base_url&quot;: &quot;https://matrix.example.com&quot;,
            &quot;server_name&quot;: &quot;example.com&quot;
        }
    },
    &quot;brand&quot;: &quot;我的 Matrix&quot;,
    &quot;disable_guests&quot;: true,
    &quot;disable_custom_urls&quot;: false
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;再给 Element 单独配一个反代站点，比如 &lt;code&gt;chat.example.com&lt;/code&gt; 转发到 &lt;code&gt;127.0.0.1:8081&lt;/code&gt; 并上 HTTPS。打开后登录页默认就指向你的服务器。手机端则直接装 Element 或 FluffyChat，登录时输入完整的 &lt;code&gt;@anex:example.com&lt;/code&gt;，客户端会靠 &lt;code&gt;.well-known/matrix/client&lt;/code&gt; 自动找到 &lt;code&gt;matrix.example.com&lt;/code&gt;——这也是前面那个文件必须配对的原因。&lt;/p&gt;
&lt;h2&gt;联邦测试：确认全世界能找到你&lt;/h2&gt;
&lt;p&gt;部署完成不等于联邦通了，按这个顺序自查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;官方联邦测试器&lt;/strong&gt;：打开 &lt;code&gt;https://federationtester.matrix.org/&lt;/code&gt;，输入 &lt;code&gt;example.com&lt;/code&gt;，它会完整走一遍「查 .well-known → 连目标服务器 → 验 TLS 证书 → 调联邦接口」的流程，并给出每一步的结果。这是最权威的一票。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;证书检查&lt;/strong&gt;：测试器对证书很严格，自签或过期会直接判联邦失败。用 Let&apos;s Encrypt 的证书并确认自动续期在跑。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;真实互通验证&lt;/strong&gt;：用你的账号去加入一个大型公共房间（比如 &lt;code&gt;#matrix:matrix.org&lt;/code&gt;），能加载出其他服务器用户发的消息，再用公共服务器上的测试账号（或让朋友在别的服务器上）给你发一条私信，能收到、能回复，联邦双向就实锤了。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;看日志&lt;/strong&gt;：&lt;code&gt;docker compose logs synapse | grep -i federation&lt;/code&gt;，联邦请求失败会在这里留下对端域名和错误原因。&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;媒体存储与保留策略：不设上限必爆盘&lt;/h2&gt;
&lt;p&gt;Synapse 把用户上传的图片、文件、以及从联邦同步过来的远程媒体缩略图，全都堆在 &lt;code&gt;media_store_path&lt;/code&gt; 指向的目录里。聊天越活跃涨得越快，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不配保留策略的 Matrix 服务器，磁盘被媒体文件吃满只是时间问题&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;在 &lt;code&gt;homeserver.yaml&lt;/code&gt; 里加上保留策略（改完重启 Synapse 生效）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;media_retention:
  # 本地用户上传的媒体保留多久，本地媒体是你的核心数据，可以给长一点或不设
  local_media_lifetime: 730d
  # 远程联邦媒体只是缓存，过期删掉不影响，需要时重新拉取
  remote_media_lifetime: 30d

# URL 预览会把外链的缩略图也缓存下来，同样吃空间，群聊多时建议直接关
url_preview_enabled: false
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;已经涨起来的存量，可以用管理员 API 清理过期的远程缓存：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -s -X POST \
  &quot;https://matrix.example.com/_synapse/admin/v1/media/&amp;lt;server_name&amp;gt;/delete?before_ts=&amp;lt;毫秒时间戳&amp;gt;&quot; \
  -H &quot;Authorization: Bearer &amp;lt;管理员 access_token&amp;gt;&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;更稳妥的日常做法是把媒体目录大小纳入监控（本系列的监控告警篇讲过思路），设个阈值，涨到警戒线先报警再处理，别等磁盘写满 Synapse 直接罢工。&lt;/p&gt;
&lt;h2&gt;备份：有一样东西丢了，服务器等于换了身份&lt;/h2&gt;
&lt;p&gt;按 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;备份与迁移篇&lt;/a&gt;的通用方法，Matrix 需要备三样：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 数据库
docker exec synapse-db pg_dump -U synapse synapse | gzip &amp;gt; synapse-db-$(date +%F).sql.gz

# 2. 配置与密钥（homeserver.yaml、签名密钥都在这个目录里）
# 3. 媒体文件
tar -czf synapse-data-$(date +%F).tar.gz /opt/matrix/synapse-data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;其中 synapse-data 里的 &lt;strong&gt;&lt;code&gt;example.com.signing.key&lt;/code&gt;（签名密钥）是重中之重&lt;/strong&gt;：联邦里其他服务器靠它认你的身份，丢了它，你的服务器在全网眼里就「不是原来那台了」，房间成员关系和联邦信任全部要重建，实际效果约等于换域名重开。这一条也呼应 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;安全与访问控制篇&lt;/a&gt;的原则：密钥类文件备份要加密、要异地，别和本体放同一块盘。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. 联邦连不上，测试器报错。&lt;/strong&gt;
按链路顺序查：先 &lt;code&gt;curl&lt;/code&gt; 两个 &lt;code&gt;.well-known&lt;/code&gt; 文件，确认返回的是 JSON 本身而不是主站的 404 页面或重定向——很多主站框架（包括一些静态托管）会把无扩展名路径吞掉，这是最高频死因。再查委派目标 &lt;code&gt;matrix.example.com:443&lt;/code&gt; 的证书是否覆盖该域名、是否过期。最后看 Synapse 日志里对端连接的具体报错。如果你的主域名实在托管不了 &lt;code&gt;.well-known&lt;/code&gt;，备选方案是 DNS SRV 记录 &lt;code&gt;_matrix-fed._tcp.example.com&lt;/code&gt; 指向 &lt;code&gt;matrix.example.com 8448&lt;/code&gt;，但那就得把 8448 端口和它的证书一起管起来，优先级低于 .well-known。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. Element 登录一直转圈。&lt;/strong&gt;
九成是客户端侧发现失败：登录时输的 ID 里服务器名部分（&lt;code&gt;example.com&lt;/code&gt;）对应的 &lt;code&gt;.well-known/matrix/client&lt;/code&gt; 打不开或内容写错，Element 找不到 &lt;code&gt;base_url&lt;/code&gt; 就无限重试。其次是 &lt;code&gt;element-config.json&lt;/code&gt; 里 &lt;code&gt;base_url&lt;/code&gt; 写成了内网地址或 http。浏览器开 F12 看网络面板，找 &lt;code&gt;.well-known&lt;/code&gt; 和 &lt;code&gt;/login&lt;/code&gt; 两个请求的状态码，定位最快。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 媒体文件涨太快。&lt;/strong&gt;
先分清涨的是本地还是远程：&lt;code&gt;du -sh synapse-data/media_store/local_content synapse-data/media_store/remote_content&lt;/code&gt;。远程涨得快是联邦大房间的缩略图缓存，开上面的 &lt;code&gt;remote_media_lifetime&lt;/code&gt; 并清一次存量；本地涨得快多半是有人在传大文件，调小 &lt;code&gt;max_upload_size&lt;/code&gt;，同时检查 &lt;code&gt;url_preview_enabled&lt;/code&gt; 是不是开着在给每个外链存图。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 注册被滥用，一夜之间多出一堆垃圾账号。&lt;/strong&gt;
说明注册被打开过或共享密钥泄漏。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;个人服务器就不要开放注册&amp;lt;/span&amp;gt;：确认 &lt;code&gt;enable_registration: false&lt;/code&gt;、换掉 &lt;code&gt;registration_shared_secret&lt;/code&gt;，用管理员 API 把陌生账号逐个停用（deactivate）。真有给朋友批量开号的需求，临时开启、建完立刻关闭，并全程盯着用户列表。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. Synapse 越用越卡。&lt;/strong&gt;
先看是不是数据库在裸奔：确认 &lt;code&gt;homeserver.yaml&lt;/code&gt; 用的是 PostgreSQL 而不是默认的 SQLite（小规模自娱自乐之外 SQLite 必然拖后腿）；再给服务器加内存，Synapse 是吃内存大户，1 核 1G 只够勉强启动，长期用建议 2G 起步；房间历史太多时，管理员 API 的 purge history 功能可以清理超大房间的旧状态。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Matrix 这一篇的难点不在装，而在&lt;strong&gt;想清楚&lt;/strong&gt;：server_name 定死不可改，所以域名设计要在部署之前完成；联邦靠 .well-known 发现，所以委派文件和证书就是服务器的「对外名片」；媒体和签名密钥决定这台服务器能活多久、丢没丢身份。把这三件事做对，Synapse＋PostgreSQL＋Element 这套组合就能长期稳定地跑下去，你的 &lt;code&gt;@你:你的域名&lt;/code&gt; 从此是全网可达的、真正属于你自己的聊天身份。&lt;/p&gt;
</content:encoded></item><item><title>监控告警实战：通知、值班与故障处理流程</title><link>https://www.anexns.cloudns.org/posts/selfhost-monitoring-alerts/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-monitoring-alerts/</guid><description>监控装好了，告警却要么不响、要么响个不停？这篇把通知渠道配置、分级降噪、值班响应与故障处理手册一次搭完，让每一次告警都值得你拿起手机。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：告警的两种死法&lt;/h2&gt;
&lt;p&gt;前两篇我们装好了 &lt;a href=&quot;/posts/selfhost-komari/&quot;&gt;Komari：轻量服务器监控探针部署与多节点接入&lt;/a&gt; 和 &lt;a href=&quot;/posts/selfhost-uptime-kuma/&quot;&gt;Uptime Kuma：服务可用性监控与公开状态页&lt;/a&gt;，机器和服务都有人盯了。但监控系统真正的考验在通知这一环，而它通常有两种死法：&lt;/p&gt;
&lt;p&gt;第一种是&lt;strong&gt;该响的不响&lt;/strong&gt;：通知渠道配错了、Bot 没激活、邮件进了垃圾箱，服务挂了一夜你毫不知情，直到用户找上门。第二种是&lt;strong&gt;不该响的乱响&lt;/strong&gt;：网络抖动一次报三条、磁盘 60% 就半夜夺命连环 Call，一周之后你把通知群设成了免打扰——这一刻，监控系统事实上已经死了。&lt;/p&gt;
&lt;p&gt;这篇就干一件事：把「探测到异常」到「问题被处理完」之间的链路设计好。核心目标只有一句：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;让每一次告警都值得拿起手机，让每一次拿起手机都知道下一步干什么。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;告警链路：五环缺一不可&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;发现异常 → 通知送达 → 有人确认 → 按手册处理 → 复盘改进
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;发现&lt;/strong&gt;靠探测参数：间隔、重试、阈值，决定灵敏度。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;送达&lt;/strong&gt;靠渠道配置：发出去不等于收得到，必须实测。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;确认&lt;/strong&gt;靠分工：哪怕只有你一个人，也要区分「立刻处理」和「明早再说」。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;处理&lt;/strong&gt;靠手册：常见故障写好步骤，凌晨三点不靠脑子靠清单。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;复盘&lt;/strong&gt;靠记录：每次真故障留三行字——原因、处理、如何防再发。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;下面逐环落地。&lt;/p&gt;
&lt;h2&gt;通知渠道：选型与配置&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;渠道&lt;/th&gt;
&lt;th&gt;送达速度&lt;/th&gt;
&lt;th&gt;可靠性&lt;/th&gt;
&lt;th&gt;适合级别&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Telegram Bot&lt;/td&gt;
&lt;td&gt;秒级&lt;/td&gt;
&lt;td&gt;高（需网络通畅）&lt;/td&gt;
&lt;td&gt;全部级别的主力&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;邮件 SMTP&lt;/td&gt;
&lt;td&gt;分钟级&lt;/td&gt;
&lt;td&gt;中，可能进垃圾箱&lt;/td&gt;
&lt;td&gt;低优先级、日报汇总&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Webhook&lt;/td&gt;
&lt;td&gt;秒级&lt;/td&gt;
&lt;td&gt;取决于接收端&lt;/td&gt;
&lt;td&gt;联动自动化、转发到其他系统&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;短信/电话类服务&lt;/td&gt;
&lt;td&gt;秒级&lt;/td&gt;
&lt;td&gt;高，但收费&lt;/td&gt;
&lt;td&gt;仅核心服务致命故障&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;个人自建的务实组合：&lt;strong&gt;Telegram 做主渠道，邮件做备份渠道与汇总渠道&lt;/strong&gt;。两个渠道都接进 Uptime Kuma，核心监控项同时勾选两个，普通项只勾 Telegram。&lt;/p&gt;
&lt;h3&gt;Telegram Bot 配置（完整流程）&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;在 Telegram 里找 &lt;code&gt;@BotFather&lt;/code&gt;，发送 &lt;code&gt;/newbot&lt;/code&gt;，按提示起名，拿到 Bot Token。&lt;/li&gt;
&lt;li&gt;给你的 Bot 随便发一条消息（如 &lt;code&gt;hi&lt;/code&gt;）——这一步不能省，Bot 无法主动联系从未与它对话过的用户。&lt;/li&gt;
&lt;li&gt;浏览器打开 &lt;code&gt;https://api.telegram.org/bot&amp;lt;你的Token&amp;gt;/getUpdates&lt;/code&gt;，在返回的 JSON 里找到 &lt;code&gt;chat&lt;/code&gt; → &lt;code&gt;id&lt;/code&gt;，这就是你的 Chat ID。&lt;/li&gt;
&lt;li&gt;在 Uptime Kuma 的设置 → 通知 → 新增 Telegram，填入 Token 与 Chat ID，保存并发送测试消息。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Bot Token 等同于这个机器人的完全控制权，不要写进截图、博客或公开仓库&amp;lt;/span&amp;gt;；泄露了就回 BotFather 用 &lt;code&gt;/revoke&lt;/code&gt; 重新生成。&lt;/p&gt;
&lt;h3&gt;邮件渠道配置要点&lt;/h3&gt;
&lt;p&gt;用专门的应用密码而不是邮箱主密码（主流邮箱都支持生成应用专用密码）；发送测试后如果收不到，先查垃圾箱，再确认 SMTP 的端口与加密方式（465 对应 SSL、587 对应 STARTTLS）配对无误。&lt;/p&gt;
&lt;h3&gt;Webhook 的位置&lt;/h3&gt;
&lt;p&gt;Webhook 不直接找人，它负责把告警转发给「能找人的系统」或触发自动化：比如把消息推给家里的智能音箱、写入工单、或联动重启脚本。新手期可以只留一个心智：渠道不够用时，Webhook 是扩展口。&lt;/p&gt;
&lt;h2&gt;分级与降噪：让告警分轻重&lt;/h2&gt;
&lt;h3&gt;先分级，再谈参数&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;级别&lt;/th&gt;
&lt;th&gt;定义&lt;/th&gt;
&lt;th&gt;例子&lt;/th&gt;
&lt;th&gt;期望响应&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;P0 致命&lt;/td&gt;
&lt;td&gt;核心服务整体不可用&lt;/td&gt;
&lt;td&gt;反代入口挂、密码库不可达、整机离线&lt;/td&gt;
&lt;td&gt;立即处理，多渠道齐发&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;P1 严重&lt;/td&gt;
&lt;td&gt;功能受损但未全挂&lt;/td&gt;
&lt;td&gt;磁盘超 85%、证书 7 天内到期、单节点离线&lt;/td&gt;
&lt;td&gt;当天处理，Telegram 通知&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;P2 提醒&lt;/td&gt;
&lt;td&gt;趋势异常&lt;/td&gt;
&lt;td&gt;流量用量超八成、内存持续走高&lt;/td&gt;
&lt;td&gt;邮件汇总，有空看&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;降噪四件套&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;重试再报&lt;/strong&gt;：Uptime Kuma 里给监控项设重试 2–3 次，连续失败才判定 Down。一次抖动不配吵醒任何人。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;恢复也要报&lt;/strong&gt;：开启「恢复通知」。知道它自己好了，你就不用爬起来了；没有恢复通知的故障处理，总悬着一颗心。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;维护窗口静默&lt;/strong&gt;：计划内重启、升级之前，在 Uptime Kuma 里给相关监控项开维护时段，这段时间的异常不发通知。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;阈值留缓冲&lt;/strong&gt;：磁盘告警设两档——80% 发 P2 提醒，92% 才发 P1。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;把阈值卡在「出事边缘」等于放弃预警，告警的意义就是提前量。&amp;lt;/span&amp;gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;告警太多等于没有告警&amp;lt;/span&amp;gt;——如果某个监控项一周误报三次，先修它的参数（间隔、重试、判定方式），不要靠意志力忍受它。忍受的终点一定是全局静音。&lt;/p&gt;
&lt;h2&gt;心跳监控：盯住那些「不说话」的任务&lt;/h2&gt;
&lt;p&gt;有一类故障上面的探测都发现不了：定时任务悄悄停了。备份脚本三天没跑，监控面板上一切绿色，因为没有任何东西「坏掉」，只是该来的没来。&lt;/p&gt;
&lt;p&gt;解法是 Push 型监控（心跳/Dead Man&apos;s Switch）：在 Uptime Kuma 里新建一个 Push 类型的监控项，它会生成一个专属上报地址；让任务在每次成功执行后访问一下这个地址。超过设定时间没等到心跳，就判定异常并告警。备份脚本的收尾加一行即可：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 备份成功后向 Uptime Kuma 报平安，失败则不会执行到这一行
curl -fsS &quot;https://kuma.example.com/api/push/&amp;lt;你的令牌&amp;gt;&quot; &amp;gt; /dev/null
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把第 11 篇 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移实战&lt;/a&gt; 里的每个备份任务都这样挂上心跳，「备份到底跑没跑」就从玄学变成了确定答案。&lt;/p&gt;
&lt;h2&gt;故障处理手册：把经验写下来&lt;/h2&gt;
&lt;p&gt;处理流程不要临场发挥，写成手册放在手边（笔记软件、仓库 Wiki 都行）。给你一个可以直接套用的骨架：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 故障处理手册（示例）

## 收到 P0 告警
1. 先看状态页/Kuma 列表，确认影响范围：单服务还是整机？
2. 整机问题：查云厂商控制台（是否欠费/维护/宿主机故障）
3. 单服务问题：进服务目录看日志
   cd /opt/apps/&amp;lt;服务&amp;gt; &amp;amp;&amp;amp; docker compose logs --tail=100
4. 磁盘满是头号嫌疑：df -h 先看一眼
5. 处理后观察 10 分钟，确认恢复通知到达
6. 在记录表补三行：时间、原因、处理

## 磁盘告警
1. du -sh /opt/apps/* 定位大户
2. Docker 日志与镜像是常见元凶：docker system df
3. 清理后确认备份任务仍正常（别把备份清了）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;手册的价值不在写得多全，而在于&lt;strong&gt;每次故障后顺手修订&lt;/strong&gt;：这次踩的坑，下次就变成清单里的一行。三个月后，这本手册就是你自己的运维百科。&lt;/p&gt;
&lt;h2&gt;值班：一个人也要有「值班意识」&lt;/h2&gt;
&lt;p&gt;自建场景没有团队轮班，但可以有等价安排：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;分时段策略&lt;/strong&gt;：P0 全天候直达手机（Telegram 单独关掉免打扰豁免）；P1 只在白天推送；P2 走邮件日报。手机系统的「专注模式」可以给 Telegram 开白名单。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;出差/旅行前检查&lt;/strong&gt;：提前确认自动续费、证书、磁盘余量，并把手册和登录方式放在手机能打开的地方。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;恢复确认闭环&lt;/strong&gt;：处理完不要只看服务恢复，要确认告警系统也回到了正常状态（监控项变绿、恢复通知到达），否则下一次故障它可能还在「已触发未恢复」的怪状态里。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
每月做一次「告警演练」：手动停掉一个不重要的服务，完整走一遍链路——多久收到通知、消息里信息够不够定位、手册步骤顺不顺。演练发现的问题都是免费的，等真故障来教，学费就是停机时间。
:::&lt;/p&gt;
&lt;h2&gt;排障：通知链路本身出问题时&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;测试消息能收、真告警收不到&lt;/strong&gt;：检查该监控项是否勾选了通知渠道（每个监控项单独绑定，新建时容易漏）；再看渠道是否被全局暂停。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Telegram 突然全部失联&lt;/strong&gt;：先用 &lt;code&gt;getUpdates&lt;/code&gt; 地址验证 Token 是否还有效，再确认服务器出网正常。Token 被重置过的话，所有引用它的地方都要同步更新。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;邮件全进垃圾箱&lt;/strong&gt;：把发件地址加入通讯录/白名单；有条件的话给发件域名配好 SPF/DKIM，这是发件域名的信誉问题，不是 Kuma 的问题。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;同故障重复轰炸&lt;/strong&gt;：这是监控项在 Up/Down 之间反复横跳。拉长间隔、增加重试、并检查目标服务是不是真的在频繁重启（&lt;code&gt;docker compose ps&lt;/code&gt; 看重启次数）——有时「误报」其实是服务在真出问题，只是幅度小到平时没人注意。&lt;/p&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：只用一个通知渠道行不行？&lt;/strong&gt;
P0 级别建议至少两个独立渠道。Telegram 挂了还有邮件，邮件延迟了还有 Telegram——告警渠道本身也需要冗余，这和服务冗余是一个道理。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：告警消息里应该包含什么？&lt;/strong&gt;
最低配：服务名、状态变化（Down/Up）、发生时间、监控详情链接。Uptime Kuma 的默认模板基本够用，别删字段图简洁，出事时每多一个定位线索就少一分钟停机。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：家人的服务也要进这套告警吗？&lt;/strong&gt;
给家人用的服务（如云盘、影音）进监控，但分级可以放低：他们打不开时先看第 4 篇的状态页，确认是故障再找你，告警则按 P1 处理即可。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：这套流程会不会太重？&lt;/strong&gt;
重的是第一次搭建，大约一小时。之后每次故障都在给手册充值。个人自建的运维成熟度，就是这么攒出来的。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;监控告警的完整链路是：探测参数决定发现速度、渠道实测决定送达可靠、分级与降噪决定你会不会把它静音、手册决定处理速度、心跳监控补上定时任务这块盲区。把这篇做完，你的自建体系就从「装好了」升级为「有人管」。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;监控的终点不是大盘和曲线，而是故障发生时，一个人能不慌不忙地把它处理完。&amp;lt;/span&amp;gt;接下来回到业务服务本身：从最能提升幸福感的私人云盘开始。&lt;/p&gt;
</content:encoded></item><item><title>自建服务实战：go-music-dl 全网音乐搜索下载</title><link>https://www.anexns.cloudns.org/posts/selfhost-music-dl/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-music-dl/</guid><description>用 go-music-dl 在自己的服务器上搭一个全网音乐搜索下载服务：聚合网易云、QQ、酷狗、Bilibili 等十多个平台，Web、TUI、桌面端与 Docker 多种用法一网打尽，附登录、本地音乐库、WebDAV 同步与 AI 播放器控制接口的完整实战。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：找一首歌，为什么要开四个 App&lt;/h2&gt;
&lt;p&gt;想听或者想存一首歌的时候，流程通常是这样的：先开网易云搜一遍，没有；再开 QQ 音乐搜一遍，有，但要登录；换酷狗，有另一个版本；Bilibili 上还有个现场版。四个平台四个账号体系，搜索结果各说各话，真要下载更是各下各的，文件散落一地，命名格式还都不一样。&lt;/p&gt;
&lt;p&gt;这件事麻烦的根源不在某个平台，而在于&lt;strong&gt;入口太碎&lt;/strong&gt;：同一批歌被切在十几个平台里，你却只能一个一个进去找。go-music-dl 的解法是把入口收拢成一个：一个程序同时对接十多个平台，一次搜索多源并发返回结果，哪个源有、哪个源音质好，一眼看完，当场试听、当场下载。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;自建一个音乐搜索下载服务的核心价值就一句话：一个入口搜遍全网，下载的文件进自己的目录、按自己的规则命名。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;认识 go-music-dl 与支持平台 → Web、TUI、桌面端四种用法逐个上手 → Docker 部署到自己的服务器 → 登录拿回自己的歌单 → 本地音乐库与 WebDAV 同步 → AI 接口操控播放器 → 安全收尾&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;项目地址：https://github.com/guohuiyuan/go-music-dl&lt;/p&gt;
&lt;h2&gt;它是什么：一个程序聚合十多个平台&lt;/h2&gt;
&lt;p&gt;go-music-dl 是一个用 Go 语言写的全网音乐搜索与下载工具，AGPL-3.0 开源。它不是某一个平台的下载器，而是一个聚合层：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;多源并发搜索&lt;/strong&gt;：一次关键词同时打到多个平台，结果合并展示，还能一键换源——同一首歌在 A 平台没有或音质差，直接切到 B 平台的版本。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;无损音质解析&lt;/strong&gt;：在来源提供的范围内解析可用的最高音质，搜索时可屏蔽 Live、Remix、Demo 等版本和 60 秒以下的试听片段，结果更干净。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;覆盖面完整&lt;/strong&gt;：单曲、歌单、专辑、排行榜都支持；粘贴歌单或专辑链接能自动识别来源并进入详情，曲目可批量播放、批量下载、导入本地歌单。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;支持的平台包括网易云、QQ、酷狗、酷我、咪咕、汽水、Apple Music、Spotify、Bilibili、Jamendo、JOOX、千千等十多个，实际可用来源以界面列表为准。首页的排行榜聚合了网易云、QQ、酷狗、酷我、咪咕、汽水、Apple Music 和 Spotify 的官方榜单，各平台的热门单曲就是当地的热歌榜，榜上歌曲可直接播放和下载。&lt;/p&gt;
&lt;p&gt;先和另外两条路线拉个对照，看看它到底站在什么位置：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;维度&lt;/th&gt;
&lt;th&gt;go-music-dl&lt;/th&gt;
&lt;th&gt;各平台官方客户端&lt;/th&gt;
&lt;th&gt;单个平台下载脚本&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;平台覆盖&lt;/td&gt;
&lt;td&gt;十多个平台聚合在一个入口&lt;/td&gt;
&lt;td&gt;一个客户端只管自家曲库&lt;/td&gt;
&lt;td&gt;通常只对接一个平台&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;搜索方式&lt;/td&gt;
&lt;td&gt;多源并发，一次出多平台结果，可换源&lt;/td&gt;
&lt;td&gt;只能搜自家&lt;/td&gt;
&lt;td&gt;只能搜目标平台&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;批量与歌单&lt;/td&gt;
&lt;td&gt;单曲、歌单、专辑、排行榜均可批量处理&lt;/td&gt;
&lt;td&gt;歌单在自家生态内可用&lt;/td&gt;
&lt;td&gt;多数只处理单曲链接&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;部署形态&lt;/td&gt;
&lt;td&gt;Web 服务、TUI、桌面端、Android、Docker&lt;/td&gt;
&lt;td&gt;装在每台设备上&lt;/td&gt;
&lt;td&gt;本地跑脚本，无服务形态&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;登录要求&lt;/td&gt;
&lt;td&gt;搜索试听下载免登录；个人歌单与设置才需要登录&lt;/td&gt;
&lt;td&gt;基本都要登录自家账号&lt;/td&gt;
&lt;td&gt;视脚本而定，常要自己拼 Cookie&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;文件归宿&lt;/td&gt;
&lt;td&gt;自己的目录，文件名模板可控，可同步 WebDAV&lt;/td&gt;
&lt;td&gt;多在 App 内部目录&lt;/td&gt;
&lt;td&gt;当前目录，自己收拾&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;简单说：官方客户端是「一平台一世界」，脚本是「一平台一锤子」，go-music-dl 想做的是把搜索和下载这一层抽出来，做成一个跑在自己手里的服务。它和本系列上一篇的 &lt;a href=&quot;/posts/selfhost-libreget/&quot;&gt;LibreGet&lt;/a&gt; 是兄弟关系：LibreGet 管视频与课程那类文件的下载，go-music-dl 专攻音乐这一摊，下好的歌再顺手归进自己的文件库即可。&lt;/p&gt;
&lt;h2&gt;用法一：Web 服务，浏览器里全搞定&lt;/h2&gt;
&lt;p&gt;Web 是最推荐的用法，起服务只需要一条命令：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 启动 Web 服务
./music-dl web
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;默认访问地址是 &lt;code&gt;http://localhost:8080/music&lt;/code&gt;。搜索、试听、下载、浏览歌单都&lt;strong&gt;不需要登录&lt;/strong&gt;，打开页面就能用；只有修改设置、管理 Cookie 这类操作才需要管理员账号。首次启动时，启动日志里会打印一行 &lt;code&gt;Web setup token&lt;/code&gt;，拿它去创建管理员账号，创建完这个令牌就完成使命了。&lt;/p&gt;
&lt;p&gt;如果你的服务器上已经有一套反向代理，想把这个服务挂在二级目录下面，加一个参数：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 挂载到反向代理的二级目录 /dl
./music-dl web --base-path /dl
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这样它就老老实实待在 &lt;code&gt;/dl&lt;/code&gt; 路径下，和同机的其他服务互不打扰。&lt;/p&gt;
&lt;p&gt;Web 界面里能做的事比想象中多：三种搜索类型（单曲、歌单、专辑）随便切；各平台的分类歌单可以直接逛，汽水还提供每日推荐、流行、华语、欧美、国风等分类；播放器支持逐字歌词、歌词字体调整、全局快捷键和媒体键。&lt;/p&gt;
&lt;h2&gt;用法二：TUI 与 CLI，终端里搜歌下歌&lt;/h2&gt;
&lt;p&gt;不想开浏览器、就想在终端里快速下两首歌，用 TUI 模式：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 终端搜索，直接进入交互界面
./music-dl -k &quot;周杰伦&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;TUI 的操作键位很顺手，记住这几个就够用了：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;↑&lt;/code&gt; / &lt;code&gt;↓&lt;/code&gt;：上下移动&lt;/li&gt;
&lt;li&gt;&lt;code&gt;空格&lt;/code&gt;：勾选当前歌曲&lt;/li&gt;
&lt;li&gt;&lt;code&gt;a&lt;/code&gt;：全选 / 清空&lt;/li&gt;
&lt;li&gt;&lt;code&gt;r&lt;/code&gt;：对勾选的歌曲换源&lt;/li&gt;
&lt;li&gt;&lt;code&gt;Enter&lt;/code&gt;：下载勾选的歌曲&lt;/li&gt;
&lt;li&gt;&lt;code&gt;b&lt;/code&gt;：返回&lt;/li&gt;
&lt;li&gt;&lt;code&gt;w&lt;/code&gt;：每日推荐歌单&lt;/li&gt;
&lt;li&gt;&lt;code&gt;q&lt;/code&gt;：退出&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;纯脚本化的场景用 CLI 参数一把梭：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 查看全部帮助
./music-dl -h

# 指定搜索源，只搜 QQ 和网易云
./music-dl -k &quot;周杰伦 晴天&quot; -s qq,netease

# 指定下载目录
./music-dl -k &quot;周杰伦&quot; -o ./my_music

# 下载时连封面和歌词一起带上
./music-dl -k &quot;周杰伦&quot; --cover --lyrics
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;-s&lt;/code&gt; 指定源在目标明确时特别有用：你很清楚这首歌在哪个平台的版本最好，就别让十几个源一起陪跑了。&lt;/p&gt;
&lt;h2&gt;用法三：桌面端与 Android，装上就用&lt;/h2&gt;
&lt;p&gt;不想碰命令行的，Releases 里有现成的桌面包，Windows、Linux、macOS 都有，分为 &lt;code&gt;music-dl-desktop-rust&lt;/code&gt; 和 &lt;code&gt;music-dl-desktop-go&lt;/code&gt; 两个版本，下载对应平台的包解压后直接运行，桌面端会自动把内置服务拉起来，用法和 Web 版一致。&lt;/p&gt;
&lt;p&gt;Android 优先下载 &lt;code&gt;music-dl_arm64-v8a.apk&lt;/code&gt;，已经内置 FFmpeg，不需要再额外装任何东西。装好之后建议进 Web 界面右上角的「设置」，把本地下载目录改成 &lt;code&gt;/sdcard/Music&lt;/code&gt;，这样下载的文件直接进系统音乐目录，任何播放器都能扫到。iOS 则提供未签名包，需要自行签名，门槛相对高一些。&lt;/p&gt;
&lt;h2&gt;Docker 部署：上服务器就一行命令&lt;/h2&gt;
&lt;p&gt;自建服务的正经归宿是自己的服务器。go-music-dl 的 Docker 部署简单到只有一条命令——把仓库的 &lt;code&gt;docker-compose.yml&lt;/code&gt; 拿下来，执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d --pull always --remove-orphans
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动后访问 &lt;code&gt;http://localhost:8080&lt;/code&gt; 即可。几个贴心之处值得点名：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;首次启动会&lt;strong&gt;自动创建 &lt;code&gt;./data&lt;/code&gt; 目录并配好容器写权限&lt;/strong&gt;，不用手动建目录再改属主，这是很多自建服务最容易卡住新手的一步，它直接替你做了。&lt;/li&gt;
&lt;li&gt;Compose 只依赖 &lt;code&gt;docker-compose.yml&lt;/code&gt; 和镜像本身，不需要把整个仓库拉下来，更不需要本地的 Dockerfile。&lt;/li&gt;
&lt;li&gt;真要改源码自建镜像，仓库另备了开发用 Compose：&lt;code&gt;docker compose -f docker-compose.dev.yml up -d --build&lt;/code&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;服务起来之后，前面说的 &lt;code&gt;Web setup token&lt;/code&gt; 在容器日志里找：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose logs | grep -i &quot;setup token&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;拿它建好管理员账号，Web 端的部署就算齐活了。下载好的文件默认落在 &lt;code&gt;data/downloads&lt;/code&gt;，这个目录后面讲本地音乐库时还会回来。&lt;/p&gt;
&lt;h2&gt;登录与音质：把你自己的歌单拿回来&lt;/h2&gt;
&lt;p&gt;不登录能搜能下，但你&lt;strong&gt;自己账号里的东西&lt;/strong&gt;得登录后才认：网易云、QQ、酷狗、汽水、Spotify 的个人歌单、收藏和喜欢的歌曲，都要在登录或配置 Cookie / Token 后才能读取；部分平台的下载本身也要求有效的登录状态（比如 QQ 下载需要有效 Cookie）。&lt;/p&gt;
&lt;p&gt;登录方式有两种：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;扫码登录&lt;/strong&gt;：网易云、QQ、酷狗、Bilibili 都支持，在设置页打开对应平台扫码即可，成功后 Cookie 自动保存。汽水音乐暂不支持扫码，需要在设置页手动填写 Cookie，设置页里附了手动抓取的步骤和请求域名，照着做即可。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;手动 Cookie&lt;/strong&gt;：设置页可集中管理各平台的 Cookie。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Cookie 等同于你的账号登录态，只保存在本地数据目录里，千万不要把配置文件公开分享出去。&amp;lt;/span&amp;gt;这是用一切此类工具的第一原则：方便是方便，账号安全不能搭进去。登录只为两件事——读取你自己的歌单收藏、获取你账号权益范围内的音质，仅此而已。&lt;/p&gt;
&lt;h2&gt;本地音乐库：下好的歌别躺着吃灰&lt;/h2&gt;
&lt;p&gt;下载只是上半场。go-music-dl 还能把本地已有的音频文件管起来，变成一个可搜索的本地曲库：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;扫描入库&lt;/strong&gt;：默认读取 &lt;code&gt;data/downloads&lt;/code&gt;（Android 是 &lt;code&gt;/sdcard/Music&lt;/code&gt;），支持 &lt;code&gt;mp3&lt;/code&gt;、&lt;code&gt;flac&lt;/code&gt;、&lt;code&gt;m4a&lt;/code&gt;、&lt;code&gt;ogg&lt;/code&gt;、&lt;code&gt;wav&lt;/code&gt;、&lt;code&gt;wma&lt;/code&gt;、&lt;code&gt;aac&lt;/code&gt;；也支持手动上传导入。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;自动识别&lt;/strong&gt;：优先读取文件内嵌的元数据、封面和歌词，缺失时查找同名资源并用 &lt;code&gt;ffprobe&lt;/code&gt; 补全信息。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;当作一个搜索源&lt;/strong&gt;：本地音乐以 &lt;code&gt;local&lt;/code&gt; 源的身份参与搜索，和在线结果并列出现；底层用 SQLite 建索引，支持分页、扫描快照、元数据缓存和后台刷新，歌多了也不卡。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;文件名模板&lt;/strong&gt;：设置页支持 &lt;code&gt;{name}&lt;/code&gt;、&lt;code&gt;{artist}&lt;/code&gt;、&lt;code&gt;{album}&lt;/code&gt;、&lt;code&gt;{source}&lt;/code&gt;、&lt;code&gt;{id}&lt;/code&gt;、&lt;code&gt;{ext}&lt;/code&gt; 等变量，下载和整理时按你的规则命名，告别一堆乱码文件名。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;歌单操作&lt;/strong&gt;：本地歌曲可批量收藏进自制歌单；删除本地文件需要二次确认，已收藏的条目可以保留，之后换源恢复。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;工作流就此闭环：在线搜到下载回来，自动进本地库，再把目录交给 &lt;a href=&quot;/posts/selfhost-alist/&quot;&gt;Alist&lt;/a&gt; 做文件管理、交给 &lt;a href=&quot;/posts/selfhost-jellyfin/&quot;&gt;Jellyfin&lt;/a&gt; 做跨设备播放，一个自建音乐小生态就成型了。&lt;/p&gt;
&lt;h2&gt;下载与同步：断点、内嵌信息与 WebDAV&lt;/h2&gt;
&lt;p&gt;下载环节的细节决定了长期使用的舒适度，这块它做得比较扎实：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;流式下载&lt;/strong&gt;：默认流式模式，支持 HTTP &lt;code&gt;Range&lt;/code&gt;，意味着断点续传和边下边播拖动进度都有底子，不会因为网络抖一下就从头再来。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;内嵌封面与歌词&lt;/strong&gt;：开启后下载时把封面和歌词写进音频文件内部，依赖 &lt;code&gt;ffmpeg&lt;/code&gt; 完成；如果环境里没有 &lt;code&gt;ffmpeg&lt;/code&gt;，这一步自动跳过，不影响原始音频下载。也可以选择在音频同目录生成同名标准 LRC 歌词文件，不动已有的歌词文件。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;WebDAV 同步&lt;/strong&gt;：设置页填上 WebDAV 地址、账号、密码和远端目录，下载完成即可同步一份到远端——服务器上下歌、家里 NAS 上存档，这个搭配很顺手；仓库还专门备了一个 &lt;code&gt;docker-compose.webdav.yml&lt;/code&gt; 方便对照配置。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;环境依赖只有一个要注意：&lt;code&gt;ffmpeg&lt;/code&gt; 与 &lt;code&gt;ffprobe&lt;/code&gt; 负责本地音乐探测和元数据写入。Docker 镜像和 Android APK 已经内置，CLI、桌面端和 iOS 包需要自行安装，装没装好一条命令验明：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ffmpeg -version
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;AI 接口：让助手直接操控你的播放器&lt;/h2&gt;
&lt;p&gt;这是 go-music-dl 最出人意料的一块：Web 服务对外暴露了一套给 AI 调用的接口，助手能&lt;strong&gt;直接操控你正开着的网页播放器&lt;/strong&gt;——点歌、切歌、暂停、调音量、拖进度，全靠 HTTP 请求完成，不需要浏览器自动化，不需要模拟点击。&lt;/p&gt;
&lt;p&gt;设计上它没有另起一套 AI 专用路由，而是把能力索引列出来，复用现有的 &lt;code&gt;/music/*&lt;/code&gt; 接口：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;能力索引：&lt;code&gt;http://localhost:8080/music/api/ai/index&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;精简说明（给模型读的）：&lt;code&gt;http://localhost:8080/music/llms.txt&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;普通搜索接口本身就是 AI 可用的，比如只搜 QQ 和网易云：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl &quot;http://localhost:8080/music/search?q=周杰伦&amp;amp;type=song&amp;amp;sources=qq&amp;amp;sources=netease&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;播放器控制的原理是：页面自己维持一条 SSE 长连接订阅服务端事件，AI 把命令 POST 到服务端，服务端推给在线页面执行，页面再把真实播放状态回传。所以助手读到的 &lt;code&gt;playing&lt;/code&gt;、&lt;code&gt;position&lt;/code&gt;、&lt;code&gt;current&lt;/code&gt; 都是页面当下的真实状态，不是猜的。典型流程是「帮我放一首 ClariS 的歌」：先调搜索接口找歌，再调点播接口播放，最后轮询状态确认已经在放：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 看当前有哪些播放器在线、在放什么
curl &quot;http://localhost:8080/music/api/ai/player/state&quot;

# 2. 直接点播（给 id + source；或只给 query 让服务端自己搜第一首）
curl -X POST &quot;http://localhost:8080/music/api/ai/player/play&quot; \
  -H &quot;Content-Type: application/json&quot; \
  -H &quot;X-Requested-With: XMLHttpRequest&quot; \
  -d &apos;{&quot;id&quot;:&quot;1958384591&quot;,&quot;source&quot;:&quot;netease&quot;,&quot;name&quot;:&quot;ALIVE&quot;,&quot;artist&quot;:&quot;ClariS&quot;}&apos;

# 3. 播放控制（暂停）
curl -X POST &quot;http://localhost:8080/music/api/ai/player/command&quot; \
  -H &quot;Content-Type: application/json&quot; \
  -H &quot;X-Requested-With: XMLHttpRequest&quot; \
  -d &apos;{&quot;action&quot;:&quot;pause&quot;}&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;控制动作支持 &lt;code&gt;play&lt;/code&gt;、&lt;code&gt;pause&lt;/code&gt;、&lt;code&gt;toggle&lt;/code&gt;、&lt;code&gt;stop&lt;/code&gt;、&lt;code&gt;next&lt;/code&gt;、&lt;code&gt;previous&lt;/code&gt;、&lt;code&gt;seek&lt;/code&gt;、&lt;code&gt;volume&lt;/code&gt; 和 &lt;code&gt;rate&lt;/code&gt;。多设备场景也考虑到了：每个打开的页面是一个独立客户端，连接时用 &lt;code&gt;client_id&lt;/code&gt; 声明身份，命令带上 &lt;code&gt;client_id&lt;/code&gt; 就只投给那一台，各控各的、绝不串台；多台在线又不带 &lt;code&gt;client_id&lt;/code&gt; 时接口返回 &lt;code&gt;409 ambiguous_client&lt;/code&gt; 并给出候选列表，宁可报错也不让所有页面一起切歌——这个克制很对。没有播放器在线时返回 &lt;code&gt;409 player_not_connected&lt;/code&gt;，页面关掉后状态保留 10 分钟供查询。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;这套接口的意义在于：音乐服务第一次有了「可被助手直接调用」的标准姿势，点歌从点鼠标变成了说句话。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;h2&gt;安全：这个服务不要裸奔在公网上&lt;/h2&gt;
&lt;p&gt;:::warning
AI 控制接口默认无鉴权，仅靠 &lt;code&gt;X-Requested-With&lt;/code&gt; 请求头做 CSRF 防护，这只防得住浏览器的跨站请求，防不住任何能直接发 HTTP 请求的人。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把 go-music-dl 直接暴露到公网。&amp;lt;/span&amp;gt;自己远程使用时，走 SSH 隧道，或者把它放在带鉴权的反向代理后面；Web 端改设置需要管理员账号，但播放器控制接口并不在账号体系内，别拿前者给后者壮胆。
:::&lt;/p&gt;
&lt;p&gt;同样的道理适用于整个服务：它最适合的部署位置是内网、自己的可信网络，或者鉴权网关之后。自建服务的第一课永远是先想清楚谁能访问，再谈功能。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：Docker 起来了，但找不到 Web setup token，怎么建管理员？&lt;/strong&gt;
A：token 只在首次启动的日志里打印。用 &lt;code&gt;docker compose logs | grep -i &quot;setup token&quot;&lt;/code&gt; 翻出来；如果日志已被刷掉，先停服务备份好 &lt;code&gt;./data&lt;/code&gt; 再排查，不要急着删数据目录重来，那等于把配置和下载记录一起清零。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：能搜到歌，但某些歌点下载没反应或失败？&lt;/strong&gt;
A：先分清是全平台失败还是单个平台失败。部分平台的下载要求有效登录状态（例如 QQ 下载需要有效 Cookie），去设置页扫码登录或补上 Cookie 再试；单个源失败时用换源功能切到其他平台的同一首歌，往往当场解决。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：汽水音乐扫不了码怎么办？&lt;/strong&gt;
A：汽水暂不支持扫码登录，在设置页按附带的步骤手动抓取并填写 Cookie 即可。网易云、QQ、酷狗、Bilibili 四家是支持扫码的。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：下载的歌没有封面和歌词，是 bug 吗？&lt;/strong&gt;
A：大概率是环境里没有 &lt;code&gt;ffmpeg&lt;/code&gt;。内嵌封面歌词依赖它，缺失时自动跳过且不报错。Docker 镜像和 Android APK 已内置；二进制或桌面端部署的，装好后用 &lt;code&gt;ffmpeg -version&lt;/code&gt; 验证，并确认设置页里的内嵌开关已打开。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：AI 点播返回 409 player_not_connected？&lt;/strong&gt;
A：说明当前没有打开着的播放页面。控制接口操控的是&lt;strong&gt;已打开的页面&lt;/strong&gt;，先在浏览器里打开 Web 播放器（后台标签页也可以，但浏览器会节流定时器，进度上报会变慢），再发命令。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：家里两台设备都开着页面，AI 切歌切错台了？&lt;/strong&gt;
A：多客户端必须带 &lt;code&gt;client_id&lt;/code&gt; 定向。不带时多台在线会返回 &lt;code&gt;409 ambiguous_client&lt;/code&gt; 和候选列表，照着列表选定目标再发；用 &lt;code&gt;GET /state?client_id=xxx&lt;/code&gt; 可以精确读某一台的状态。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：升级之后 AI 定向控制失灵了？&lt;/strong&gt;
A：先对页面按 &lt;code&gt;Ctrl+F5&lt;/code&gt; 硬刷新。前端脚本是编译进二进制的，升级后旧页面还拿着老脚本，&lt;code&gt;client_id&lt;/code&gt; 定向这类新能力用不了，刷新即可。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：Android 上下载的歌在别的播放器里找不到？&lt;/strong&gt;
A：默认下载目录不在系统音乐目录里。进设置把本地下载目录改成 &lt;code&gt;/sdcard/Music&lt;/code&gt;，之后下载的文件会直接进系统音乐目录。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：本地音乐库扫不进新放进去的文件？&lt;/strong&gt;
A：确认文件放在扫描目录下（默认 &lt;code&gt;data/downloads&lt;/code&gt;），格式在支持列表内；索引有缓存和后台刷新机制，稍等片刻或重启服务触发重新扫描。元数据残缺的文件会用 &lt;code&gt;ffprobe&lt;/code&gt; 补全，补不全的会以文件名示人，先检查文件本身是否完好。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;go-music-dl 把一件高频小事做成了完整的自建服务：一头聚合十多个平台的搜索与下载，一头管好本地曲库的整理与同步，中间还留了一套能让 AI 助手直接操控播放器的接口。部署上 Docker 一行命令、桌面端解压即用、Android 一个 APK，门槛压得很低。&lt;/p&gt;
&lt;p&gt;适合部署的人很明确：歌单散落在好几个平台、想把「搜歌—下载—归档—播放」收进自己手里的人。按本篇的顺序走——Docker 起服务、建管理员、按需扫码登录拿回自己的歌单、下载目录与 WebDAV 打通、最后确认服务没有裸奔在公网——一个属于你自己的音乐入口就立起来了。&lt;/p&gt;
</content:encoded></item><item><title>Nextcloud ＋ OnlyOffice：私有云盘与在线文档协作</title><link>https://www.anexns.cloudns.org/posts/selfhost-nextcloud-onlyoffice/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-nextcloud-onlyoffice/</guid><description>用 Docker Compose 部署 Nextcloud ＋ PostgreSQL ＋ Redis ＋ OnlyOffice 四件套，打造能在线编辑 Office 文档的私有云盘，含性能调优、内网回连大坑、客户端同步与备份要点。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说定位：这次要的不是「能存文件」，是「能干活」&lt;/h2&gt;
&lt;p&gt;自建文件服务有很多种活法。本系列前面写过 &lt;a href=&quot;/posts/selfhost-cloudreve/&quot;&gt;Cloudreve&lt;/a&gt;，它的定位是轻量网盘：部署简单、分享链接好用、给博客和团队当文件中转站非常称职。但如果你想要的不只是存取文件，还包括这些事：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;桌面文件夹和服务器实时双向同步，换台电脑打开就是同一份工作区；&lt;/li&gt;
&lt;li&gt;Word、Excel、PPT 直接在浏览器里打开编辑，还能多人同时改一份文档；&lt;/li&gt;
&lt;li&gt;日历、通讯录、任务、笔记都收进自己的服务器，不再散落各家云服务；&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;那要的就是 Nextcloud 这一档了。它是一个完整的私有云协作平台，网盘只是其中一块。而在线编辑 Office 文档这块拼图，靠它自带的简易编辑器远远不够，必须外挂一套真正的文档引擎——这就是 OnlyOffice Document Server 的位置。&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;strong&gt;四件套架构总览 → Docker Compose 一次编排到位 → 初始化与可信域名 → 性能调优把卡顿消掉 → OnlyOffice 集成与内网回连大坑 → 客户端同步 → 外部存储概念 → 备份要点&lt;/strong&gt;。全篇用 Docker Compose 部署，数据库选 PostgreSQL（选型理由和参数细节可参考 &lt;a href=&quot;/posts/postgresql-install-config/&quot;&gt;PostgreSQL 安装与配置&lt;/a&gt;）。&lt;/p&gt;
&lt;h2&gt;架构总览：四个容器，各管一段&lt;/h2&gt;
&lt;p&gt;先把四件套的分工说清楚，后面所有配置都是在给这张图填细节：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;组件&lt;/th&gt;
&lt;th&gt;角色&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Nextcloud（app）&lt;/td&gt;
&lt;td&gt;平台本体&lt;/td&gt;
&lt;td&gt;Web 界面、文件管理、用户与权限、应用生态，对外提供服务&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;PostgreSQL&lt;/td&gt;
&lt;td&gt;数据库&lt;/td&gt;
&lt;td&gt;存用户、文件索引、分享记录等全部元数据，不存文件本体&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Redis&lt;/td&gt;
&lt;td&gt;缓存与文件锁&lt;/td&gt;
&lt;td&gt;内存缓存 + 事务文件锁，缺了它 Nextcloud 又慢又容易出冲突&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;OnlyOffice Document Server&lt;/td&gt;
&lt;td&gt;文档引擎&lt;/td&gt;
&lt;td&gt;负责 docx/xlsx/pptx 的渲染与协同编辑，通过连接器与 Nextcloud 对接&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;cron（app 镜像复用）&lt;/td&gt;
&lt;td&gt;后台任务&lt;/td&gt;
&lt;td&gt;定时跑预览生成、垃圾回收、索引维护等计划任务&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;文件本体躺在宿主机目录（或数据卷）里，数据库只记元数据，这是理解后面备份章节的关键：&lt;strong&gt;备份 = 数据库 + data 目录 + config 配置，三样缺一不可&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;四件套的核心关系一句话：Nextcloud 管人和文件，PostgreSQL 管账本，Redis 管速度，OnlyOffice 管文档编辑。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;资源预估先交代：Nextcloud 本体加 PostgreSQL、Redis 大约 1.5 GB 内存能跑，OnlyOffice Document Server 自己就要吃 2 GB 左右（它内置了转换服务和消息队列，是个重量级选手）。整机建议 4 GB 内存起步，磁盘按你打算存多少文件另算。内存不够时 OnlyOffice 打开文档会明显迟钝，这不是调优能救的。&lt;/p&gt;
&lt;h2&gt;完整编排：docker-compose.yml&lt;/h2&gt;
&lt;p&gt;部署目录约定为 &lt;code&gt;/opt/nextcloud&lt;/code&gt;，先把骨架搭起来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p /opt/nextcloud/{data,db}
cd /opt/nextcloud
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;.env&lt;/code&gt; 文件放所有密码和域名，Compose 自动读取：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cat &amp;gt; .env &amp;lt;&amp;lt; &apos;EOF&apos;
DOMAIN=cloud.example.com
POSTGRES_PASSWORD=换成你的强密码
REDIS_PASSWORD=换成你的强密码
OO_JWT_SECRET=换成一串足够长的随机字符串
EOF
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;docker-compose.yml&lt;/code&gt; 全文如下，这是本篇的核心资产，后面几节都是在解释和调优它：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  db:
    image: postgres:16-alpine
    container_name: nc-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: nextcloud
      POSTGRES_USER: nextcloud
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./db:/var/lib/postgresql/data
    healthcheck:
      test: [&quot;CMD-SHELL&quot;, &quot;pg_isready -U nextcloud&quot;]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: nc-redis
    restart: unless-stopped
    command: redis-server --requirepass ${REDIS_PASSWORD} --maxmemory 256mb --maxmemory-policy allkeys-lru
    volumes:
      - redis_data:/data

  app:
    image: nextcloud:30-apache
    container_name: nc-app
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    environment:
      POSTGRES_HOST: db
      POSTGRES_DB: nextcloud
      POSTGRES_USER: nextcloud
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      REDIS_HOST: redis
      REDIS_HOST_PASSWORD: ${REDIS_PASSWORD}
      NEXTCLOUD_TRUSTED_DOMAINS: ${DOMAIN}
      OVERWRITEPROTOCOL: https
      TZ: Asia/Shanghai
    volumes:
      - ./data:/var/www/html/data
      - app_html:/var/www/html
    ports:
      - &quot;127.0.0.1:8080:80&quot;

  cron:
    image: nextcloud:30-apache
    container_name: nc-cron
    restart: unless-stopped
    depends_on:
      - app
    entrypoint: /cron.sh
    volumes:
      - ./data:/var/www/html/data
      - app_html:/var/www/html

  onlyoffice:
    image: onlyoffice/documentserver:latest
    container_name: nc-onlyoffice
    restart: unless-stopped
    environment:
      JWT_SECRET: ${OO_JWT_SECRET}
      JWT_ENABLED: &quot;true&quot;
    volumes:
      - oo_data:/var/www/onlyoffice/Data
    ports:
      - &quot;127.0.0.1:8081:80&quot;

volumes:
  app_html:
  redis_data:
  oo_data:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个关键点逐个说：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;端口只绑 127.0.0.1&lt;/strong&gt;。两个 Web 服务都只监听本机回环，对外统一走反向代理（自建服务系列的标准入口做法见 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager 统一入口&lt;/a&gt;），由它负责域名和 HTTPS 证书。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;数据库和 Redis 完全不映射端口&lt;/strong&gt;。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不要图省事把 PostgreSQL 的 5432 端口映射到公网&amp;lt;/span&amp;gt;，数据库裸奔在公网上被扫描爆破是迟早的事，它们只需要被 app 容器按服务名访问。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;app 和 cron 共用同一套卷&lt;/strong&gt;。cron 容器跑的是官方镜像自带的 &lt;code&gt;/cron.sh&lt;/code&gt;，每 5 分钟触发一次后台任务，和 app 共享代码卷与 data 目录，这是官方推荐的独立 cron 方案，比在 Web 进程里顺带跑 AJAX 后台任务可靠得多。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;data 目录用宿主机目录挂载&lt;/strong&gt;而不是命名卷，纯粹为了备份和迁移时看得见摸得着，后面备份一节会用到。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;启动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose pull
docker compose up -d
docker compose ps
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;等 &lt;code&gt;nc-db&lt;/code&gt; 变为 healthy、其余容器都 running 后，在反向代理里加两条：&lt;code&gt;cloud.example.com&lt;/code&gt; 指向 &lt;code&gt;127.0.0.1:8080&lt;/code&gt;，再给 OnlyOffice 单独一个子域名 &lt;code&gt;office.example.com&lt;/code&gt; 指向 &lt;code&gt;127.0.0.1:8081&lt;/code&gt;，两条都申请好 HTTPS 证书。为什么 OnlyOffice 必须独立域名，后面集成一节细说。&lt;/p&gt;
&lt;h2&gt;初始化与可信域名&lt;/h2&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;https://cloud.example.com&lt;/code&gt;，首次访问是创建管理员账号的页面。注意：因为 Compose 里已经通过环境变量把数据库连接参数喂给了安装向导，这里&lt;strong&gt;不要&lt;/strong&gt;在页面上再选 SQLite，老老实实确认 PostgreSQL 参数无误，设好管理员用户名和密码，点安装。&lt;/p&gt;
&lt;p&gt;装完先做三件事，都在服务器上用 &lt;code&gt;occ&lt;/code&gt; 命令完成（&lt;code&gt;occ&lt;/code&gt; 是 Nextcloud 的官方命令行管理工具，容器里执行要带上 Web 用户身份）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 1. 确认可信域名（环境变量已注入，再核对一遍）
docker exec -u www-data nc-app php occ config:system:get trusted_domains

# 2. 补一条本机回环，方便服务器内部自检
docker exec -u www-data nc-app php occ config:system:set trusted_domains 2 --value=127.0.0.1

# 3. 设置默认语言与时区等区域项
docker exec -u www-data nc-app php occ config:system:set default_language --value=zh_CN
docker exec -u www-data nc-app php occ config:system:set default_locale --value=zh_Hans_CN
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;可信域名（trusted_domains）是 Nextcloud 的一道门禁：不在名单里的 Host 头访问会被直接拒绝并提示「通过不受信任的域名访问」。反代场景下如果忘了把正式域名写进去，就会出现网站明明能打开却被拦在门外的情况，排查方向就是这条配置。&lt;/p&gt;
&lt;p&gt;:::warning
&lt;strong&gt;关于覆盖协议与代理的提醒&lt;/strong&gt;：Nextcloud 在反向代理后面时，必须知道自己对外的真实协议是 HTTPS，否则生成的分享链接、客户端发现地址会全部带着 http 和内网端口。Compose 里已经设了 &lt;code&gt;OVERWRITEPROTOCOL: https&lt;/code&gt;；如果你改用手工配置，等价命令是 &lt;code&gt;occ config:system:set overwriteprotocol --value=https&lt;/code&gt;，改完记得验证分享链接是否正确。
:::&lt;/p&gt;
&lt;h2&gt;性能调优：把「能用」调成「不卡」&lt;/h2&gt;
&lt;p&gt;Nextcloud 原生状态有几个广为人知的卡点：打开文件夹要等、缩略图现生成现等、后台任务靠访问触发。这节逐个消掉。&lt;/p&gt;
&lt;h3&gt;Redis 缓存与文件锁&lt;/h3&gt;
&lt;p&gt;Compose 的环境变量已经让安装向导自动写入了 Redis 配置，验证一下：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec -u www-data nc-app php occ config:system:get memcache.local
docker exec -u www-data nc-app php occ config:system:get memcache.locking
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两个值都应该是 &lt;code&gt;\OC\Memcache\Redis&lt;/code&gt;。前者是本地内存缓存，后者是事务文件锁——多人或多客户端同时操作同一批文件时，没有文件锁很容易出现冲突副本和莫名报错。如果输出为空，说明 Redis 没接上，手工补齐：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec -u www-data nc-app php occ config:system:set memcache.local --value=&apos;\OC\Memcache\Redis&apos;
docker exec -u www-data nc-app php occ config:system:set memcache.distributed --value=&apos;\OC\Memcache\Redis&apos;
docker exec -u www-data nc-app php occ config:system:set memcache.locking --value=&apos;\OC\Memcache\Redis&apos;
docker exec -u www-data nc-app php occ config:system:set redis host --value=redis
docker exec -u www-data nc-app php occ config:system:set redis port --value=6379
docker exec -u www-data nc-app php occ config:system:set redis password --value=&apos;你的Redis密码&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;PHP 与 OPcache&lt;/h3&gt;
&lt;p&gt;Apache 版镜像的 PHP 配置基本够用，重点确认 OPcache 已启用并给足内存。在 app 容器里挂一个自定义 ini 即可，新建 &lt;code&gt;opcache.ini&lt;/code&gt; 通过卷挂进 &lt;code&gt;/usr/local/etc/php/conf.d/&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=10000
opcache.revalidate_freq=60
apc.enable_cli=1
memory_limit=1024M
upload_max_filesize=16G
post_max_size=16G
max_execution_time=3600
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;最后三行是给大文件上传留的余量，下一节排障里的 413 问题有一半要在这里解决（另一半在反代那边）。&lt;/p&gt;
&lt;h3&gt;后台任务切到 Cron 模式&lt;/h3&gt;
&lt;p&gt;进入管理设置 → 基本设置 → 后台任务，选 &lt;strong&gt;Cron&lt;/strong&gt;。我们已经有独立 cron 容器每 5 分钟调用一次，这里选错成 AJAX 的话，等于白养了一个容器还继续卡。选好后页面会显示上次执行时间，应该是 5 分钟以内的新鲜时间。&lt;/p&gt;
&lt;h3&gt;预览图预生成&lt;/h3&gt;
&lt;p&gt;文件夹里照片和视频的缩略图默认是首次打开时现算的，慢且占 CPU。装 Preview Generator 应用后让 cron 在后台提前算好：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 在应用商店装 Preview Generator，或命令行直接装
docker exec -u www-data nc-app php occ app:install previewgenerator

# 先全量生成一次（文件多时耗时较久，挑空闲时段跑）
docker exec -u www-data nc-app php occ preview:generate-all

# 限制预览图尺寸，别让它生成原图级预览吃爆磁盘
docker exec -u www-data nc-app php occ config:app:set previewgenerator squareSizes --value=&quot;32 256&quot;
docker exec -u www-data nc-app php occ config:app:set previewgenerator widthSizes --value=&quot;256 384&quot;
docker exec -u www-data nc-app php occ config:app:set previewgenerator heightSizes --value=&quot;256&quot;
docker exec -u www-data nc-app php occ config:system:set preview_max_x --value=2048
docker exec -u www-data nc-app php occ config:system:set preview_max_y --value=2048
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;做完这四步，再把管理设置页的「安全及设置警告」逐条清掉（排障一节有清单），Nextcloud 的体感会从「自建的凑合用」变成「这不就是个正经云盘」。&lt;/p&gt;
&lt;h2&gt;OnlyOffice 集成：成败全在「回连地址」&lt;/h2&gt;
&lt;h3&gt;装连接器、填三要素&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;以管理员登录 Nextcloud，右上角头像 → 应用，搜索 &lt;strong&gt;ONLYOFFICE&lt;/strong&gt;，下载并启用官方连接器应用。&lt;/li&gt;
&lt;li&gt;进入管理设置 → ONLYOFFICE，填三样东西：
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Document Server 地址&lt;/strong&gt;：&lt;code&gt;https://office.example.com/&lt;/code&gt;（用户浏览器要访问的地址，必须是公网可达的 HTTPS 地址）；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;密钥（JWT Secret）&lt;/strong&gt;：就是 &lt;code&gt;.env&lt;/code&gt; 里给 OnlyOffice 容器设置的 &lt;code&gt;OO_JWT_SECRET&lt;/code&gt;，两边必须一字不差；&lt;/li&gt;
&lt;li&gt;勾选「在新标签页打开编辑器」与否按个人喜好，下面的高级设置先展开，有大坑等着。&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;点保存。顺利的话会提示连接成功，打开任意 docx 文件就直接进编辑器了。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;为什么 Document Server 要独立子域名而不是挂在子路径下：它的编辑器页面、转换服务、静态资源都按根路径设计，塞进子路径会引出一串资源加载和 WebSocket 的问题，独立子域名是官方和社区的共识做法，别在这上面省一个域名。&lt;/p&gt;
&lt;h3&gt;大坑：内网回连地址&lt;/h3&gt;
&lt;p&gt;这是整个集成里最容易翻车、也最少有人一次讲透的一环。先理解编辑一份文档时发生了什么：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;你的浏览器从 &lt;code&gt;office.example.com&lt;/code&gt; 加载编辑器界面；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;OnlyOffice 服务器&lt;/strong&gt;需要回头到 Nextcloud 把文档文件&lt;strong&gt;下载&lt;/strong&gt;下来；&lt;/li&gt;
&lt;li&gt;你编辑完，&lt;strong&gt;OnlyOffice 服务器&lt;/strong&gt;再把新文件&lt;strong&gt;回传&lt;/strong&gt;给 Nextcloud 保存。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;第 2、3 步是服务器对服务器的访问。问题来了：OnlyOffice 容器要访问的 Nextcloud 地址，就是连接器里填的那个公网地址吗？不是——连接器会把 Nextcloud 的地址按请求来源拼出来发给 OnlyOffice。在纯公网部署里这能工作，但在我们这种「容器内网 + 反代对外」的结构里，OnlyOffice 容器拿着 &lt;code&gt;https://cloud.example.com&lt;/code&gt; 去回连，要先绕出公网、过 DNS、再被反代送回来一圈，经常卡在 DNS 解析不到、回环被拒或者证书校验失败上，表现就是&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;编辑器一直转圈，或者文档能打开但保存时报错&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;解法是连接器高级设置里的两个「内部地址」，让两台服务器在内网直连，把浏览器那条公网链路和服务器间链路分开：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;设置项&lt;/th&gt;
&lt;th&gt;填什么&lt;/th&gt;
&lt;th&gt;谁用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Document Server 地址&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://office.example.com/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;浏览器加载编辑器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Document Server 内部请求地址&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http://nc-onlyoffice/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Nextcloud 向 OnlyOffice 发起请求时走内网&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Nextcloud 内部请求地址&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http://nc-app/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;OnlyOffice 回连 Nextcloud 下载/回传文件时走内网&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;填容器名能通的前提是两个容器在同一个 Docker 网络里——用同一份 Compose 编排天然满足（默认网络互通，按服务名和容器名都能解析）。注意内部地址用 http 即可，内网链路不经过公网，没必要再套一层证书。&lt;/p&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;OnlyOffice 集成的核心结论：浏览器走公网域名，服务器互访走容器内网地址，两条路分开，九成的转圈和保存失败都会消失。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;验证内网连通性不用靠猜，进容器实测：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# OnlyOffice 容器能否摸到 Nextcloud
docker exec nc-onlyoffice curl -sI http://nc-app/status.php | head -3

# Nextcloud 容器能否摸到 OnlyOffice 的健康检查
docker exec nc-app curl -s http://nc-onlyoffice/healthcheck
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第二条返回 &lt;code&gt;true&lt;/code&gt; 才算通。另外要注意，JWT 密钥两边不一致时编辑器会直接报权限错误且日志里不会明说，改过 &lt;code&gt;.env&lt;/code&gt; 后记得 OnlyOffice 容器要重建、连接器设置页要重新保存一次密钥。&lt;/p&gt;
&lt;h2&gt;客户端同步：让文件自己流动&lt;/h2&gt;
&lt;p&gt;服务端跑通后，把日常设备接进来才算落地：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;桌面端&lt;/strong&gt;：官网下载 Nextcloud Desktop（Windows/macOS/Linux 都有），登录时填服务器地址 &lt;code&gt;https://cloud.example.com&lt;/code&gt;，走浏览器授权流程。可以选「虚拟文件」模式（文件按需下载，本地只占索引）或整文件夹实同步，工作区建议实同步，归档区用虚拟文件省磁盘。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;手机端&lt;/strong&gt;：Nextcloud 官方 App（Android/iOS），登录后打开「自动上传」，把相册目录映射到服务器的 Photos 文件夹，拍照即备份。注意在系统里给它放行后台运行和流量权限，否则自动上传会断断续续。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;WebDAV&lt;/strong&gt;：任何支持 WebDAV 的工具（文档扫描、笔记软件等）都能直连，地址是 &lt;code&gt;https://cloud.example.com/remote.php/dav/files/你的用户名/&lt;/code&gt;，密码建议在个人设置 → 安全里生成&lt;strong&gt;应用专用密码&lt;/strong&gt;，不要用主密码到处填。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;外部存储：把别的盘也挂进来&lt;/h2&gt;
&lt;p&gt;Nextcloud 支持把外部存储当作一个文件夹挂进网盘视图：本地其他目录、S3 兼容对象存储、另一台机器的 SMB/NFS 共享等。启用方式：应用里启用 &lt;strong&gt;External storage support&lt;/strong&gt;，管理设置 → 外部存储里添加。&lt;/p&gt;
&lt;p&gt;概念上要分清两种用法：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;主存储&lt;/strong&gt;：整个实例的 data 目录直接放对象存储（&lt;code&gt;objectstore&lt;/code&gt; 配置），适合文件量巨大、要横向扩容的场景，但元数据与小文件性能要实测，个人部署一般没必要；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;挂载式外部存储&lt;/strong&gt;：主 data 还是本地盘，只把某个大目录（比如 NAS 上的影音库）挂进来浏览下载，编辑和协同仍走本地文件，这是个人场景最实用的形态。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;挂载进来的目录权限、分享规则跟随 Nextcloud 的用户体系，但要注意：外部目录里被别的程序直接改动的文件，Nextcloud 的索引不会实时感知，需要手动触发扫描：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec -u www-data nc-app php occ files:scan --all
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;备份要点&lt;/h2&gt;
&lt;p&gt;Nextcloud 的备份对象在架构一节已经点明：&lt;strong&gt;数据库 + data 目录 + app 的 config&lt;/strong&gt;。其中 config.php 里存着实例的密钥盐（passwordsalt）和实例 ID，丢了它，数据库和文件都在也拼不回原样。完整的方法论（一致性快照、异地留存、恢复演练）在 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移&lt;/a&gt; 里有系统展开，这里只列 Nextcloud 特有的动作顺序：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/nextcloud

# 1. 进维护模式，冻结写入，保证数据库与文件的一致性
docker exec -u www-data nc-app php occ maintenance:mode --on

# 2. 导出数据库
docker exec nc-db pg_dump -U nextcloud nextcloud &amp;gt; backup-$(date +%F).sql

# 3. 打包 data 目录与配置（app_html 卷里的 config 也要带走）
tar czf nc-files-$(date +%F).tar.gz data
docker run --rm -v nextcloud_app_html:/html -v $PWD:/backup alpine \
  tar czf /backup/nc-config-$(date +%F).tar.gz -C /html config

# 4. 退出维护模式
docker exec -u www-data nc-app php occ maintenance:mode --off
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;维护模式这步最容易图省事跳过，但&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不进维护模式直接拷 data，拷到一半正好有人上传文件，备份里的数据库记录和文件就会对不上&amp;lt;/span&amp;gt;，恢复时轻则丢文件，重则索引错乱。备份做完把三件套同步一份到另一台机器或对象存储，本机留一份不算备份。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;h3&gt;上传大文件报 413&lt;/h3&gt;
&lt;p&gt;413（Request Entity Too Large）是请求体超过了某一层的上限，链路上有三层都可能拦，按顺序查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;反向代理层&lt;/strong&gt;：最常见。Nginx 系反代默认 &lt;code&gt;client_max_body_size&lt;/code&gt; 只有 1 MB，在站点配置里调大，例如 &lt;code&gt;client_max_body_size 16G;&lt;/code&gt;，改完重载。用 NPM 的话在站点的 Advanced 里加这一行。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;PHP 层&lt;/strong&gt;：前面 opcache.ini 里已经把 &lt;code&gt;upload_max_filesize&lt;/code&gt; 和 &lt;code&gt;post_max_size&lt;/code&gt; 设为 16G，没设的话在这一层被拦。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Nextcloud 本身&lt;/strong&gt;：Web 端上传走分片机制，一般不是瓶颈；桌面客户端同步大文件失败先看前两层。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;「安全及设置警告」逐条消&lt;/h3&gt;
&lt;p&gt;管理设置页顶部的警告清单是 Nextcloud 的体检报告，新装完通常有四五条，逐条对应处理：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;「未配置内存缓存」/「没有默认的电话区域」等&lt;/strong&gt;：前者说明 Redis 没接上，按调优一节补 &lt;code&gt;memcache.local&lt;/code&gt; 配置；电话区域顺手补上 &lt;code&gt;occ config:system:set default_phone_region --value=CN&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;「数据库缺少一些索引」&lt;/strong&gt;：一条命令补齐：&lt;code&gt;docker exec -u www-data nc-app php occ db:add-missing-indices&lt;/code&gt;，大表会跑一会儿，低峰期执行。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;「数据库缺少一些可选列 / 主键」&lt;/strong&gt;：依次跑 &lt;code&gt;occ db:add-missing-columns&lt;/code&gt;、&lt;code&gt;occ db:add-missing-primary-keys&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;「未设置或无法检查 HSTS 等 HTTP 响应头」&lt;/strong&gt;：这是反代的活，在反代站点上补齐 Strict-Transport-Security 等安全响应头，Nextcloud 自己不发这些头。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;「后台任务上次执行在很久以前」&lt;/strong&gt;：cron 容器没跑起来或模式选错，回调优一节检查 cron 容器日志与后台任务模式。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;「PHP 的 OPcache 未正确配置」&lt;/strong&gt;：按调优一节的 ini 挂载后重启 app 容器。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;目标是让这个页面显示「一切正常」。这不是强迫症：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;长期挂着警告的实例，往往在某次大版本升级时因为缺失索引或缓存未配置而直接翻车&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h3&gt;OnlyOffice 打开文档一直转圈&lt;/h3&gt;
&lt;p&gt;按这个顺序排查，命中率从高到低：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;内网回连不通&lt;/strong&gt;：回集成一节，用两条 curl 实测容器互访，这是第一嫌疑。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;JWT 密钥不一致&lt;/strong&gt;：连接器设置页与 OnlyOffice 容器环境变量逐字对比，改过要重建容器并重新保存设置。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Document Server 地址协议不对&lt;/strong&gt;：页面是 HTTPS、编辑器填了 http 地址会被浏览器拦截混合内容，公网地址必须是 HTTPS。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;OnlyOffice 容器资源不足&lt;/strong&gt;：它启动要预热转换服务，内存紧张时 healthcheck 长时间不返回 true，先 &lt;code&gt;docker logs nc-onlyoffice&lt;/code&gt; 看有没有反复重启。&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;文档能打开但保存失败 / 改动丢失&lt;/h3&gt;
&lt;p&gt;编辑器有强制保存机制，关页面太快时最后几秒的改动靠回调落盘。先查 OnlyOffice 回连 Nextcloud 的那条内网链路（同上），再在连接器高级设置里确认没有把回调地址改错；也可以在管理设置里开启「保存后强制组装」相关的连接器选项做对照测试。多人协同同时先确认 Redis 文件锁已生效（&lt;code&gt;memcache.locking&lt;/code&gt; 为 Redis），没有文件锁的协同编辑出问题只是时间问题。&lt;/p&gt;
&lt;h3&gt;客户端登录时报「不受信任的域名」&lt;/h3&gt;
&lt;p&gt;手机/桌面客户端填的地址 Host 不在 trusted_domains 名单里。用命令查看现有名单并补上正式域名，注意名单是带下标的数组，新增要顺延下标：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec -u www-data nc-app php occ config:system:get trusted_domains
docker exec -u www-data nc-app php occ config:system:set trusted_domains 3 --value=cloud.example.com
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Nextcloud ＋ PostgreSQL ＋ Redis ＋ OnlyOffice 四件套，是自建文件服务里「能干活」的那一档：同步、分享、在线协同编辑一条龙；&lt;/li&gt;
&lt;li&gt;部署本身不难，难的是三处细节：Redis 缓存与文件锁要接实、后台任务要交给独立 cron、OnlyOffice 的服务器间回连要走内网地址；&lt;/li&gt;
&lt;li&gt;安全及设置警告清零、备份三件套（数据库＋data＋config）定期留异地副本，这套私有云就能长期稳住。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;和 &lt;a href=&quot;/posts/selfhost-cloudreve/&quot;&gt;Cloudreve&lt;/a&gt; 的分工可以这样记：轻量分享用 Cloudreve，正经当工作云盘用 Nextcloud，两者并不冲突，完全可以一台机器上各跑一套，按场景分流。&lt;/p&gt;
</content:encoded></item><item><title>Nginx Proxy Manager：所有自建服务的统一入口</title><link>https://www.anexns.cloudns.org/posts/selfhost-nginx-proxy-manager/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-nginx-proxy-manager/</guid><description>十几个自建服务难道要记十几个端口？这篇用 Docker 部署 Nginx Proxy Manager，给每个服务分配域名、自动签发 HTTPS 证书，让全屋服务只从 80/443 一个大门进出。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：端口越开越多，管理越来越乱&lt;/h2&gt;
&lt;p&gt;自建服务装到第三个，你就会撞上这堵墙：监控在 &lt;code&gt;IP:25774&lt;/code&gt;、状态页在 &lt;code&gt;IP:3001&lt;/code&gt;、云盘在 &lt;code&gt;IP:5212&lt;/code&gt;……每个服务一个端口，全要记、全暴露在公网上、全都没有 HTTPS。浏览器对着密码库的登录页弹出「不安全」警告时，那种感觉尤其糟糕。&lt;/p&gt;
&lt;p&gt;上一篇 &lt;a href=&quot;/posts/selfhost-getting-started/&quot;&gt;自建服务入门：从一台 VPS 开始的完整规划&lt;/a&gt; 定下的规矩是：整台机器只开 80/443，所有 Web 服务通过反向代理按域名分发。实现这个规矩的工具就是本篇主角 Nginx Proxy Manager（下文简称 NPM）：它把 Nginx 的反向代理和 Let&apos;s Encrypt 证书管理包进了一个图形化界面，添加一个服务入口就是填几个框、点几下鼠标，不用手写 Nginx 配置，更不用手动续证书。&lt;/p&gt;
&lt;h2&gt;选型对比：为什么入门推荐 NPM&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方案&lt;/th&gt;
&lt;th&gt;上手难度&lt;/th&gt;
&lt;th&gt;证书管理&lt;/th&gt;
&lt;th&gt;适合人群&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;手写 Nginx 配置&lt;/td&gt;
&lt;td&gt;高，要懂配置语法&lt;/td&gt;
&lt;td&gt;certbot 手动或脚本续期&lt;/td&gt;
&lt;td&gt;有运维经验、需求复杂&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Caddy&lt;/td&gt;
&lt;td&gt;低，配置文件极简&lt;/td&gt;
&lt;td&gt;全自动&lt;/td&gt;
&lt;td&gt;喜欢配置文件管理的人&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Nginx Proxy Manager&lt;/td&gt;
&lt;td&gt;最低，全图形界面&lt;/td&gt;
&lt;td&gt;界面一键申请、自动续期&lt;/td&gt;
&lt;td&gt;自建入门、多服务统一管理&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;三者没有高下之分，本站 Docker 系列有 &lt;a href=&quot;/posts/docker-caddy-https/&quot;&gt;用 Caddy 给容器服务自动配 HTTPS&lt;/a&gt; 的完整教程，喜欢 Caddy 的可以走那条路线。本系列选 NPM 做统一入口，看中的是它的 Access List（访问控制列表）和可视化管理——服务多了之后，在一个面板里看清所有转发规则，价值很大。&lt;/p&gt;
&lt;h2&gt;部署：一份 Compose 搞定&lt;/h2&gt;
&lt;p&gt;按系列规范，服务装在 &lt;code&gt;/opt/apps/nginx-proxy-manager/&lt;/code&gt; 下。先把子域名 &lt;code&gt;npm.example.com&lt;/code&gt; 的 A 记录解析到 VPS（管理后台也要走域名加 HTTPS），然后写 Compose：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  npm:
    image: jc21/nginx-proxy-manager:latest
    container_name: nginx-proxy-manager
    restart: unless-stopped
    ports:
      - &quot;80:80&quot;
      - &quot;443:443&quot;
      - &quot;81:81&quot;
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/apps/nginx-proxy-manager
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;端口说明：80 和 443 是对外服务的正门；81 是 NPM 自己的管理后台端口。注意防火墙层面，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;81 端口不要对公网开放&amp;lt;/span&amp;gt;——等下我们会把管理后台也套上 NPM 自己的反代（用域名加 HTTPS 访问），然后把 81 限制为仅本机或干脆只在初始配置时临时放行。数据目录里，&lt;code&gt;/data&lt;/code&gt; 存 NPM 的配置数据库与站点配置，&lt;code&gt;/etc/letsencrypt&lt;/code&gt; 存证书，两者都在备份范围内。&lt;/p&gt;
&lt;p&gt;首次启动后访问 &lt;code&gt;http://你的IP:81&lt;/code&gt;，用默认账号登录：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;邮箱：&lt;code&gt;admin@example.com&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;密码：&lt;code&gt;changeme&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;登录后第一件事就是改邮箱和密码&amp;lt;/span&amp;gt;，默认凭据是公开信息，拖着不改等于大门敞开。改完凭据，在 NPM 里给它自己先建一条转发：新建 Proxy Host，域名填 &lt;code&gt;npm.example.com&lt;/code&gt;，转发到 &lt;code&gt;127.0.0.1&lt;/code&gt; 的 &lt;code&gt;81&lt;/code&gt; 端口，SSL 页签申请新证书并勾选 Force SSL。完成后改用 &lt;code&gt;https://npm.example.com&lt;/code&gt; 访问后台，并到云厂商防火墙/系统防火墙里关掉公网 81。&lt;/p&gt;
&lt;h2&gt;给服务添加入口：Proxy Host 标准流程&lt;/h2&gt;
&lt;p&gt;以后每装一个新服务，入口配置都是同一套动作，以后面要装的监控面板为例：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;DNS 先加好子域名解析，如 &lt;code&gt;status.example.com&lt;/code&gt; → VPS 的 IP。&lt;/li&gt;
&lt;li&gt;NPM 后台 → Proxy Hosts → Add Proxy Host。&lt;/li&gt;
&lt;li&gt;Domain Names 填 &lt;code&gt;status.example.com&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;Scheme 选 &lt;code&gt;http&lt;/code&gt;，Forward Hostname/IP 与 Forward Port 填服务实际监听地址（见下一节）。&lt;/li&gt;
&lt;li&gt;打开 Block Common Exploits；服务是实时类应用（如聊天、日志流）再打开 Websockets Support。&lt;/li&gt;
&lt;li&gt;SSL 页签选 Request a new SSL Certificate，勾选 Force SSL 与 HTTP/2 Support，同意 Let&apos;s Encrypt 条款。&lt;/li&gt;
&lt;li&gt;保存，浏览器访问域名验证。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;证书申请走的是 HTTP 验证，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;申请时 80 端口必须能从公网访问且域名解析已生效&amp;lt;/span&amp;gt;，这两条不满足是证书失败的最常见原因。证书有效期 90 天，NPM 会自动续期，不用操心。&lt;/p&gt;
&lt;h2&gt;转发地址怎么写：三种情形&lt;/h2&gt;
&lt;p&gt;Forward Hostname/IP 填什么，取决于服务和 NPM 的相对位置：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;情形&lt;/th&gt;
&lt;th&gt;填法&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;服务与 NPM 在同一个 Compose/网络&lt;/td&gt;
&lt;td&gt;容器名，如 &lt;code&gt;komari&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Docker 内网 DNS 自动解析，最干净&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;服务在同一台机器、端口映射到宿主机&lt;/td&gt;
&lt;td&gt;&lt;code&gt;172.17.0.1&lt;/code&gt; + 映射端口&lt;/td&gt;
&lt;td&gt;&lt;code&gt;172.17.0.1&lt;/code&gt; 是默认 docker0 网桥上宿主机的地址&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;服务在另一台机器&lt;/td&gt;
&lt;td&gt;那台机器的内网/公网 IP&lt;/td&gt;
&lt;td&gt;跨机器时注意对方防火墙放行来源&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;本系列的部署大多是「各服务独立 Compose、端口映射到宿主机」，所以常用第二种写法：服务 Compose 里把端口映射出来，NPM 转发到 &lt;code&gt;172.17.0.1:端口&lt;/code&gt;。同时宿主机防火墙只放行 80/443/SSH，服务端口虽然映射在宿主机上，但被防火墙挡在外面，只有本机的 NPM 能访问到——这正是「只开三个端口」的实现方式。&lt;/p&gt;
&lt;h2&gt;进阶两件套：访问控制与自定义配置&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Access Lists&lt;/strong&gt; 是 NPM 被低估的功能。给监控、密码库这类敏感服务的 Proxy Host 绑一个 Access List，可以叠加两层保护：IP 白名单（只允许你自己的出口 IP 段访问）和/或 HTTP 基础认证（进服务登录页之前先过一道 NPM 的账号密码）。哪怕某个服务将来爆出登录绕过漏洞，这道前置门也能挡住绝大多数扫描。完整的加固思路在第 11 篇 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全加固：最小暴露与访问控制&lt;/a&gt; 展开。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Advanced 页签&lt;/strong&gt; 可以给单个站点追加原生 Nginx 配置，常见用途是放行大文件上传。默认 Nginx 对请求体大小有限制，云盘类服务传大文件报 413 时，在对应 Proxy Host 的 Advanced 里加：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;client_max_body_size 0;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;保存即生效，不用重启容器。改之前想清楚作用域：这行只加在需要的站点上，别图省事写进全局。&lt;/p&gt;
&lt;h2&gt;排障：最常见的三个问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;502 Bad Gateway&lt;/strong&gt;：NPM 活着但上游不通。依次查：服务容器是否在运行（&lt;code&gt;docker compose ps&lt;/code&gt;）、转发 IP 和端口是否写对、在 NPM 容器内能否连通上游（&lt;code&gt;docker exec -it nginx-proxy-manager curl -v http://172.17.0.1:端口&lt;/code&gt;）。九成是端口写错或服务没起来。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;证书申请失败&lt;/strong&gt;：先自查 &lt;code&gt;curl http://你的域名&lt;/code&gt; 能否从外网打开（哪怕是报错页面），再确认云厂商安全组放行了 80。DNS 刚改完要等生效，用 &lt;code&gt;dig +short 域名&lt;/code&gt; 看解析是不是已经指向本机。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;跳转死循环/页面资源加载不全&lt;/strong&gt;：多见于服务本身不知道自己在反代后面。优先在服务侧找「外部访问地址/站点 URL」类设置，填成 &lt;code&gt;https://子域名&lt;/code&gt;；个别服务需要在 Advanced 里补 &lt;code&gt;proxy_set_header X-Forwarded-Proto $scheme;&lt;/code&gt;，NPM 默认已带大部分转发头，先查服务侧设置再动这里。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;改完配置不生效&lt;/strong&gt;：NPM 保存时会自动 reload Nginx，若页面缓存顽固，先强刷浏览器，再看 &lt;code&gt;docker compose logs -f&lt;/code&gt; 里有没有配置校验报错——Advanced 里写错语法会导致该站点配置加载失败，删掉自定义段即可恢复。&lt;/p&gt;
&lt;p&gt;:::warning
NPM 的管理后台本身就是全屋服务的钥匙：强密码、不开公网 81、再给它绑一个 Access List 做 IP 白名单，这三件事做完再去装别的服务。入口的安全等级，决定整套自建体系的安全上限。
:::&lt;/p&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：已经用 Caddy/原生 Nginx 了，有必要换 NPM 吗？&lt;/strong&gt;
没必要为了换而换。统一入口的目的是「只开 80/443 + 证书自动管理」，你现有方案做到了就继续用，本系列后续篇目里「通过 NPM 添加入口」的步骤，换成你自己的反代等价操作即可。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：服务在本机跑但不是 Docker 部署的，能转发吗？&lt;/strong&gt;
可以，Forward 填 &lt;code&gt;127.0.0.1&lt;/code&gt; 在 NPM 容器内指向的是容器自己，要填宿主机地址 &lt;code&gt;172.17.0.1&lt;/code&gt; 加服务端口（服务需监听 &lt;code&gt;0.0.0.0&lt;/code&gt; 或网桥可达的地址）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：一个域名多个路径分给不同服务行不行？&lt;/strong&gt;
NPM 支持 Custom Locations 按路径转发，但很多 Web 应用对子路径部署不友好（静态资源写死根路径）。一人一个子域名是省心做法，不建议用路径硬凑。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：NPM 挂了是不是所有服务都进不去？&lt;/strong&gt;
是的，这就是统一入口的代价。所以 NPM 的数据目录必须进备份清单，并且用第 4 篇的 &lt;a href=&quot;/posts/selfhost-uptime-kuma/&quot;&gt;Uptime Kuma：服务可用性监控与公开状态页&lt;/a&gt; 把 NPM 本身也列为监控对象——它值得被最先盯上。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Nginx Proxy Manager 把反向代理这件「概念重要、配置繁琐」的事变成了填表：一条 Proxy Host 记录 = 一个子域名 + 一份自动续期的 HTTPS 证书 + 可选的访问控制。整台机器对外只剩 80/443，服务增减都在一个面板里完成。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;先有统一入口，后面的每个服务才有资格谈安全与好用。&amp;lt;/span&amp;gt;地基打完，接下来给这台机器装上眼睛：Komari 监控面板与 Agent，先把「机器还好吗」这个问题解决掉。&lt;/p&gt;
</content:encoded></item><item><title>Open WebUI：自建 AI 聊天界面（本地模型与 API 接入）</title><link>https://www.anexns.cloudns.org/posts/selfhost-open-webui/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-open-webui/</guid><description>用 Docker 部署 Open WebUI：既能连同机 Ollama 在本地跑开源模型，也能只接外部 OpenAI 兼容 API 当纯前端，多用户、权限与全部对话数据都握在自己手里。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：聊天界面和对话数据，凭什么放在别人家&lt;/h2&gt;
&lt;p&gt;现在用 AI 聊天，主流姿势是打开某个厂商的网页或 App：界面是人家的，对话记录存在人家的服务器上，账号一封、服务一停，你的历史会话、上传的文档、调好的提示词全都跟着没了。更别提不少服务有地区和支付门槛，光是「能用上」就得费一番周折。&lt;/p&gt;
&lt;p&gt;Open WebUI 解决的正是这一层：它是一个可以自建的 AI 聊天前端，界面长得和主流 AI 聊天产品几乎一样——左侧会话列表、模型切换、文档上传、多模态输入一应俱全——但它跑在你自己的服务器上，后端接什么模型完全由你决定：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;想彻底离线，就连同机部署的 Ollama，在本地跑开源模型，一个字都不出内网；&lt;/li&gt;
&lt;li&gt;想用云端大模型的能力，就填一个 OpenAI 兼容的 API 地址和密钥，它只当一个纯前端，请求直达你填的接口；&lt;/li&gt;
&lt;li&gt;两种可以同时接：本地模型处理日常小问题，云端 API 留给硬活，界面里下拉切换。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;本篇是「自建服务实战系列」的扩充篇。动手之前，建议先看 &lt;a href=&quot;/posts/selfhost-getting-started/&quot;&gt;自建服务入门：从一台 VPS 开始的完整规划&lt;/a&gt; 把机器、域名和目录规划好，本篇默认你已经有一台装好 Docker 的服务器。&lt;/p&gt;
&lt;h2&gt;两种形态，先选再装&lt;/h2&gt;
&lt;p&gt;Open WebUI 本身不包含模型，它只是「界面 + 用户系统 + 数据层」。模型从哪来，决定了部署形态：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;形态一：本地模型&lt;/th&gt;
&lt;th&gt;形态二：纯前端接 API&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;模型来源&lt;/td&gt;
&lt;td&gt;同机 Ollama 跑开源模型&lt;/td&gt;
&lt;td&gt;外部 OpenAI 兼容 API&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;资源占用&lt;/td&gt;
&lt;td&gt;高，吃 CPU/GPU 和内存&lt;/td&gt;
&lt;td&gt;极低，一个小容器即可&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;数据流向&lt;/td&gt;
&lt;td&gt;完全不出内网&lt;/td&gt;
&lt;td&gt;请求发往你填的 API 服务商&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;回答质量&lt;/td&gt;
&lt;td&gt;取决于本地模型大小&lt;/td&gt;
&lt;td&gt;取决于所接的云端模型&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;成本&lt;/td&gt;
&lt;td&gt;电费 + 硬件&lt;/td&gt;
&lt;td&gt;按 API 用量付费&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;典型场景&lt;/td&gt;
&lt;td&gt;隐私敏感、离线可用、随便折腾&lt;/td&gt;
&lt;td&gt;小服务器、要强模型、多人共用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;两种形态不冲突：先按形态二十分钟搭起来用上，之后有闲置显卡再把本地 Ollama 挂上去，界面和账号数据都不用动。&amp;lt;/span&amp;gt;下面分别给出两套 Compose。&lt;/p&gt;
&lt;h2&gt;形态一：同机 Ollama 跑本地模型&lt;/h2&gt;
&lt;p&gt;Ollama 是目前最省心的本地模型运行器，一条命令拉模型、一条命令跑服务，还对外提供标准的 HTTP 接口。把 Ollama 和 Open WebUI 放进同一份 Compose、同一个 Docker 网络，两者用服务名直连，最稳妥：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    volumes:
      - ollama:/root/.ollama

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: unless-stopped
    depends_on:
      - ollama
    ports:
      - &quot;3000:8080&quot;
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
    volumes:
      - open-webui:/app/backend/data

volumes:
  ollama:
  open-webui:
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动后先给 Ollama 拉一个模型（以通义千问 7B 量化版为例，中文对话够用、体积约 5 GB）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec -it ollama ollama pull qwen2.5:7b
docker exec -it ollama ollama list
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后浏览器打开 &lt;code&gt;http://服务器IP:3000&lt;/code&gt;，注册的第一个账号自动成为管理员。进界面后左上角模型列表里应该已经能看到刚拉的模型，点开就能聊。想换大模型就再 &lt;code&gt;pull&lt;/code&gt; 一个更大的，Open WebUI 会自动把 Ollama 里所有已下载模型列出来。&lt;/p&gt;
&lt;p&gt;有 NVIDIA 显卡的话，给 ollama 服务加上 GPU 预留，推理速度会有数量级差别：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    # 在 ollama 服务下追加
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;没有显卡也能跑，只是 7B 模型用 CPU 推理大概每秒几个字，适合当备用和玩具，别指望它干重活。另外提一句：官方还提供 &lt;code&gt;ghcr.io/open-webui/open-webui:ollama&lt;/code&gt; 这种把 Ollama 打包进同一个容器的镜像，一条 &lt;code&gt;docker run&lt;/code&gt; 就能起全套，适合尝鲜；长期使用还是推荐上面的双容器拆分版，升级和排障都更清楚。&lt;/p&gt;
&lt;p&gt;:::warning
Ollama 的 11434 端口默认没有任何鉴权。上面的 Compose 没有把 11434 映射到宿主机，这是故意的——&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;千万不要为了「方便调试」把无鉴权的 Ollama 端口暴露到公网&amp;lt;/span&amp;gt;，任何人扫到都能白嫖你的算力，甚至通过接口乱拉模型塞满你的硬盘。需要从别的机器调 Ollama 时，走内网或反向代理加认证。
:::&lt;/p&gt;
&lt;h2&gt;形态二：只接外部 API 当纯前端&lt;/h2&gt;
&lt;p&gt;如果你的服务器只是台 2 核 2G 的小机器，本地跑模型不现实，那就让 Open WebUI 纯当界面：删掉 Ollama，只填 API 地址。任何提供 OpenAI 兼容接口的服务都能接（官方 API、云厂商的模型服务、公司内网的模型网关都行）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: unless-stopped
    ports:
      - &quot;3000:8080&quot;
    environment:
      - OPENAI_API_BASE_URL=https://api.example.com/v1
      - OPENAI_API_KEY=sk-xxxxxxxxxxxx
    volumes:
      - open-webui:/app/backend/data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;注意 &lt;code&gt;OPENAI_API_BASE_URL&lt;/code&gt; 一般要带上 &lt;code&gt;/v1&lt;/code&gt; 后缀，具体以服务商文档为准。想同时接多家做对比或互为备份，用分号分隔写多组：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;OPENAI_API_BASE_URLS=https://api-a.example.com/v1;https://api-b.example.com/v1
OPENAI_API_KEYS=sk-aaaa;sk-bbbb
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;两组值按顺序一一对应。接好后，各家的模型会合并出现在同一个模型列表里，聊天时随手切换——哪个便宜用哪个、哪个挂了切哪个，这是官方网页给不了的自由。&lt;/p&gt;
&lt;p&gt;密钥管理上多说一句：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要把带真实密钥的 Compose 文件提交到公开仓库&amp;lt;/span&amp;gt;，密钥单独写进同目录的 &lt;code&gt;.env&lt;/code&gt; 文件再用 &lt;code&gt;${VAR}&lt;/code&gt; 引用，或者至少把仓库设为私有。密钥一旦泄漏，账单是按分钟涨的。&lt;/p&gt;
&lt;h2&gt;第一次打开：管理员、多用户与权限&lt;/h2&gt;
&lt;p&gt;Open WebUI 的用户体系是它比「单机版聊天工具」更适合自建的原因：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;第一个注册的账号自动成为管理员&lt;/strong&gt;，所以部署完请第一时间自己注册占住这个位置；&lt;/li&gt;
&lt;li&gt;之后在管理员面板里可以关闭公开注册（&lt;code&gt;ENABLE_SIGNUP=false&lt;/code&gt; 环境变量也能锁死），新用户由管理员手动创建或审批；&lt;/li&gt;
&lt;li&gt;新注册用户默认是「待批准」状态，管理员批准后才能登录使用，可以逐个分配可用模型——比如只给家人开本地模型，强模型只留给自己；&lt;/li&gt;
&lt;li&gt;每个人有独立的会话历史、上传文档和个人设置，互不可见。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;也就是说，你完全可以把它当成一个「全家共用的 AI 入口」：你在后台统一管理模型和密钥，使用者只管打开网页聊天，不用每人去注册一堆账号、绑一堆卡。对话数据全部落在你自己的数据卷里，这正是下一篇要说的重点。&lt;/p&gt;
&lt;h2&gt;数据自持：你的聊天记录到底存在哪&lt;/h2&gt;
&lt;p&gt;Open WebUI 的全部状态都在 &lt;code&gt;open-webui&lt;/code&gt; 这个数据卷里，核心是 &lt;code&gt;/app/backend/data/webui.db&lt;/code&gt;（SQLite 数据库，存用户、会话、设置）和同目录下的上传文件、向量库数据。把这个卷纳入常规备份，就等于把整个站的历史完整带走，方法见 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移实战&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;这也是自建前端最实在的意义：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;模型可以随便换、API 可以随便切，但你的对话、文档和账号体系沉淀在自己手里，不随任何一家服务商的政策变化而消失。&amp;lt;/span&amp;gt;哪天某个 API 涨价或停服，你换一行环境变量继续用，历史会话一条不少。&lt;/p&gt;
&lt;h2&gt;进阶功能速览&lt;/h2&gt;
&lt;p&gt;用熟基础聊天之后，这几个内置功能值得打开：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;知识库（RAG）&lt;/strong&gt;：把 PDF、Word、文本文件传进知识库，聊天时让模型基于你的文档回答，适合喂产品手册、课程讲义、公司制度；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;联网搜索&lt;/strong&gt;：在设置里接一个搜索引擎后端（比如自建的 SearXNG），模型就能查实时信息再回答；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;模型预设与提示词&lt;/strong&gt;：给常用场景（翻译、润色、代码审查）存好系统提示词模板，一键调用，不用每次粘贴；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;语音输入输出&lt;/strong&gt;：浏览器端语音识别加上 TTS 接口，能当语音助手用。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;这些功能都不需要额外装容器，在管理面板里按需开启即可。注意知识库的向量检索会额外吃一些 CPU 和磁盘，文档量大的时候先小批量试。&lt;/p&gt;
&lt;h2&gt;对外访问：反向代理与 HTTPS&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;3000&lt;/code&gt; 端口明文 HTTP 只适合内网尝鲜。正式使用请套一层反向代理上 HTTPS，做法和系列里其他服务完全一致，见 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager：所有自建服务的统一入口&lt;/a&gt;：新增一条 Proxy Host 指向 &lt;code&gt;open-webui:3000&lt;/code&gt;（同 Docker 网络）或 &lt;code&gt;服务器IP:3000&lt;/code&gt;，勾选 Websockets Support（Open WebUI 的流式输出和语音功能要用到），再申请一张 Let&apos;s Encrypt 证书即可。&lt;/p&gt;
&lt;p&gt;安全上再补两点：一是管理员账号务必用强密码并保存在密码库里；二是如果只在家里用，完全可以用 Access List 或内网访问把暴露面降到零，整体思路见 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全加固：最小暴露与访问控制&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;界面里看不到 Ollama 的模型。&lt;/strong&gt; 先确认 Ollama 容器在跑：&lt;code&gt;docker compose ps&lt;/code&gt;；再进 Open WebUI 容器里测连通性：&lt;code&gt;docker exec -it open-webui curl http://ollama:11434/api/tags&lt;/code&gt;，能返回模型 JSON 说明链路没问题，多半是 &lt;code&gt;OLLAMA_BASE_URL&lt;/code&gt; 写错。如果你把 Ollama 装在宿主机而不是容器里，要改用 &lt;code&gt;http://host.docker.internal:11434&lt;/code&gt; 并给 open-webui 服务加 &lt;code&gt;extra_hosts: [&quot;host.docker.internal:host-gateway&quot;]&lt;/code&gt;，同时 Ollama 本身默认只监听 127.0.0.1，需要设 &lt;code&gt;OLLAMA_HOST=0.0.0.0&lt;/code&gt; 才接受容器来的连接——但记住前面的警告，这种用法只限内网。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;接了 API 但模型列表是空的。&lt;/strong&gt; 依次排查：Base URL 是否少了 &lt;code&gt;/v1&lt;/code&gt;；密钥是否有效（在宿主机上 &lt;code&gt;curl https://api.example.com/v1/models -H &quot;Authorization: Bearer 你的密钥&quot;&lt;/code&gt; 直接验证）；服务商是否限制了调用来源 IP。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;回答速度极慢。&lt;/strong&gt; 本地模型先看有没有用上 GPU：宿主机执行 &lt;code&gt;nvidia-smi&lt;/code&gt; 看 ollama 进程在不在；不在就是 GPU 预留没生效或驱动没装好。纯 CPU 跑大模型慢是物理规律，换小一号的模型或量化等级更实际。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;升级后页面打不开或报错。&lt;/strong&gt; 先 &lt;code&gt;docker compose logs -f open-webui&lt;/code&gt; 看日志。Open WebUI 更新较频繁，跨大版本升级前建议先备份数据卷再 &lt;code&gt;docker compose pull &amp;amp;&amp;amp; docker compose up -d&lt;/code&gt;，真出问题把镜像标签改回旧版本号就能回滚。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;多个人同时用，本地模型排队严重。&lt;/strong&gt; Ollama 默认并发有限，本地模型本质上是单机单卡资源，家庭内部错峰用没问题；要正经多人并发，还是把主力切到云端 API、本地只作备用。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Open WebUI 是自建服务里投入产出比很高的一类：一个小容器，换来一个界面现代、账号数据完全自持的 AI 聊天入口。部署形态就两条路——有显卡就连 Ollama 在本地跑开源模型，彻底离线；没硬件就只接 OpenAI 兼容 API 当纯前端，轻得任何小服务器都能带。把注册关掉、管理员占好、反向代理和 HTTPS 配上、数据卷纳入备份，它就能长期稳定地当全家人的 AI 总入口，模型爱换哪家换哪家。&lt;/p&gt;
</content:encoded></item><item><title>Paperless-ngx：文档票据数字化归档与全文搜索</title><link>https://www.anexns.cloudns.org/posts/selfhost-paperless-ngx/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-paperless-ngx/</guid><description>把合同、发票、票据、说明书统统扫进一个可全文搜索的私人档案库：Paperless-ngx 官方三件套 Compose 部署、中文 OCR 设置、消费目录与自动化归类、备份要点一次讲清。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：文件越来越多，能找出来的越来越少&lt;/h2&gt;
&lt;p&gt;每个人的文档都在以一种失控的方式增长：租房合同在微信收藏里，发票在邮箱附件里，保单是纸质的塞在抽屉里，产品说明书扫过一次就不知道存哪了。真到要用的时候——报销找发票、维权找合同、报修找保修卡——翻箱倒柜半小时是常态。&lt;/p&gt;
&lt;p&gt;网盘能解决「存」的问题，解决不了「找」的问题：文件名起得随手，内容搜不到，扫描件就是一张死图。这一篇的主角 Paperless-ngx 补的正是这一环：它把文档统一收进来，用 OCR 把扫描件和图片变成可搜索的文字，再用标签、通讯方、文档类型自动归档。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;目标是以后找任何一份文件，只需要记得里面出现过的任意一个词。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;本篇主线：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;用官方 Compose 三件套把 Paperless-ngx 跑起来&lt;/li&gt;
&lt;li&gt;配好中文 OCR，让中文合同发票也能识别&lt;/li&gt;
&lt;li&gt;打通消费目录、邮箱、API 等进料通道&lt;/li&gt;
&lt;li&gt;用匹配规则实现自动打标签、自动归类&lt;/li&gt;
&lt;li&gt;把备份这件事做对&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;部署方式延续本系列的一贯路线：Docker Compose 起服务，域名与 HTTPS 交给 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager&lt;/a&gt; 统一入口，方法不再重复。&lt;/p&gt;
&lt;h2&gt;Paperless-ngx 的架构：三个容器各司其职&lt;/h2&gt;
&lt;p&gt;Paperless-ngx 不是单体应用，官方推荐的 Compose 由三个服务组成：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;组件&lt;/th&gt;
&lt;th&gt;镜像&lt;/th&gt;
&lt;th&gt;职责&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;webserver&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ghcr.io/paperless-ngx/paperless-ngx&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;主程序：网页界面、OCR、文档消费与搜索&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;broker&lt;/td&gt;
&lt;td&gt;&lt;code&gt;redis:7&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;任务队列：OCR、索引等耗时任务排队执行&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;db&lt;/td&gt;
&lt;td&gt;&lt;code&gt;postgres:16&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;存元数据：标题、标签、通讯方、全文索引&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;文档原文件本身不进数据库，存在 &lt;code&gt;media&lt;/code&gt; 卷里；数据库只存「这份文档是谁的、什么时候、讲了什么」。这个分工决定了后面的备份策略：两边都得备，缺一不可。&lt;/p&gt;
&lt;h2&gt;Docker Compose 部署&lt;/h2&gt;
&lt;p&gt;在服务器上建目录，把官方结构落下来：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/paperless/{export,consume}
cd ~/paperless
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;docker-compose.yml&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:16
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: 改成你的数据库密码

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - &quot;8000:8000&quot;
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_SECRET_KEY: 改成一长串随机字符串
      PAPERLESS_TIME_ZONE: Asia/Shanghai
      PAPERLESS_OCR_LANGUAGE: chi_sim
      PAPERLESS_OCR_LANGUAGES: chi_sim
      PAPERLESS_ADMIN_USER: admin
      PAPERLESS_ADMIN_PASSWORD: 改成强密码
      USERMAP_UID: 1000
      USERMAP_GID: 1000

volumes:
  data:
  media:
  pgdata:
  redisdata:
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个关键点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;PAPERLESS_ADMIN_USER&lt;/code&gt; 与 &lt;code&gt;PAPERLESS_ADMIN_PASSWORD&lt;/code&gt; 只在首次启动时生效，自动创建管理员账号，之后改密码请在界面里改。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;USERMAP_UID/GID&lt;/code&gt; 要和宿主机上你的用户对齐（&lt;code&gt;id&lt;/code&gt; 命令查看），否则消费目录放进去的文件容器可能读不了。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;PAPERLESS_SECRET_KEY&lt;/code&gt; 是加密敏感数据用的密钥，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;一旦丢失或更换，已保存的邮箱密码等加密字段将无法解开&amp;lt;/span&amp;gt;，生成后请连同 Compose 文件一起纳入备份。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;启动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose up -d
docker compose logs -f webserver
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;日志出现应用启动完成字样后，浏览器打开 &lt;code&gt;http://服务器IP:8000&lt;/code&gt;，用上面设置的管理员账号登录。首次启动会多花一点时间：容器要按 &lt;code&gt;PAPERLESS_OCR_LANGUAGES&lt;/code&gt; 下载中文语言包并初始化数据库。&lt;/p&gt;
&lt;p&gt;:::warning
8000 端口只是调试入口，正式使用请走反向代理加 HTTPS，并且不要把 Paperless 直接裸奔在公网——里面躺着的是你全部合同、票据和证件扫描件，是家里隐私密度最高的服务之一。访问控制的完整思路见本系列的安全加固篇。
:::&lt;/p&gt;
&lt;h2&gt;中文 OCR：让中文文档也能被搜到&lt;/h2&gt;
&lt;p&gt;Paperless 底层用 Tesseract 做 OCR。默认语言是英文，识别中文必须做两件事，上面 Compose 里已经包含：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;PAPERLESS_OCR_LANGUAGE: chi_sim&lt;/code&gt;——默认 OCR 语言设为简体中文（繁体是 &lt;code&gt;chi_tra&lt;/code&gt;）。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;PAPERLESS_OCR_LANGUAGES: chi_sim&lt;/code&gt;——官方镜像默认只带英、德、法、意、西几种语言，中文语言包靠这个变量在容器启动时额外下载安装。中英混排文档可以写 &lt;code&gt;chi_sim+eng&lt;/code&gt;，识别语言一项里把两种都带上。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;效果预期要放平：印刷体中文合同、发票识别率相当可用；手写体、歪斜拍照、分辨率太低的图，识别质量会明显下降。扫描环节给三个硬指标：分辨率 300 DPI 起步、页面摆正、光线均匀。手机扫描建议用系统自带「扫描文稿」或专业扫描 App 先生成规整的 PDF 再导入，比直接拍照片再让 OCR 硬啃靠谱得多。&lt;/p&gt;
&lt;p&gt;如果存量文档已经入库才改的语言设置，旧文档不会自动重跑 OCR，需要在文档列表里批量选中执行「重新处理」，或者对单份文档在详情页触发。&lt;/p&gt;
&lt;h2&gt;文档怎么进来：四条进料通道&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;通道&lt;/th&gt;
&lt;th&gt;适合场景&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;网页上传&lt;/td&gt;
&lt;td&gt;零散文件随手存&lt;/td&gt;
&lt;td&gt;登录界面拖拽上传，支持 PDF、图片、Office 文档等&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;消费目录&lt;/td&gt;
&lt;td&gt;扫描仪、手机同步&lt;/td&gt;
&lt;td&gt;丢进 &lt;code&gt;consume&lt;/code&gt; 文件夹的文件会被自动处理并删除原文件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;邮箱抓取&lt;/td&gt;
&lt;td&gt;发票、对账单&lt;/td&gt;
&lt;td&gt;配置 IMAP 邮箱与规则，附件自动入库&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;REST API&lt;/td&gt;
&lt;td&gt;脚本与自动化&lt;/td&gt;
&lt;td&gt;&lt;code&gt;POST /api/documents/post_document/&lt;/code&gt;，令牌认证&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;消费目录是最值得打通的一条：把它和本系列 &lt;a href=&quot;/posts/selfhost-file-sync/&quot;&gt;文件同步篇&lt;/a&gt; 的 Syncthing 组合起来——手机上扫完的文档同步到服务器的 &lt;code&gt;consume&lt;/code&gt; 目录，几秒后就出现在 Paperless 里并完成 OCR 和归类，全程不用手动上传。两个细节：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;消费目录里的文件被成功处理后会从目录中删除，这是设计行为不是故障；想按子文件夹自动打标签可以开启 &lt;code&gt;PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;如果 &lt;code&gt;consume&lt;/code&gt; 挂在网络文件系统上，文件变化通知可能不灵，补一个 &lt;code&gt;PAPERLESS_CONSUMER_POLLING: 10&lt;/code&gt; 让它每 10 秒轮询一次。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;邮箱抓取在设置里的「邮件」中配置：先加邮件账户（IMAP 服务器、账号、密码），再建处理规则——按发件人、主题关键词过滤，指定附件处理后把邮件标记已读、移动到指定文件夹或删除。电子发票、对账单这类定期到达的文档，用这条通道可以做到完全无人值守。&lt;/p&gt;
&lt;h2&gt;自动化归类：标签、通讯方与文档类型&lt;/h2&gt;
&lt;p&gt;手动给每份文档打标签是不可持续的，Paperless 的自动化靠三类元数据加匹配规则：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;通讯方（Correspondent）&lt;/strong&gt;：文档的来源方，比如税务局、银行、房东、公司行政。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;文档类型（Document Type）&lt;/strong&gt;：合同、发票、保单、说明书、账单。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;标签（Tag）&lt;/strong&gt;：自由维度，比如「待报销」「2026」「重要」。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;在管理界面给每一类建好条目后，为条目设置匹配方式：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;匹配方式&lt;/th&gt;
&lt;th&gt;行为&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;任意词 / 全部词&lt;/td&gt;
&lt;td&gt;OCR 文本里出现指定关键词即命中&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;精确匹配 / 正则&lt;/td&gt;
&lt;td&gt;按整段文本或正则表达式命中&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;模糊匹配&lt;/td&gt;
&lt;td&gt;容忍 OCR 识别错误，适合扫描质量参差的来源&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;自动&lt;/td&gt;
&lt;td&gt;机器学习分类器，根据你已归类好的历史文档自动判断&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;实战建议：先手动认真归类二三十份文档打底，通讯方和文档类型尽量切到「自动」，分类器学到的样本越多越准；关键词特征特别明显的（比如发票上的「增值税专用发票」）用关键词匹配兜底。新版 Paperless 还提供「工作流」功能，可以按「文档新增/消费/更新」触发，自动赋标题模板、标签、通讯方甚至权限，比单条匹配规则更成体系，文档量大了值得迁过去。&lt;/p&gt;
&lt;p&gt;标题也建议用模板规范化，比如 &lt;code&gt;{correspondent} - {document_type} - {created}&lt;/code&gt;，列表里一眼就能扫清。&lt;/p&gt;
&lt;h2&gt;备份：原文件与数据库，一个都不能少&lt;/h2&gt;
&lt;p&gt;Paperless 自带导出工具，把全部文档连同元数据导成一个可迁移的目录：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker compose exec webserver document_exporter ../export
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;导出的 &lt;code&gt;export&lt;/code&gt; 目录里有原始文件、归档版 PDF 和一份 &lt;code&gt;manifest.json&lt;/code&gt; 元数据清单。换机器恢复时把目录拷回，执行 &lt;code&gt;document_importer&lt;/code&gt; 即可完整重建。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;最忌讳的备份方式是只备份 PostgreSQL 数据库&amp;lt;/span&amp;gt;——数据库里没有文档原件，原件全在 &lt;code&gt;media&lt;/code&gt; 卷里，只备一半等于没备。&lt;/p&gt;
&lt;p&gt;日常备份策略和本系列 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;备份与迁移篇&lt;/a&gt; 一致：&lt;code&gt;document_exporter&lt;/code&gt; 定期导出 + &lt;code&gt;pgdata&lt;/code&gt;、&lt;code&gt;media&lt;/code&gt;、&lt;code&gt;data&lt;/code&gt; 三个卷整目录打包，两份材料互相印证，再同步一份到机器之外。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;放进消费目录的文件没被处理。&lt;/strong&gt;
先看权限：文件属主与 &lt;code&gt;USERMAP_UID&lt;/code&gt; 对不上时容器读不到。再看日志 &lt;code&gt;docker compose logs webserver&lt;/code&gt;，消费失败的原因（格式不支持、文件损坏）都会写明。网络盘挂载的目录记得加轮询变量。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;中文识别结果一塌糊涂。&lt;/strong&gt;
九成是源文件质量问题：确认扫描分辨率到 300 DPI、页面没有倾斜。再确认语言变量生效——在文档详情的 OCR 文本里如果全是乱码方块，多半是语言包没装上，重启容器看启动日志有没有下载 &lt;code&gt;chi_sim&lt;/code&gt; 的记录。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;反向代理后登录一直跳转或提示 CSRF 失败。&lt;/strong&gt;
通过域名访问时补上环境变量 &lt;code&gt;PAPERLESS_CSRF_TRUSTED_ORIGINS: https://你的域名&lt;/code&gt;，并确认反代传递了正确的 Host 头，改完重建容器。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;文档量大了界面变卡。&lt;/strong&gt;
OCR 是吃 CPU 和内存的大户，批量导入时把 &lt;code&gt;PAPERLESS_TASK_WORKERS&lt;/code&gt; 按机器核数调（默认会自动取），小内存机器同时跑的消费任务别贪多；搜索慢则多半是数据库没跟上，先给 &lt;code&gt;db&lt;/code&gt; 的卷换到 SSD 上再谈调参。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;想批量修改已入库文档的标签。&lt;/strong&gt;
文档列表页勾选多份后有批量编辑功能，可以统一改通讯方、类型和标签，改完分类器的训练样本也随之更新，越用越准。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Paperless-ngx 干的事可以概括成一句话：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;把「存文件」升级成「存得进、找得出、不用手动整理」的档案系统。&amp;lt;/span&amp;gt;部署就是官方三件套 Compose，真正的功夫在后面三件小事上：中文 OCR 语言配对、消费目录和同步工具打通、匹配规则先手动打底再交给自动分类。备份记住原文件和数据库两条腿走路，这个装满全家隐私的服务才算真正落在自己手里。&lt;/p&gt;
&lt;p&gt;它是本系列扩充篇的一员，同批的还有 Open WebUI、Immich 与 &lt;a href=&quot;/posts/selfhost-gitea/&quot;&gt;Gitea&lt;/a&gt;，都是把数据和服务握回自己手里的路子。&lt;/p&gt;
</content:encoded></item><item><title>Rocket.Chat：私有聊天服务器部署</title><link>https://www.anexns.cloudns.org/posts/selfhost-rocketchat/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-rocketchat/</guid><description>用 Docker Compose 在 VPS 上部署 Rocket.Chat 私有聊天服务器：MongoDB 副本集初始化、反向代理接入、管理员与注册策略、桌面与手机客户端连接，以及 502、oplog 报错等常见故障的排查方法。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说清楚：为什么要自建聊天服务器&lt;/h2&gt;
&lt;p&gt;团队群聊、家庭沟通、朋友之间传文件，日常用的都是别人的平台：聊天记录存在对方服务器上，账号说封就封，文件链接过段时间就失效。自建聊天服务器解决的就是这件事——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;数据在自己的 VPS 上，规则自己定，想留多久留多久&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;p&gt;Rocket.Chat 是自建聊天里最成熟的开源方案之一：频道、私聊、文件传输、音视频通话（通过集成）、多端客户端一应俱全，界面接近 Slack，用起来没有学习成本。这一篇我们用 Docker Compose 把它完整搭起来：Rocket.Chat 本体加 MongoDB 数据库，再通过前面部署的反向代理对外提供 HTTPS 访问。&lt;/p&gt;
&lt;p&gt;整篇的主线是：&lt;strong&gt;准备 Compose → 初始化 MongoDB 副本集 → 启动并完成管理员设置 → 关紧注册入口 → 客户端接入 → 日常维护与排障&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;部署架构与资源要求&lt;/h2&gt;
&lt;p&gt;Rocket.Chat 不是单容器能跑起来的，它强依赖 MongoDB，而且新版本要求 MongoDB 以**副本集（Replica Set）**模式运行——这是很多人第一次部署时踩的坑：直接套个单机 MongoDB，容器能启动，但日志里会反复报 oplog 相关错误，消息实时推送也不正常。所以 Compose 里要多一个初始化容器，专门负责把副本集拉起来。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;组件&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;rocket.chat&lt;/td&gt;
&lt;td&gt;聊天服务本体&lt;/td&gt;
&lt;td&gt;监听 3000 端口，只对内&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;mongo&lt;/td&gt;
&lt;td&gt;数据库&lt;/td&gt;
&lt;td&gt;副本集模式，存全部消息与用户数据&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;mongo-init&lt;/td&gt;
&lt;td&gt;一次性初始化容器&lt;/td&gt;
&lt;td&gt;执行 rs.initiate 后自动退出&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Nginx Proxy Manager&lt;/td&gt;
&lt;td&gt;反向代理&lt;/td&gt;
&lt;td&gt;统一入口与 HTTPS，见系列第 2 篇&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;资源方面，Rocket.Chat 是这批自建服务里偏重的一个：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;使用规模&lt;/th&gt;
&lt;th&gt;建议配置&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;个人/家庭（&amp;lt;10 人）&lt;/td&gt;
&lt;td&gt;2 核 2 GB&lt;/td&gt;
&lt;td&gt;空载内存约 800 MB&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;小团队（10–50 人）&lt;/td&gt;
&lt;td&gt;2 核 4 GB&lt;/td&gt;
&lt;td&gt;建议预留 Swap&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;50 人以上&lt;/td&gt;
&lt;td&gt;4 核 8 GB 起&lt;/td&gt;
&lt;td&gt;另考虑对象存储存附件&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;域名提前解析好一个子域名，例如 &lt;code&gt;chat.example.com&lt;/code&gt;，解析方法在系列第 1 篇 &lt;a href=&quot;/posts/selfhost-getting-started/&quot;&gt;自建服务入门：从一台 VPS 开始的完整规划&lt;/a&gt; 里已经交代过。&lt;/p&gt;
&lt;h2&gt;编写 Compose 并启动&lt;/h2&gt;
&lt;p&gt;在服务器上新建目录并写入 &lt;code&gt;docker-compose.yml&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  mongo:
    image: mongo:6.0
    container_name: rocketchat-mongo
    restart: unless-stopped
    command: mongod --replSet rs0 --bind_ip_all
    volumes:
      - ./mongo-data:/data/db
    environment:
      TZ: Asia/Shanghai

  mongo-init:
    image: mongo:6.0
    container_name: rocketchat-mongo-init
    depends_on:
      - mongo
    entrypoint: &amp;gt;
      bash -c &quot;
        until mongosh --host mongo:27017 --eval &apos;rs.status()&apos;; do sleep 2; done;
        mongosh --host mongo:27017 --eval &apos;rs.initiate({_id: \&quot;rs0\&quot;, members: [{_id: 0, host: \&quot;mongo:27017\&quot;}]})&apos;
      &quot;

  rocketchat:
    image: rocketchat/rocket.chat:latest
    container_name: rocketchat
    restart: unless-stopped
    depends_on:
      - mongo
    environment:
      ROOT_URL: https://chat.example.com
      MONGO_URL: mongodb://mongo:27017/rocketchat?replicaSet=rs0
      MONGO_OPLOG_URL: mongodb://mongo:27017/local?replicaSet=rs0
      PORT: 3000
      TZ: Asia/Shanghai
    ports:
      - &quot;127.0.0.1:3000:3000&quot;
    volumes:
      - ./uploads:/app/uploads
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个关键点：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;ROOT_URL&lt;/code&gt; 必须填最终对外访问的完整地址（含 &lt;code&gt;https://&lt;/code&gt;），后面生成的邮件链接、文件链接、客户端校验都依赖它，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;填错会导致文件打不开、客户端连不上&amp;lt;/span&amp;gt;，改起来还要清缓存，能一次填对就别返工。&lt;/li&gt;
&lt;li&gt;端口映射绑在 &lt;code&gt;127.0.0.1&lt;/code&gt;，不对公网直接暴露，流量统一从反向代理进。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;uploads&lt;/code&gt; 卷存用户上传的文件附件，这是核心数据的一部分，备份时不能漏。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;启动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/rocketchat &amp;amp;&amp;amp; cd ~/rocketchat
docker compose up -d
docker compose logs -f rocketchat
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;第一次启动要等 MongoDB 选出主节点、Rocket.Chat 跑完数据库迁移，日志里出现 &lt;code&gt;SERVER RUNNING&lt;/code&gt; 才算就绪，一般需要一两分钟。&lt;/p&gt;
&lt;h2&gt;反向代理与首次设置&lt;/h2&gt;
&lt;p&gt;在 Nginx Proxy Manager 里新增一条 Proxy Host（具体操作见 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager：所有自建服务的统一入口&lt;/a&gt;）：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;配置项&lt;/th&gt;
&lt;th&gt;值&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Domain Names&lt;/td&gt;
&lt;td&gt;chat.example.com&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Forward Hostname&lt;/td&gt;
&lt;td&gt;127.0.0.1&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Forward Port&lt;/td&gt;
&lt;td&gt;3000&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Websockets Support&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;开启&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SSL&lt;/td&gt;
&lt;td&gt;申请证书并开启 Force SSL&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;WebSocket 必须开，否则消息不能实时推送，会出现「发出去的消息对方半天才收到」。&lt;/p&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;https://chat.example.com&lt;/code&gt;，首次访问会进入设置向导：创建管理员账号、设置站点名称、组织信息随便填。管理员账号的邮箱和密码务必记牢，这是整套系统的最高权限。&lt;/p&gt;
&lt;h2&gt;关紧注册入口&lt;/h2&gt;
&lt;p&gt;向导走完之后，第一件事不是拉人，而是关门。进入 &lt;strong&gt;管理面板 → 设置 → 常规 → 注册&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;「手动批准新用户」打开，或者直接把注册方式改成「私密」/关闭公开注册；&lt;/li&gt;
&lt;li&gt;开启「注册时需要验证邮箱」；&lt;/li&gt;
&lt;li&gt;在 &lt;strong&gt;设置 → 账户&lt;/strong&gt; 里打开两步验证（TOTP）的支持。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;绝对不要让自建聊天服务器处于开放注册状态。&amp;lt;/span&amp;gt;公网可达的聊天服务一旦开放注册，很快会被批量注册机器人盯上，轻则灌垃圾消息，重则被当成违规内容的中转站，VPS 商家收到投诉可能直接停机。邀请制 + 人工批准是唯一推荐的姿势。
:::&lt;/p&gt;
&lt;p&gt;之后加人走「管理面板 → 用户 → 邀请」发邀请链接，或者管理员手动建号。频道方面，建议建一个全员默认加入的公告频道，再按话题拆几个小频道，比所有人挤在一个大群里清爽得多。&lt;/p&gt;
&lt;h2&gt;客户端接入&lt;/h2&gt;
&lt;p&gt;Rocket.Chat 有全平台官方客户端：Windows / macOS / Linux 桌面端，iOS / Android 移动端，应用商店搜 Rocket.Chat 即可。第一次打开客户端会让你填服务器地址，填 &lt;code&gt;https://chat.example.com&lt;/code&gt;，再用账号密码登录即可，不需要任何额外配置。&lt;/p&gt;
&lt;p&gt;注意移动端推送：自建服务器没有官方的推送网关加持时，App 在后台的消息推送依赖系统级通道，国行 Android 手机上可能收不到实时推送，需要把 App 设为允许自启动和后台运行。这是自建 IM 的通病，先有心理预期。&lt;/p&gt;
&lt;h2&gt;日常维护&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;更新&lt;/strong&gt;：&lt;code&gt;docker compose pull &amp;amp;&amp;amp; docker compose up -d&lt;/code&gt;。Rocket.Chat 大版本升级偶尔伴随数据库迁移，升级前务必先备份，备份方法见 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移实战&lt;/a&gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;附件存储&lt;/strong&gt;：默认附件存在本地 &lt;code&gt;uploads&lt;/code&gt; 卷，量大之后可以到「管理面板 → 设置 → 文件上传」切换到 S3 兼容存储。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;看日志&lt;/strong&gt;：&lt;code&gt;docker compose logs --tail 200 rocketchat&lt;/code&gt;，排障基本靠它。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;安全层面再补一刀：管理面板本身就是高价值目标，建议结合 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全加固：最小暴露与访问控制&lt;/a&gt; 里的方法，给 &lt;code&gt;/admin&lt;/code&gt; 路径或整个站点再加一层访问控制。&lt;/p&gt;
&lt;h2&gt;频道、权限与日常运营细节&lt;/h2&gt;
&lt;p&gt;服务跑起来只是开始，真正决定使用体验的是频道结构和权限划分。几个实用的经验：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;频道规划&lt;/strong&gt;：频道分三类就够了——全员公告频道（只读，只有管理员能发言，放重要通知）、按主题分的讨论频道（技术、生活、灌水各一）、临时项目频道（用完归档）。频道一多就没人说话，宁可少建、合并，也不要按一时兴起拆一堆空频道。私密频道适合放敏感话题，加入需要管理员邀请，历史消息对新成员默认不可见，这一点在建频道时要想清楚。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;角色与权限&lt;/strong&gt;：Rocket.Chat 的权限体系很细，在「管理面板 → 权限」里按角色（admin、moderator、user）逐项勾选。日常最值得收紧的三项是：普通用户能不能建频道、能不能邀请新人、能不能删除自己发的消息。团队规模小的时候可以放宽，等人多了再收也不迟，但「谁能批准新用户」这一项从第一天起就只给管理员。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;机器人与 Webhook&lt;/strong&gt;：Rocket.Chat 支持传入/传出 Webhook 和官方机器人框架。比如把服务器监控告警发到一个运维频道：在「管理面板 → 集成」里新建 Incoming Webhook，拿到地址后，监控脚本往这个地址 POST 一段 JSON 就能发消息。脚本示例：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;curl -X POST https://chat.example.com/hooks/xxxx/yyyy \
  -H &apos;Content-Type: application/json&apos; \
  -d &apos;{&quot;text&quot;: &quot;⚠️ 服务器 disk 使用率超过 85%&quot;}&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;把告警、备份结果、服务上下线通知都汇到一个频道，运维动态一目了然，这也是自建聊天相比公共平台的一大优势——集成不用看任何人脸色。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;消息保留策略&lt;/strong&gt;：在「管理面板 → 设置 → 常规」里可以设置频道消息的保留与清理规则。聊天记录长期攒下去，MongoDB 体积会稳步膨胀，小团队建议每半年看一次数据库大小：&lt;code&gt;docker exec rocketchat-mongo mongosh --eval &apos;db.runCommand({dbStats: 1, scale: 1073741824})&apos;&lt;/code&gt;，超过心理预期就考虑给老频道做归档或给文件附件转对象存储。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. 反向代理后页面 502&lt;/strong&gt;
先在服务器上直接验证服务本身：&lt;code&gt;curl -I http://127.0.0.1:3000&lt;/code&gt;。有响应说明是代理配置问题，检查 NPM 里转发端口和 WebSocket 开关；没响应就去看容器日志，多半是 MongoDB 还没就绪，Rocket.Chat 连不上数据库会反复重启。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 日志报 oplog / replica set 相关错误&lt;/strong&gt;
说明副本集没初始化成功。执行 &lt;code&gt;docker compose logs mongo-init&lt;/code&gt; 看初始化容器输出；手动验证：&lt;code&gt;docker exec -it rocketchat-mongo mongosh --eval &apos;rs.status()&apos;&lt;/code&gt;，确认有 PRIMARY 节点。常见原因是第一次启动时 mongo 还没完全起来初始化就失败了，重启一次 mongo-init 即可：&lt;code&gt;docker compose up mongo-init&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 文件上传成功但下载 404 / 链接是内网地址&lt;/strong&gt;
&lt;code&gt;ROOT_URL&lt;/code&gt; 配错的典型症状。改成正确的对外地址后重启 rocketchat 容器，并清掉浏览器缓存再试。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 内存占用越来越高&lt;/strong&gt;
Node.js 服务的通病。可以在 Compose 里给 rocketchat 加 &lt;code&gt;mem_limit: 1500m&lt;/code&gt; 并配合 &lt;code&gt;NODE_OPTIONS: --max-old-space-size=1024&lt;/code&gt;，同时确认系统有 Swap 兜底。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. 客户端提示服务器版本或地址无效&lt;/strong&gt;
九成是 HTTPS 证书链不完整或客户端填了 http 地址。确认 NPM 里 Force SSL 已开、证书有效，再让客户端删掉旧服务器重新添加。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇我们把 Rocket.Chat 用 Compose 完整搭了起来：关键点只有三个——MongoDB 必须跑副本集、&lt;code&gt;ROOT_URL&lt;/code&gt; 一次填对、注册入口第一时间关紧。剩下的频道、权限、客户端都是水到渠成的配置。自建聊天是所有自建服务里「存在感」最强的一个，搭好之后记得把它纳入例行备份，别让聊天记录只剩一份。&lt;/p&gt;
</content:encoded></item><item><title>自建服务安全加固：最小暴露与访问控制</title><link>https://www.anexns.cloudns.org/posts/selfhost-security-access/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-security-access/</guid><description>给全部自建服务做一次系统安全加固：盘点公网暴露面、服务只监听本地统一走反代、给管理入口加第二道门、账号与两步验证规范、SSH 与系统层防护，以及更新和日志审计的日常纪律。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说清楚：自建服务的安全边界在哪&lt;/h2&gt;
&lt;p&gt;前面十四篇我们把服务一个个搭了起来，每多一个服务，公网就多一个入口。自建服务的安全事故九成不是什么高深攻击，而是低级失误：管理后台裸奔在公网、默认密码没改、注册开放被机器人灌爆、老版本漏洞被扫描器批量收割。这一篇收官，专门把防线系统地补齐。&lt;/p&gt;
&lt;p&gt;核心思想只有八个字：&lt;strong&gt;最小暴露、分层设防&lt;/strong&gt;。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;公网上能摸到的东西越少，需要信任的东西就越少。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;主线：&lt;strong&gt;盘点暴露面 → 收口到反代 → 管理入口加第二道门 → 账号纪律 → 系统层防护 → 更新与审计&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;第一步：盘点你到底暴露了什么&lt;/h2&gt;
&lt;p&gt;先在服务器上把当前的对外监听列全：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ss -tlnp
docker ps --format &quot;table {{.Names}}\t{{.Ports}}&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐条对照，理想的暴露清单应该只剩三类：SSH 端口、反向代理的 80/443、以及确实需要直连的个别服务。逐个服务检查它的端口映射：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;暴露方式&lt;/th&gt;
&lt;th&gt;示例&lt;/th&gt;
&lt;th&gt;评价&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;直接映射公网&lt;/td&gt;
&lt;td&gt;&lt;code&gt;0.0.0.0:8080:80&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;除非必要，改掉&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;只绑本地&lt;/td&gt;
&lt;td&gt;&lt;code&gt;127.0.0.1:8080:80&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;推荐，统一走反代&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;不映射端口&lt;/td&gt;
&lt;td&gt;只在 Docker 网络内互通&lt;/td&gt;
&lt;td&gt;数据库类就该这样&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;把 Compose 里所有 &lt;code&gt;ports&lt;/code&gt; 逐个过一遍：应用类改成 &lt;code&gt;127.0.0.1:端口:端口&lt;/code&gt;，数据库类（PostgreSQL、MySQL、MongoDB、Redis）&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;直接删掉 ports 映射&amp;lt;/span&amp;gt;——它们只需要在 Docker 网络里被应用访问，任何情况下都不该出现在公网上。公网上裸奔的数据库是扫描器最爱的目标，没有例外。&lt;/p&gt;
&lt;h2&gt;第二步：统一入口与 HTTPS&lt;/h2&gt;
&lt;p&gt;收口之后，全部 Web 流量从 Nginx Proxy Manager 一个门进（部署见 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager：所有自建服务的统一入口&lt;/a&gt;），好处是防线可以集中配置：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;全部站点 Force SSL，证书自动续期；&lt;/li&gt;
&lt;li&gt;不再使用的子域名及时删掉解析和代理记录，别留「僵尸入口」；&lt;/li&gt;
&lt;li&gt;每个服务一个子域名，出了问题可以单独关停，不影响其他服务。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;第三步：给管理入口加第二道门&lt;/h2&gt;
&lt;p&gt;有些入口本身就是高价值目标：NPM 管理后台、Komari 管理端、各服务的 &lt;code&gt;/admin&lt;/code&gt; 路径。光靠应用自己的登录页不够，再加一层：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方案&lt;/th&gt;
&lt;th&gt;做法&lt;/th&gt;
&lt;th&gt;适合&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;反代 Basic Auth&lt;/td&gt;
&lt;td&gt;NPM 的 Access Lists 给站点加账密&lt;/td&gt;
&lt;td&gt;简单粗暴，适合低频后台&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;IP 白名单&lt;/td&gt;
&lt;td&gt;Access Lists 只放行自己的出口 IP&lt;/td&gt;
&lt;td&gt;出口 IP 固定时最佳&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cloudflare Access&lt;/td&gt;
&lt;td&gt;域名走 Cloudflare 时用邮箱验证码登录&lt;/td&gt;
&lt;td&gt;不想记额外密码时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;只走内网&lt;/td&gt;
&lt;td&gt;后台不配公网域名，SSH 隧道访问&lt;/td&gt;
&lt;td&gt;最稳，但用起来麻烦&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;以 NPM 为例：打开站点的 Access Lists，新建一条，设置用户名密码（或 IP 白名单），再回到 Proxy Host 把这条 Access List 挂上。效果是打开后台先弹一层系统级账密验证，过不去连登录页都看不到。扫描器撞库的成本一下就上去了。&lt;/p&gt;
&lt;p&gt;SSH 隧道访问内网服务的方法也很实用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ssh -L 8081:127.0.0.1:8080 root@你的服务器
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后浏览器打开 &lt;code&gt;http://127.0.0.1:8081&lt;/code&gt; 就能访问只监听本地的服务，全程走加密隧道，适合临时排障时看一眼不对外开放的后台。&lt;/p&gt;
&lt;h2&gt;第四步：账号纪律&lt;/h2&gt;
&lt;p&gt;应用层账号是最后一道、也是最常被攻破的一道：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;改掉一切默认账号密码&lt;/strong&gt;：装完服务的第一件事，不是第二天的事；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;关闭公开注册&lt;/strong&gt;：Rocket.Chat、FreshRSS、Vaultwarden 都在前面篇目里强调过，装完建好自己的号立刻关；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;管理员账号单独命名&lt;/strong&gt;：不要用 admin、root 这类可猜的名字当管理员用户名；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;两步验证能开尽开&lt;/strong&gt;：尤其是密码库、云盘、聊天这三个装着核心数据的服务；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;密码复用是大忌&lt;/strong&gt;：自建服务的管理员密码各用各的，统一存进 &lt;a href=&quot;/posts/selfhost-vaultwarden/&quot;&gt;Vaultwarden：自建密码库与客户端接入&lt;/a&gt; 里管理。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::warning
两步验证的恢复代码和密码库主密码一样，属于「丢了会锁死自己」的东西。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;恢复代码要离线存一份&amp;lt;/span&amp;gt;，不要只存在服务里或同一台手机上——手机丢了又没恢复代码，体验会非常酸爽。
:::&lt;/p&gt;
&lt;h2&gt;第五步：系统层防护&lt;/h2&gt;
&lt;p&gt;服务器本身的安全在 Linux 系列里有完整的展开，这里只列与自建服务直接相关的几条：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;SSH 只许密钥登录&lt;/strong&gt;，关闭密码登录并改非默认端口，具体步骤见 &lt;a href=&quot;/posts/linux-ssh-hardening/&quot;&gt;SSH 安全加固&lt;/a&gt;；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;防火墙只放行必要端口&lt;/strong&gt;：ufw 里除了 SSH 和 80/443，其余一律拒绝，Docker 映射的端口也要结合前文的绑本地处理，别以为有 ufw 就万事大吉；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;装 fail2ban 看着 SSH 和反代日志&lt;/strong&gt;，自动封禁反复试密码的 IP；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;时区和日志时间统一&lt;/strong&gt;，出事后对不上时间线会非常痛苦。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;第六步：容器层也别裸奔&lt;/h2&gt;
&lt;p&gt;应用跑在容器里，不等于天然安全。Compose 里顺手就能加的几项加固，建议对每个服务都过一遍：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  app:
    image: example/app:latest
    user: &quot;1000:1000&quot;              # 能用非 root 跑就别用 root
    read_only: true                # 根文件系统只读（需要写的目录单独挂 tmpfs 或卷）
    cap_drop:
      - ALL                        # 砍掉全部 Linux capabilities
    security_opt:
      - no-new-privileges:true     # 禁止提权
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;逐项说明：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;user&lt;/strong&gt;：很多官方镜像支持指定运行用户，或者通过 &lt;code&gt;PUID/PGID&lt;/code&gt; 环境变量降权。先看镜像文档，支持就开；个别老镜像强依赖 root 的，不要硬改，改完起不来反而折腾；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;read_only&lt;/strong&gt;：开了之后应用往系统目录写东西会失败，需要写的路径（缓存、临时文件）用 &lt;code&gt;tmpfs&lt;/code&gt; 或数据卷单独放出来，排障时看日志报错就知道缺哪个目录；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;cap_drop + no-new-privileges&lt;/strong&gt;：对绝大多数 Web 类服务无副作用，属于白捡的加固。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;另外，镜像版本别长期钉死在某个老 tag 上吃灰，也别无脑追 latest——合理姿势是钉大版本、按月手动升小版本，和下一节的更新纪律配套执行。&lt;/p&gt;
&lt;h2&gt;第七步：真出事了怎么办——应急处置顺序&lt;/h2&gt;
&lt;p&gt;发现异常登录、页面被篡改、服务器莫名跑满 CPU 时，按这个顺序处理，不要慌乱中先删东西：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;顺序&lt;/th&gt;
&lt;th&gt;动作&lt;/th&gt;
&lt;th&gt;目的&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;拍快照/整机镜像（商家面板支持的话）&lt;/td&gt;
&lt;td&gt;保全现场，方便事后复盘&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;改掉该服务全部管理员密码并强制下线所有会话&lt;/td&gt;
&lt;td&gt;先止血&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;看登录日志和反代日志，定位入侵入口与时间&lt;/td&gt;
&lt;td&gt;判断影响范围&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;检查同机其他服务有没有同款弱口令/同版本漏洞&lt;/td&gt;
&lt;td&gt;防止横向扩散&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5&lt;/td&gt;
&lt;td&gt;拿干净备份在新环境恢复，旧环境留档后销毁&lt;/td&gt;
&lt;td&gt;不信任已失陷的环境&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;核心原则是：&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;失陷过的系统不要试图「修干净」继续用&amp;lt;/span&amp;gt;，你永远不知道还埋了什么。正确的做法是保全日志、定位入口、用备份在干净环境重建。这也是为什么前一篇的备份体系如此重要——它不只是防数据丢失，也是安全事件的最后退路。&lt;/p&gt;
&lt;p&gt;平时就把几个关键日志的位置记清楚：反代访问日志、各服务的登录记录、SSH 的 auth.log。真出事时，能不能在十分钟内把这三份日志调出来，决定了处置质量。&lt;/p&gt;
&lt;h2&gt;第八步：更新纪律与日志审计&lt;/h2&gt;
&lt;p&gt;自建服务最大的长期风险是「搭完就不管了」。版本越老，公开漏洞越多。定个简单纪律：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;频率&lt;/th&gt;
&lt;th&gt;动作&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;每周&lt;/td&gt;
&lt;td&gt;瞄一眼各服务后台的版本提示和异常登录记录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每月&lt;/td&gt;
&lt;td&gt;手动执行一次 &lt;code&gt;docker compose pull &amp;amp;&amp;amp; up -d&lt;/code&gt; 批量更新，更新前先备份&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;每季度&lt;/td&gt;
&lt;td&gt;做一次恢复演练，顺带检查备份是否还能用&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;自动更新工具（如 Watchtower）对个人服务可以用，但建议只对无状态、挂了影响小的服务开启；数据库和密码库这类核心服务坚持手动更新，更新前备份、更新后验证。备份流程见 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移实战&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;日志审计不用复杂：定期看反代和关键服务的访问日志，留意三类信号——大量 404 扫描路径、非常用地区的登录成功记录、凌晨时段的异常请求峰值。真发现异常登录，先改密码、踢下线所有会话，再查来源。&lt;/p&gt;
&lt;h2&gt;补一层：域名与 DNS 层面的卫生&lt;/h2&gt;
&lt;p&gt;暴露面不只在服务器上，DNS 记录也是攻击面的一部分，顺手检查三件事：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;删掉不再使用的子域名解析&lt;/strong&gt;：下线一个服务时，解析记录要跟着删。留着的子域名如果后来指向的 IP 被别人拿去，等于把你的域名信誉借给了陌生人，严重的还会出子域名接管问题；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;谨慎使用泛解析&lt;/strong&gt;：&lt;code&gt;*.example.com&lt;/code&gt; 图省事，但任何人猜到一个没用过的子域名就能打到你的反代默认站点。按需逐个加记录，麻烦一点但干净；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;注册商账号本身开两步验证&lt;/strong&gt;：域名是所有服务的根，注册商账号被盗，改解析就能截走全部流量。这个账号的安全等级应该和密码库主密码看齐，别用弱密码，更别和其他站点共用密码。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;另外，建议每个季度把第一步的暴露面盘点重跑一遍：新装的服务有没有顺手开了公网端口、临时开的测试站点有没有忘关、证书有没有临期的。安全加固不是一次性工程，服务在变，清单就得跟着变。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. 绑了 127.0.0.1 之后反代 502&lt;/strong&gt;
NPM 和应用不在同一台机器/同一网络时，127.0.0.1 指的不是应用所在的位置。本系列默认 NPM 与服务同机或同 Docker 网络；跨机部署要改走内网 IP 并在防火墙上只放行反代机器。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 开了 Access List 后手机 App 连不上&lt;/strong&gt;
Basic Auth 这类额外验证很多 App 客户端不兼容。解决办法：给 App 用的域名或 API 路径单独建一条不挂 Access List 的 Proxy Host，只靠应用自身登录防护；管理后台域名继续加锁。鱼和熊掌分开端。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. IP 白名单把自己锁在外面&lt;/strong&gt;
家庭宽带出口 IP 会变。白名单方案建议和 Basic Auth 二选一或叠加时预留后路：先保留一个能进的通道（比如 SSH 隧道）再改配置，改完当场验证，别关了页面才发现进不去。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. fail2ban 把自己封了&lt;/strong&gt;
输错几次密码很正常。把常用出口 IP 加进 fail2ban 的 &lt;code&gt;ignoreip&lt;/code&gt; 白名单；已经被封的用 &lt;code&gt;fail2ban-client set sshd unbanip 你的IP&lt;/code&gt; 解开。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. 某天所有站点一起报证书过期&lt;/strong&gt;
多半是 NPM 的证书自动续期失败了，常见原因有三个：80 端口被防火墙或云厂商安全组挡住（Let&apos;s Encrypt 验证走不通）、域名解析被改到了别的机器、NPM 容器时间不对。逐个排查后在 NPM 里手动点一次 Renew，成功后再观察日志确认续期任务恢复正常。吸取教训的话，给证书到期时间也加一条监控告警，提前两周提醒，比过期当天全站红锁强得多——这正是系列第 4、5 篇监控体系存在的意义。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;自建服务的安全不靠某一个神器，靠的是层层收口：端口只绑本地、流量只走反代、管理入口再加一道门、账号关注册加两步、系统关密码登录、版本按月更新、备份定期演练。这十五篇到此收官——从一台 VPS 的规划开始，入口、监控、云盘、同步、影音、聊天、密码库、阅读器，一直到备份与安全，一套完整的个人基础设施就齐了。剩下的就是长期主义：让它安安稳稳地跑下去。&lt;/p&gt;
</content:encoded></item><item><title>Uptime Kuma：服务可用性监控与公开状态页</title><link>https://www.anexns.cloudns.org/posts/selfhost-uptime-kuma/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-uptime-kuma/</guid><description>机器活着不代表服务正常。这篇部署 Uptime Kuma：用 HTTP、TCP、Ping、DNS 等多种探测盯住每个自建服务，再做一个可公开访问的状态页，服务状态从此不用猜。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说问题：CPU 正常，网站照样打不开&lt;/h2&gt;
&lt;p&gt;上一篇 &lt;a href=&quot;/posts/selfhost-komari/&quot;&gt;Komari：轻量服务器监控探针部署与多节点接入&lt;/a&gt; 解决的是「机器怎么样」：CPU、内存、磁盘、流量。但机器层面的健康骗过你只需要一个瞬间：容器 OOM 被杀、证书悄悄过期、反代配置写错——机器曲线一切正常，用户打开页面却是一片 502。&lt;/p&gt;
&lt;p&gt;可用性监控盯的是另一件事：&lt;strong&gt;以用户的视角，这个服务现在能不能用&lt;/strong&gt;。Uptime Kuma 是这个领域最受欢迎的开源自建方案：界面友好、探测类型丰富、自带通知与公开状态页，一个容器就能跑。本篇把它部署好、把全屋服务都加进监控、再发布一个状态页，监控体系的第二条腿就站稳了。&lt;/p&gt;
&lt;h2&gt;探测类型一览&lt;/h2&gt;
&lt;p&gt;添加监控时先选类型，常用的就这几种：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;探测方式&lt;/th&gt;
&lt;th&gt;典型对象&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;HTTP(s)&lt;/td&gt;
&lt;td&gt;请求 URL，按状态码/关键字判定&lt;/td&gt;
&lt;td&gt;所有 Web 服务、反代入口&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TCP Port&lt;/td&gt;
&lt;td&gt;尝试建立 TCP 连接&lt;/td&gt;
&lt;td&gt;数据库、SSH、游戏服务器&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Ping&lt;/td&gt;
&lt;td&gt;ICMP 回显&lt;/td&gt;
&lt;td&gt;只有 IP 的设备、家用主机&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;DNS&lt;/td&gt;
&lt;td&gt;查询指定记录并比对结果&lt;/td&gt;
&lt;td&gt;自建 DNS、域名解析巡检&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Keyword&lt;/td&gt;
&lt;td&gt;在 HTTP 响应里找关键字&lt;/td&gt;
&lt;td&gt;页面能开但内容异常的场景&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Push&lt;/td&gt;
&lt;td&gt;服务主动上报心跳&lt;/td&gt;
&lt;td&gt;定时任务、备份脚本（见第 5 篇）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;判定逻辑记牢一条：HTTP 监控默认把 200–299 视为正常，需要放宽时在「接受的状态码」里调整，比如某些服务的 401（未登录拦截）其实代表活着，在列表里勾上即可。&lt;/p&gt;
&lt;h2&gt;部署：一份 Compose&lt;/h2&gt;
&lt;p&gt;按系列规范装在 &lt;code&gt;/opt/apps/uptime-kuma/&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - &quot;3001:3001&quot;
    volumes:
      - uptime-kuma-data:/app/data

volumes:
  uptime-kuma-data:
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/apps/uptime-kuma
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这里故意用了一个命名卷做示范——Uptime Kuma 官方推荐这种挂法，它的 &lt;code&gt;/app/data&lt;/code&gt; 里是 SQLite 数据库加配置。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;备份时不要只想着拷目录，命名卷要用 &lt;code&gt;docker volume&lt;/code&gt; 相关命令导出或整卷打包&amp;lt;/span&amp;gt;，第 11 篇 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移实战&lt;/a&gt; 会把目录挂载与命名卷两种情况的备份方法都讲清。&lt;/p&gt;
&lt;p&gt;首次访问 &lt;code&gt;http://你的IP:3001&lt;/code&gt; 创建管理员账号（第一个注册的账号即管理员）。随后按第 2 篇 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager：所有自建服务的统一入口&lt;/a&gt; 的流程加 Proxy Host，例如 &lt;code&gt;kuma.example.com&lt;/code&gt; 转发到 &lt;code&gt;172.17.0.1:3001&lt;/code&gt; 并申请证书，之后关掉 3001 的公网暴露。&lt;/p&gt;
&lt;p&gt;一个可选项先说清：Uptime Kuma 支持挂载宿主机 &lt;code&gt;/var/run/docker.sock&lt;/code&gt; 来监控容器状态。&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;挂载 docker.sock 等于把宿主机的完全控制权交给这个容器&amp;lt;/span&amp;gt;，非必要不挂——容器存活与否，Komari 的机器视角加本篇的服务探测已经够用，不要为省事开这个口子。&lt;/p&gt;
&lt;h2&gt;添加监控：把全屋服务盯起来&lt;/h2&gt;
&lt;p&gt;点「添加新监控项」，逐个把服务加进来。几个实务建议：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;监控目标优先填公网域名，而不是内网地址。&lt;/strong&gt; 填 &lt;code&gt;https://drive.example.com&lt;/code&gt;，走的是和真实用户完全相同的链路：DNS → 反代 → 证书 → 服务，任何一环坏了都能报出来。只盯内网端口，等于对最常坏的那段路视而不见。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;间隔与重试要成对设置。&lt;/strong&gt; 常规服务间隔 60 秒足够；判定故障前允许重试 2–3 次，避免一次网络抖动就误报。间隔、重试与通知节奏是一套联动参数，第 5 篇会系统地调。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;善用分组与标签。&lt;/strong&gt; 按「核心服务 / 一般服务 / 他人机器」分组，状态页和列表都会清爽很多；命名用 &lt;code&gt;服务名（域名）&lt;/code&gt; 的格式，报警消息里一眼能认。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;证书到期提醒别关。&lt;/strong&gt; HTTP(s) 监控会顺带检查证书剩余天数并在临近过期时提醒。虽然 NPM 会自动续期，但自动续期失败时，这条提醒就是最后一道保险。&lt;/p&gt;
&lt;p&gt;建议的初始监控清单：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对象&lt;/th&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;NPM 反代的每个子域名&lt;/td&gt;
&lt;td&gt;HTTP(s)&lt;/td&gt;
&lt;td&gt;每个服务一条&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Komari 面板域名&lt;/td&gt;
&lt;td&gt;HTTP(s)&lt;/td&gt;
&lt;td&gt;监控系统互相守夜&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;VPS 的 SSH 端口&lt;/td&gt;
&lt;td&gt;TCP&lt;/td&gt;
&lt;td&gt;只测连通，不测登录&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;家里主机&lt;/td&gt;
&lt;td&gt;Ping&lt;/td&gt;
&lt;td&gt;配合内网设备在线巡检&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;关键域名解析&lt;/td&gt;
&lt;td&gt;DNS&lt;/td&gt;
&lt;td&gt;防解析被篡改或过期&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;通知：先接一条能找到人的渠道&lt;/h2&gt;
&lt;p&gt;Uptime Kuma 内置了几十种通知渠道（Telegram、邮件、Webhook、企业微信、钉钉等）。本篇先完成「接通」：以 Telegram 为例，在设置 → 通知里新增，填入 Bot Token 与 Chat ID 保存后点测试，能收到测试消息即通。邮件则填 SMTP 服务器信息。&lt;/p&gt;
&lt;p&gt;渠道怎么选、多渠道怎么分工、半夜的告警发给谁——这些策略问题不在这里拍脑袋决定，第 5 篇 &lt;a href=&quot;/posts/selfhost-monitoring-alerts/&quot;&gt;监控告警实战：通知、值班与故障处理流程&lt;/a&gt; 专门处理。本篇的目标只是：任意监控项变红时，你的手机能响一声。&lt;/p&gt;
&lt;h2&gt;公开状态页：把状态晒出来&lt;/h2&gt;
&lt;p&gt;Uptime Kuma 自带状态页功能，这也是它区别于纯告警工具的一大价值：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;进入「状态页」管理，新建一个页面，起个路径名（如 &lt;code&gt;main&lt;/code&gt;）。&lt;/li&gt;
&lt;li&gt;把要公开的监控项按分组拖进去，核心服务在前。&lt;/li&gt;
&lt;li&gt;设置页面标题、说明文字与图标，保存后通过 &lt;code&gt;https://kuma.example.com/status/main&lt;/code&gt; 访问。&lt;/li&gt;
&lt;li&gt;想用独立域名（如 &lt;code&gt;status-page.example.com&lt;/code&gt;）也可以：在 NPM 里把该域名转发到同一个 3001，状态页支持按域名区分展示。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;状态页适合两种场景：服务是给家人朋友用的（出问题时让他们先看状态页，省去挨个解释）和给自己留一个「外网视角的总览」。但公开范围要克制：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;状态页只放对外服务的可用性，不放内网设备、监控细节和管理入口&amp;lt;/span&amp;gt;，管理后台本身永远不要出现在任何公开页面里。是否公开、公开什么的完整判断标准，在第 11 篇安全加固里还会再收一次口。&lt;/p&gt;
&lt;h2&gt;排障：监控自己的常见病&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;监控项一直误报 Down&lt;/strong&gt;：先看报错详情。超时多半是间隔太短或目标响应慢，适当放宽超时并加重试；状态码不对就核对「接受的状态码」；关键字监控找不到关键字，通常是页面改版或被重定向到登录页，改用状态码判定更稳。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;通知发不出去&lt;/strong&gt;：先用通知设置里的测试按钮单独验证渠道，再检查监控项是否勾选了该通知。Telegram 收不到时，常见原因是没给 Bot 发过第一条消息（Bot 不能主动私聊从未对话过的用户）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;状态页打开是空白/未发布&lt;/strong&gt;：确认状态页已保存并处于发布状态，且访问路径正确；套了独立域名时，回 NPM 检查该域名的转发是否指向 3001。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;数据库越来越大&lt;/strong&gt;：监控历史会持续增长。在设置里调整数据保留天数（比如 180 天），并把数据目录纳入容量巡检，别让监控把磁盘吃满——那会成为一篇绝妙的事故报告。&lt;/p&gt;
&lt;p&gt;:::warning
不要把 Uptime Kuma 和它监控的关键服务部署在同一台机器上还指望它报警：机器整机宕机时，监控会和服务一起沉默。条件允许时，把可用性监控放在另一台机器或家用设备上；实在只有一台，也至少在另一处（如第二台小鸡）给 Kuma 本身加一个外部探测。
:::&lt;/p&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：Uptime Kuma 和 Komari 功能重叠吗？&lt;/strong&gt;
不重叠。Komari 看机器内部指标（Agent 视角），Uptime Kuma 从外部探测服务可用性（用户视角）。前者回答「机器累不累」，后者回答「服务通不通」，本系列两个都装。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：监控间隔越短越好吗？&lt;/strong&gt;
不是。间隔越短，探测流量与资源消耗越大，误报概率也越高。60 秒是个人自建的甜点；真金白银的核心服务可以 30 秒，边缘服务 120–300 秒完全够。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：状态页能不能加密码？&lt;/strong&gt;
状态页的设计目标就是公开。如果只想自己看，直接用后台列表即可；需要团队可见又不想公开时，用 NPM 的 Access List 给状态页路径加一层基础认证。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：监控项几十个之后怎么维护？&lt;/strong&gt;
用分组和命名规范（见前文），并养成「新服务上线三件套」的习惯：加反代、加可用性监控、加进备份清单，一次做完，别攒账。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Uptime Kuma 补上了监控体系的外部视角：每个服务以真实用户的链路被持续探测，状态变化有记录、有通知，还有一个能公开示人的状态页。至此，机器视角（Komari）与服务视角（Uptime Kuma）都齐了。还差最后一环：告警响了之后怎么办——通知分级、降噪、值班与故障处理流程，下一篇专门讲透。&lt;/p&gt;
</content:encoded></item><item><title>Vaultwarden：自建密码库与客户端接入</title><link>https://www.anexns.cloudns.org/posts/selfhost-vaultwarden/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/selfhost-vaultwarden/</guid><description>用 Vaultwarden 在 VPS 上自建 Bitwarden 兼容密码库：Docker Compose 部署、关闭注册与管理员令牌、HTTPS 接入、用官方 Bitwarden 客户端全平台同步，以及密码库数据的备份要点。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;先说清楚：密码库为什么值得自建&lt;/h2&gt;
&lt;p&gt;密码管理器是数字生活的命门：所有账号的钥匙都锁在一个库里。这个库放在厂商云端，方便，但你要信任厂商的服务器、订阅政策和账号风控；放在自己手里，信任对象就只剩自己这台 VPS。&lt;/p&gt;
&lt;p&gt;Bitwarden 官方服务端功能全，但部署偏重（多个容器加 SQL Server 级别的数据库）。&lt;strong&gt;Vaultwarden&lt;/strong&gt; 是社区用 Rust 重写的轻量实现，完整兼容 Bitwarden 的 API 和全部官方客户端，个人使用还能直接用上组织共享、文件附件等原本的付费功能，一个容器、一个 SQLite 文件、几十 MB 内存就能跑。&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;对个人和小家庭来说，Vaultwarden 是自建密码库的最优解，没有之一。&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;主线：&lt;strong&gt;Compose 部署 → 配好域名与 HTTPS → 创建账号后立即关注册 → 设管理员令牌 → 客户端接入 → 备份这个「命门」目录&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;Compose 部署&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: &quot;https://vault.example.com&quot;
      SIGNUPS_ALLOWED: &quot;true&quot;
      INVITATIONS_ALLOWED: &quot;false&quot;
      TZ: Asia/Shanghai
    volumes:
      - ./vw-data:/data
    ports:
      - &quot;127.0.0.1:8080:80&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;启动：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p ~/vaultwarden &amp;amp;&amp;amp; cd ~/vaultwarden
docker compose up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;所有数据都在 &lt;code&gt;./vw-data&lt;/code&gt; 一个目录里：&lt;code&gt;db.sqlite3&lt;/code&gt; 是密码库数据库，&lt;code&gt;attachments/&lt;/code&gt; 是文件附件，&lt;code&gt;rsa_key.pem&lt;/code&gt; 是加密相关密钥。这个目录就是你的全部身家，后面备份篇会再强调。&lt;/p&gt;
&lt;p&gt;在 Nginx Proxy Manager 里给 &lt;code&gt;vault.example.com&lt;/code&gt; 加一条 Proxy Host，转发到 &lt;code&gt;127.0.0.1:8080&lt;/code&gt;，开启 Websockets Support 并申请 SSL 证书（方法见 &lt;a href=&quot;/posts/selfhost-nginx-proxy-manager/&quot;&gt;Nginx Proxy Manager：所有自建服务的统一入口&lt;/a&gt;）。&lt;/p&gt;
&lt;p&gt;:::warning
&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;Vaultwarden 必须走 HTTPS，明文 HTTP 下 Web 端会直接拒绝注册和登录。&amp;lt;/span&amp;gt;这是因为浏览器只在安全上下文里提供密码库依赖的加密 API。先把证书配好、确认 &lt;code&gt;https://&lt;/code&gt; 能打开，再进行下一步，不要在 HTTP 上折腾为什么按钮点不动。
:::&lt;/p&gt;
&lt;h2&gt;创建账号，然后立刻关门&lt;/h2&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;https://vault.example.com&lt;/code&gt;，点「创建账户」，用你的常用邮箱和一个&lt;strong&gt;足够长的主密码&lt;/strong&gt;注册。主密码是整个密码库的最后一道锁，Vaultwarden 服务端存的只是加密后的数据，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;主密码忘了，库里的数据谁都救不回来，包括你自己&amp;lt;/span&amp;gt;。建议用一句长短语，并把主密码本身离线记在安全的地方。&lt;/p&gt;
&lt;p&gt;账号能正常登录、同步没问题之后，马上把注册关掉。改 Compose 环境变量：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;      SIGNUPS_ALLOWED: &quot;false&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;然后 &lt;code&gt;docker compose up -d&lt;/code&gt; 让配置生效。之后再有人打开这个地址，只会看到登录框，注册入口消失。需要给家人开账号时，临时改回 &lt;code&gt;true&lt;/code&gt; 注册完再关，或者用管理员后台发邀请。&lt;/p&gt;
&lt;h2&gt;设置管理员令牌&lt;/h2&gt;
&lt;p&gt;Vaultwarden 有一个隐藏的管理后台 &lt;code&gt;/admin&lt;/code&gt;，能看用户列表、发邀请、查配置。开启方式是设置 &lt;code&gt;ADMIN_TOKEN&lt;/code&gt;。不要用明文短密码，官方推荐用 Argon2 哈希。生成方法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker run --rm -it vaultwarden/server /vaultwarden hash
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;按提示输入你的管理员密码，它会输出一段 &lt;code&gt;$argon2id$...&lt;/code&gt; 开头的哈希值，填进 Compose：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;      ADMIN_TOKEN: &quot;$argon2id$v=19$m=65540,t=3,p=4$...&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;重启后访问 &lt;code&gt;https://vault.example.com/admin&lt;/code&gt;，用刚设置的管理员密码进入。注意这个后台权限极高，能直接删用户，令牌本身要当主密码同等级别保管。更进一步的访问控制思路见 &lt;a href=&quot;/posts/selfhost-security-access/&quot;&gt;自建服务安全加固：最小暴露与访问控制&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;常用配置项汇总：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;环境变量&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;推荐值&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;DOMAIN&lt;/td&gt;
&lt;td&gt;对外访问地址&lt;/td&gt;
&lt;td&gt;https://vault.example.com&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SIGNUPS_ALLOWED&lt;/td&gt;
&lt;td&gt;是否开放注册&lt;/td&gt;
&lt;td&gt;建号后改 false&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;INVITATIONS_ALLOWED&lt;/td&gt;
&lt;td&gt;是否允许邀请加入组织&lt;/td&gt;
&lt;td&gt;按需，默认 false&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ADMIN_TOKEN&lt;/td&gt;
&lt;td&gt;管理后台令牌&lt;/td&gt;
&lt;td&gt;Argon2 哈希值&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SMTP_HOST 等&lt;/td&gt;
&lt;td&gt;邮件发送（邀请、验证码）&lt;/td&gt;
&lt;td&gt;有邮箱需求再配&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;IP_HEADER&lt;/td&gt;
&lt;td&gt;反代后获取真实 IP 的请求头&lt;/td&gt;
&lt;td&gt;默认 X-Real-IP 即可&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;客户端接入：全平台用官方 Bitwarden&lt;/h2&gt;
&lt;p&gt;Vaultwarden 最大的好处是不用装任何第三方客户端，&lt;strong&gt;Bitwarden 官方客户端全部原生支持自托管&lt;/strong&gt;：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;平台&lt;/th&gt;
&lt;th&gt;客户端&lt;/th&gt;
&lt;th&gt;接入方式&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Windows / macOS / Linux&lt;/td&gt;
&lt;td&gt;Bitwarden 桌面端&lt;/td&gt;
&lt;td&gt;登录界面点「自托管」，填服务器地址&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;iOS / Android&lt;/td&gt;
&lt;td&gt;Bitwarden App&lt;/td&gt;
&lt;td&gt;登录页右上角设置 → 自托管服务器地址&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;浏览器&lt;/td&gt;
&lt;td&gt;Bitwarden 扩展&lt;/td&gt;
&lt;td&gt;设置 → 自托管环境，填 https://vault.example.com&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;网页&lt;/td&gt;
&lt;td&gt;直接打开域名&lt;/td&gt;
&lt;td&gt;Web Vault，无需安装&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;每个客户端第一次登录时，在输邮箱之前先找到「自托管 / Self-hosted」选项，把服务器地址填成你的域名，再正常登录。之后自动填充、同步、指纹/面容解锁都与官方云完全一致。&lt;/p&gt;
&lt;p&gt;进阶玩法：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;两步验证&lt;/strong&gt;：在 Web 端账户设置里开 TOTP 两步验证，并保存好恢复代码；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;家庭共享&lt;/strong&gt;：Web 端新建「组织」，把家人邀请进来，共享文件夹里的密码全家可用，个人条目仍各自私密；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;紧急访问/导出&lt;/strong&gt;：定期在 Web 端导出一份加密备份（选「密码保护导出」），离线保存，作为最后的保险。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;从旧密码管理方式迁过来&lt;/h2&gt;
&lt;p&gt;大多数人不是从零开始用密码库的，密码散落在浏览器、备忘录或者另一个密码管理器里。迁移到 Vaultwarden 的路径很顺滑：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;从浏览器导出&lt;/strong&gt;：Chrome / Edge / Firefox 的密码管理页面都能导出 CSV 明文文件；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;在 Web Vault 里导入&lt;/strong&gt;：「工具 → 导入数据」，格式选对应的浏览器或通用 CSV，一次性全部灌进来；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;整理&lt;/strong&gt;：导入后按网站逐个登录验证，顺手把弱密码、重复密码全改掉——迁移是最好的「密码卫生大扫除」时机，平时没动力干这件事；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;销毁导出文件&lt;/strong&gt;：CSV 是明文，导完确认无误后立即彻底删除，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;不要让它躺在下载文件夹里&amp;lt;/span&amp;gt;，那等于把全部密码明文放在桌面上。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;另外两个值得知道的功能：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Bitwarden Send&lt;/strong&gt;：需要临时把一段文本或一个文件安全地发给别人时，在客户端里建一个 Send，生成带密码和过期时间的链接，对方打开即焚，比聊天软件里直接发密码体面得多；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;密码健康报告&lt;/strong&gt;：Web Vault 的「报告」里有弱密码、重复密码、已泄露密码检查（泄露检查会联网查询公开泄露库的哈希，介意的话可以不用），每季度跑一遍，慢慢把老账号的密码都换成随机生成的强密码。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;给家人接入时的建议姿势：先在自己的账号里把组织和共享文件夹建好，再邀请家人注册（临时开注册或用管理后台邀请），手把手教他们在手机上装好 App 并开启生物识别解锁。密码库的推广难点从来不是技术，是让家人养成「新密码随手存进去」的习惯，前两周多提醒几次就好。&lt;/p&gt;
&lt;h2&gt;备份：这一个目录不能丢&lt;/h2&gt;
&lt;p&gt;Vaultwarden 的备份异常简单也异常重要：停容器或不停容器，把整个 &lt;code&gt;vw-data&lt;/code&gt; 目录打包带走即可。但注意 SQLite 在写入瞬间直接拷贝可能拷到一半状态，最稳妥的做法是先 &lt;code&gt;docker compose stop&lt;/code&gt; 再打包，或者用 sqlite3 的 &lt;code&gt;.backup&lt;/code&gt; 命令做热备。完整的定时备份脚本和异地保存方案见 &lt;a href=&quot;/posts/selfhost-backup-migration/&quot;&gt;自建服务备份与迁移实战&lt;/a&gt;，请务必把这个目录纳入其中——&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;密码库是所有自建服务里唯一「丢了就真的全完了」的数据&amp;lt;/span&amp;gt;。&lt;/p&gt;
&lt;h2&gt;常见问题与排障&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. 打开页面点注册/登录没反应或报错&lt;/strong&gt;
先查是不是 HTTPS：地址栏必须是 &lt;code&gt;https://&lt;/code&gt; 且证书有效。再查 &lt;code&gt;DOMAIN&lt;/code&gt; 环境变量是否与实际访问地址完全一致，不一致会导致部分请求被重定向到错误地址。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. 客户端提示无法连接服务器&lt;/strong&gt;
确认客户端里填的是自托管地址而不是用的官方账号体系；手机端还要检查 App 是否被系统省电策略限制后台。反代侧确认 NPM 里这条 Host 开了 WebSocket 支持，新版客户端的实时同步（增删密码立即推送到其他设备）依赖它。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. 图标不显示、附件上传失败&lt;/strong&gt;
网站图标抓取走的是服务端出网，VPS 出站受限时会失败，不影响核心功能。附件失败先查 &lt;code&gt;vw-data&lt;/code&gt; 目录权限和磁盘空间，再查 NPM 是否限制了请求体大小，可在 NPM 的高级配置里加 &lt;code&gt;client_max_body_size 50m;&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. 忘了管理员令牌&lt;/strong&gt;
改 Compose 里的 &lt;code&gt;ADMIN_TOKEN&lt;/code&gt; 为新的明文或哈希，重启容器即可重置。注意这同时说明：能碰到服务器的人就能重置一切，服务器本身的安全才是根。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. 登录时提示设备验证邮件收不到&lt;/strong&gt;
新设备登录验证依赖邮件配置。没配 SMTP 时，可以在管理后台关闭新设备验证要求，或者干脆把 SMTP 配好——自建服务里凡是涉及账号的，配一个发信邮箱都值得。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;6. 一台设备改了密码，其他设备迟迟不同步&lt;/strong&gt;
先确认各客户端登录的都是同一个自托管地址（有人会误连到官方云，账号同名但数据完全两套）；再检查服务器时间是否准确，时间漂移会导致同步令牌校验异常；最后在客户端里手动下拉刷新一次。反代层如果给 API 路径加了缓存规则，也会造成这种假象，密码库这类动态服务不要进任何缓存。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;7. 能不能在库里存通行密钥（Passkey）&lt;/strong&gt;
可以。Bitwarden 客户端支持把网站的 Passkey 直接存进密码库，Vaultwarden 作为服务端完整兼容。在支持 Passkey 的网站上注册时选「保存到 Bitwarden」即可，之后在任何登录了你自建库的设备上都能调用。把 Passkey 和密码放在同一个库里管理，省去了再单独维护一套凭据的麻烦。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;8. 升级之后打不开，先别慌&lt;/strong&gt;
Vaultwarden 升级偶尔会做数据库结构迁移，第一次启动慢是正常的，看日志等它跑完。真起不来就回滚：停容器，把镜像 tag 换回旧版本号，再把备份的 &lt;code&gt;vw-data&lt;/code&gt; 放回去启动。所以升级前的动作永远是先备份、再 pull，这句话在本系列里已经出现很多次了，对密码库尤其成立。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;Vaultwarden 是投入产出比最高的自建服务之一：一个容器、几十 MB 内存，换来全平台密码同步和完整的数据自主权。部署本身十分钟的事，真正的功夫在规矩上——HTTPS 先行、注册随开随关、管理员令牌用哈希、主密码足够长、&lt;code&gt;vw-data&lt;/code&gt; 必须备份。这几条守住了，它就是你所有自建服务里最让人安心的一个。&lt;/p&gt;
</content:encoded></item><item><title>SQL 基础速成：建表、增删改查与常用语法</title><link>https://www.anexns.cloudns.org/posts/sql-basics-crud/</link><guid isPermaLink="true">https://www.anexns.cloudns.org/posts/sql-basics-crud/</guid><description>用一张用户表把 SQL 的核心语法一次练完：建表与数据类型、INSERT、SELECT 查询、WHERE 过滤、排序分页、UPDATE、DELETE，以及聚合统计和多表 JOIN 入门，PostgreSQL 与 MySQL 通用。</description><pubDate>Sun, 15 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;这一篇练什么&lt;/h2&gt;
&lt;p&gt;不管你最后用 PostgreSQL 还是 MySQL，日常打交道的都是同一套 SQL 语言——先选哪个库的问题已经在 &lt;a href=&quot;/posts/database-choosing-guide/&quot;&gt;《数据库怎么选》&lt;/a&gt; 里解决了，这一篇只管把手练熟。我们用上一篇 &lt;a href=&quot;/posts/database-docker-quickstart/&quot;&gt;《用 Docker 快速搭建三大数据库》&lt;/a&gt; 里建好的环境，围绕一张最典型的用户表，把建表、增、删、改、查、排序、聚合、关联全部走一遍。&lt;/p&gt;
&lt;p&gt;文中 SQL 以 PostgreSQL 为主演示，MySQL 差异会随文标注；两边 95% 的基础语法是通用的。先连进 PostgreSQL：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker exec -it lab-postgres psql -U appuser -d appdb
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;记住一条贯穿全文的核心原则：&amp;lt;span style=&quot;color:#38bdf8&quot;&amp;gt;&lt;strong&gt;先用 SELECT 把要动的数据查出来确认，再执行 UPDATE 或 DELETE&lt;/strong&gt;&amp;lt;/span&amp;gt;。这一个习惯能挡掉绝大多数线上事故。&lt;/p&gt;
&lt;h2&gt;建表：先把结构定清楚&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;CREATE TABLE users (
    id          BIGSERIAL PRIMARY KEY,
    username    VARCHAR(50)  NOT NULL UNIQUE,
    email       VARCHAR(100) NOT NULL,
    age         SMALLINT,
    balance     NUMERIC(10, 2) NOT NULL DEFAULT 0,
    created_at  TIMESTAMPTZ  NOT NULL DEFAULT now()
);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;这段定义里包含了建表最常用的元素：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;元素&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;BIGSERIAL PRIMARY KEY&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;主键，自增&lt;/td&gt;
&lt;td&gt;PostgreSQL 写法；MySQL 写 &lt;code&gt;BIGINT AUTO_INCREMENT PRIMARY KEY&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;VARCHAR(n)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;变长字符串&lt;/td&gt;
&lt;td&gt;用户名、邮箱这类长度可控的文本&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;NOT NULL&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;不允许为空&lt;/td&gt;
&lt;td&gt;关键字段务必加，空值是 bug 温床&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;UNIQUE&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;唯一约束&lt;/td&gt;
&lt;td&gt;用户名、邮箱防重复靠它，不要只靠代码判断&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;NUMERIC(10, 2)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;精确小数&lt;/td&gt;
&lt;td&gt;钱必须用它，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;绝不能用 FLOAT/DOUBLE 存金额&lt;/strong&gt;&amp;lt;/span&amp;gt;，浮点误差迟早对不上账&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;DEFAULT&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;默认值&lt;/td&gt;
&lt;td&gt;余额默认 0、创建时间默认当前时间&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;TIMESTAMPTZ&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;带时区时间&lt;/td&gt;
&lt;td&gt;PostgreSQL 推荐；MySQL 对应 &lt;code&gt;DATETIME&lt;/code&gt; / &lt;code&gt;TIMESTAMP&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;常用数据类型速记：整数用 &lt;code&gt;INT&lt;/code&gt; / &lt;code&gt;BIGINT&lt;/code&gt;，短文本用 &lt;code&gt;VARCHAR&lt;/code&gt;，长文本用 &lt;code&gt;TEXT&lt;/code&gt;，布尔用 &lt;code&gt;BOOLEAN&lt;/code&gt;，日期用 &lt;code&gt;DATE&lt;/code&gt;，时间用带时区的 &lt;code&gt;TIMESTAMPTZ&lt;/code&gt;，半结构化数据 PostgreSQL 用 &lt;code&gt;JSONB&lt;/code&gt;、MySQL 用 &lt;code&gt;JSON&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;删表和改表：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ALTER TABLE users ADD COLUMN phone VARCHAR(20);       -- 加字段
ALTER TABLE users ALTER COLUMN age TYPE INT;          -- 改类型（MySQL 用 MODIFY）
ALTER TABLE users DROP COLUMN phone;                  -- 删字段
DROP TABLE users;                                     -- 删整张表，数据全没，慎用
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;增：INSERT 插入数据&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;-- 插入一行
INSERT INTO users (username, email, age, balance)
VALUES (&apos;zhangsan&apos;, &apos;zhangsan@example.com&apos;, 28, 100.50);

-- 一次插入多行，效率比逐条插高得多
INSERT INTO users (username, email, age, balance) VALUES
    (&apos;lisi&apos;,    &apos;lisi@example.com&apos;,    35, 200.00),
    (&apos;wangwu&apos;,  &apos;wangwu@example.com&apos;,  22, 50.25),
    (&apos;zhaoliu&apos;, &apos;zhaoliu@example.com&apos;, 41, 0);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;插入后想拿到自增 id：PostgreSQL 用 &lt;code&gt;INSERT ... RETURNING id;&lt;/code&gt;，MySQL 用 &lt;code&gt;SELECT LAST_INSERT_ID();&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;查：SELECT 是 SQL 的半壁江山&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;-- 查全部列（练习可以，生产代码里别用 *，列名写全）
SELECT * FROM users;

-- 只查需要的列
SELECT id, username, balance FROM users;

-- WHERE 过滤
SELECT * FROM users WHERE age &amp;gt;= 30;
SELECT * FROM users WHERE username = &apos;lisi&apos;;
SELECT * FROM users WHERE age BETWEEN 20 AND 40;
SELECT * FROM users WHERE username IN (&apos;lisi&apos;, &apos;wangwu&apos;);
SELECT * FROM users WHERE email LIKE &apos;%@example.com&apos;;

-- 多条件组合：AND 比 OR 优先，复杂条件加括号
SELECT * FROM users WHERE age &amp;gt;= 30 AND balance &amp;gt; 0;

-- 排序与分页
SELECT * FROM users ORDER BY balance DESC LIMIT 10;
SELECT * FROM users ORDER BY id LIMIT 10 OFFSET 10;   -- 第二页

-- 去重
SELECT DISTINCT age FROM users;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;几个高频细节：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;字符串用&lt;strong&gt;单引号&lt;/strong&gt;，双引号在 PostgreSQL 里是标识符（表名列名）的引号，别混。&lt;/li&gt;
&lt;li&gt;判断空值只能用 &lt;code&gt;age IS NULL&lt;/code&gt; / &lt;code&gt;age IS NOT NULL&lt;/code&gt;，写 &lt;code&gt;age = NULL&lt;/code&gt; 永远查不到任何行。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;LIKE&lt;/code&gt; 的 &lt;code&gt;%&lt;/code&gt; 匹配任意长度字符，&lt;code&gt;_&lt;/code&gt; 匹配单个字符；前缀模糊（&lt;code&gt;LIKE &apos;zhang%&apos;&lt;/code&gt;）能走索引，&amp;lt;span style=&quot;color:#f87171&quot;&amp;gt;&lt;strong&gt;&lt;code&gt;LIKE &apos;%zhang&apos;&lt;/code&gt; 这种前后都带 % 的写法走不了普通索引&lt;/strong&gt;&amp;lt;/span&amp;gt;，数据量大时就是全表扫。&lt;/li&gt;
&lt;li&gt;分页深翻（比如 &lt;code&gt;OFFSET 100000&lt;/code&gt;）性能很差，数据库要先数出前十万行再丢掉。数据量大时改用「记住上一页最后一个 id，&lt;code&gt;WHERE id &amp;gt; ? ORDER BY id LIMIT 10&lt;/code&gt;」的游标分页。&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;改：UPDATE 必须带 WHERE&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;UPDATE users SET balance = balance + 50 WHERE username = &apos;lisi&apos;;
UPDATE users SET age = 29, email = &apos;new@example.com&apos; WHERE id = 1;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::warning
&lt;code&gt;UPDATE&lt;/code&gt; 和 &lt;code&gt;DELETE&lt;/code&gt; 不带 &lt;code&gt;WHERE&lt;/code&gt; 就是&lt;strong&gt;全表生效&lt;/strong&gt;，没有回收站、没有撤销键。手滑一次，全表用户的余额都会被改掉。养成两个习惯：第一，先把同样的条件用 &lt;code&gt;SELECT&lt;/code&gt; 查一遍确认影响行数；第二，重要操作先开事务（见下文），确认无误再提交。
:::&lt;/p&gt;
&lt;p&gt;事务的基本用法（PostgreSQL 与 MySQL InnoDB 都支持）：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;BEGIN;
UPDATE users SET balance = balance - 100 WHERE username = &apos;zhangsan&apos;;
UPDATE users SET balance = balance + 100 WHERE username = &apos;lisi&apos;;
-- 两条都成功才提交；任何一步不对，用 ROLLBACK 全部撤销
COMMIT;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;转账这类「要么全成、要么全不成」的操作，必须放进同一个事务，这正是关系型数据库 ACID 的核心价值。&lt;/p&gt;
&lt;h2&gt;删：DELETE 与 TRUNCATE 的区别&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;DELETE FROM users WHERE username = &apos;zhaoliu&apos;;   -- 删符合条件的行
DELETE FROM users;                              -- 删全部行（逐行删，可回滚）
TRUNCATE TABLE users;                           -- 清空整表，更快，但多数情况下不能回滚
&lt;/code&gt;&lt;/pre&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;方式&lt;/th&gt;
&lt;th&gt;速度&lt;/th&gt;
&lt;th&gt;能否回滚&lt;/th&gt;
&lt;th&gt;备注&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;DELETE ... WHERE&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;慢&lt;/td&gt;
&lt;td&gt;事务内可回滚&lt;/td&gt;
&lt;td&gt;日常删数据用它&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;DELETE&lt;/code&gt; 无条件&lt;/td&gt;
&lt;td&gt;慢&lt;/td&gt;
&lt;td&gt;事务内可回滚&lt;/td&gt;
&lt;td&gt;逐行删除，产生大量日志&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;TRUNCATE&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;快&lt;/td&gt;
&lt;td&gt;PostgreSQL 事务内可回滚，MySQL 不可&lt;/td&gt;
&lt;td&gt;清空测试表用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;DROP TABLE&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;快&lt;/td&gt;
&lt;td&gt;不可&lt;/td&gt;
&lt;td&gt;连表结构一起删&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;软删除也是常见做法：给表加 &lt;code&gt;deleted_at&lt;/code&gt; 字段，删除时只更新这个字段，查询时过滤掉。数据可恢复、能审计，代价是所有查询都要记得带条件。&lt;/p&gt;
&lt;h2&gt;聚合统计：GROUP BY 入门&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;SELECT COUNT(*) FROM users;                              -- 总行数
SELECT COUNT(*) FROM users WHERE age &amp;gt;= 30;              -- 条件计数
SELECT AVG(balance), MAX(balance), MIN(balance) FROM users;  -- 平均/最大/最小
SELECT age, COUNT(*) AS cnt FROM users GROUP BY age ORDER BY cnt DESC;  -- 按年龄分组数人
SELECT age, COUNT(*) AS cnt FROM users GROUP BY age HAVING COUNT(*) &amp;gt;= 2; -- 对分组结果再过滤
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;记住分工：&lt;code&gt;WHERE&lt;/code&gt; 在分组前过滤行，&lt;code&gt;HAVING&lt;/code&gt; 在分组后过滤组，两者别用反。&lt;/p&gt;
&lt;h2&gt;关联查询：JOIN 入门&lt;/h2&gt;
&lt;p&gt;再建一张订单表练关联：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;CREATE TABLE orders (
    id         BIGSERIAL PRIMARY KEY,
    user_id    BIGINT NOT NULL REFERENCES users(id),
    amount     NUMERIC(10, 2) NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- 查每个订单对应的用户名
SELECT o.id, u.username, o.amount
FROM orders o
JOIN users u ON o.user_id = u.id
ORDER BY o.id;

-- 查每个用户的订单总额，没下过单的用户也要出现（LEFT JOIN，结果为 NULL）
SELECT u.username, COALESCE(SUM(o.amount), 0) AS total
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
GROUP BY u.username;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;JOIN&lt;/code&gt;（内连接）只返回两边都匹配的行，&lt;code&gt;LEFT JOIN&lt;/code&gt; 保左表全部行、右表没匹配的补 NULL——报表统计里后者用得更多。索引和 JOIN 的性能关系，在 &lt;a href=&quot;/posts/postgresql-index-optimization/&quot;&gt;《PostgreSQL 索引与查询优化入门》&lt;/a&gt; 和 &lt;a href=&quot;/posts/mysql-index-slow-query/&quot;&gt;《MySQL 索引与慢查询优化》&lt;/a&gt; 里展开。&lt;/p&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Q：执行 SQL 报语法错误，不知道错在哪？&lt;/strong&gt;
A：先把语句拆开逐段看：关键字拼写、逗号、引号配对是最常见三处。psql 里可以用 &lt;code&gt;\e&lt;/code&gt; 把上一条语句调回编辑器改，MySQL 客户端里按上箭头调出历史命令修改。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：&lt;code&gt;SELECT * FROM users WHERE age = &apos;28&apos;&lt;/code&gt; 年龄是字符串也能查？&lt;/strong&gt;
A：多数数据库会做隐式类型转换，能查出结果，但会让索引失效。比较时类型保持一致，数字就写数字。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：中文存进去变问号或乱码？&lt;/strong&gt;
A：基本是字符集问题。MySQL 确保库、表、连接都是 utf8mb4（上一篇的 Compose 已钉死）；PostgreSQL 建库时用 UTF8 编码，一般不出这问题。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Q：自增 id 删除一行后会复用吗？&lt;/strong&gt;
A：不会。PostgreSQL 的序列和 MySQL 的自增值都是只进不退，id 出现空洞完全正常，不要拿 id 连续性做业务逻辑。&lt;/p&gt;
&lt;h2&gt;小结&lt;/h2&gt;
&lt;p&gt;这一篇的骨架就五件事：&lt;code&gt;CREATE TABLE&lt;/code&gt; 定结构、&lt;code&gt;INSERT&lt;/code&gt; 进数据、&lt;code&gt;SELECT ... WHERE ... ORDER BY ... LIMIT&lt;/code&gt; 取数据、&lt;code&gt;UPDATE&lt;/code&gt; / &lt;code&gt;DELETE&lt;/code&gt; 永远带 &lt;code&gt;WHERE&lt;/code&gt;、聚合靠 &lt;code&gt;GROUP BY&lt;/code&gt;、多表靠 &lt;code&gt;JOIN&lt;/code&gt;。把这套在练功房里敲熟，后面学哪个数据库的专属功能都有底。下一篇进入 PostgreSQL 正题，从安装与初始配置开始。&lt;/p&gt;
</content:encoded></item></channel></rss>