<?xml version="1.0" encoding="UTF-8"?><rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>cleeate 的博客</title><description>个人博客。</description><link>https://npq.kdns.fr/</link><language>zh-cn</language><item><title>把 Fuwari 从 Astro 移植到 Hugo：过程、踩坑与经验</title><link>https://npq.kdns.fr/posts/hugo-fuwari-port/</link><guid isPermaLink="true">https://npq.kdns.fr/posts/hugo-fuwari-port/</guid><description>记录把 Fuwari 主题从 Astro 移植到 Hugo 的完整过程：模板重写、构建脚本、以及 return 单语句、paginate、contentDir、图标、文档同步这些真实的坑。</description><pubDate>Fri, 13 Nov 2026 00:00:00 GMT</pubDate><content:encoded><![CDATA[<p>Fuwari 是我很喜欢的一个博客主题，原版是基于 Astro 的。用了一段时间后，我决定把它整体移植到 Hugo，这篇文章记录整个过程和踩过的坑，给想做类似事情的人参考。</p>

<h2 id="为什么移植到-hugo">为什么移植到 Hugo<a class="anchor" href="#%e4%b8%ba%e4%bb%80%e4%b9%88%e7%a7%bb%e6%a4%8d%e5%88%b0-hugo"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<ul>
<li><strong>Hugo 是单个二进制</strong>，不需要 Node 运行时就能构建，部署环境更简单。</li>
<li><strong>构建快</strong>：这个站 11 个页面，Hugo 构建不到 0.2 秒。</li>
<li><strong>模板能力够用</strong>：Hugo 的 partial + 模板函数基本能还原 Astro 组件的逻辑。</li>
</ul>
<p>移植不是”翻译”那么简单，Astro 的组件模型、配置体系、构建流程都和 Hugo 不一样，很多地方要重新设计。</p>

<h2 id="移植范围">移植范围<a class="anchor" href="#%e7%a7%bb%e6%a4%8d%e8%8c%83%e5%9b%b4"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>原仓库的 Astro 源码全部移除，替换成 Hugo 实现：</p>
<ul>
<li><code>layouts/</code>：Astro 组件（<code>.astro</code>）全部改写成 Hugo 的 partial / 模板</li>
<li><code>hugo.toml</code>：替代原来的 <code>src/config.ts</code> 和 <code>astro.config.mjs</code></li>
<li><code>scripts/</code>：保留构建辅助脚本（内容预处理、Tailwind CSS 编译）</li>
<li><code>data/icons.json</code>：图标库（Iconify）</li>
<li><code>src/content/</code>：文章与页面内容</li>
</ul>

<h2 id="几个核心差异">几个核心差异<a class="anchor" href="#%e5%87%a0%e4%b8%aa%e6%a0%b8%e5%bf%83%e5%b7%ae%e5%bc%82"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>

<h3 id="1-配置从-typescript-变成-toml">1. 配置从 TypeScript 变成 TOML<a class="anchor" href="#1-%e9%85%8d%e7%bd%ae%e4%bb%8e-typescript-%e5%8f%98%e6%88%90-toml"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h3>
<p>Astro 版所有配置都在 <code>src/config.ts</code> 里，用 TypeScript 对象写。Hugo 版拆到了 <code>hugo.toml</code>：站点信息、<code>[params.profile]</code>（个人资料）、<code>[params.navbarLinks]</code>（导航）、<code>[frontmatter]</code>（日期字段映射）等。</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="toml" class="wrap" style="--ecMaxLine:41ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">[</span><span style="--0:#B392F0;--1:#B392F0">params</span><span style="--0:#E1E4E8;--1:#E1E4E8">.</span><span style="--0:#B392F0;--1:#B392F0">profile</span><span style="--0:#E1E4E8;--1:#E1E4E8">]</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">avatar = </span><span style="--0:#9ECBFF;--1:#9ECBFF">"https://github.com/cleeate.png"</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">3</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">name = </span><span style="--0:#9ECBFF;--1:#9ECBFF">"cleeate"</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">4</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">bio = </span><span style="--0:#9ECBFF;--1:#9ECBFF">"个人博客。"</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">5</div></div><div class="code">
</div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">6</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">[[</span><span style="--0:#B392F0;--1:#B392F0">params</span><span style="--0:#E1E4E8;--1:#E1E4E8">.</span><span style="--0:#B392F0;--1:#B392F0">profile</span><span style="--0:#E1E4E8;--1:#E1E4E8">.</span><span style="--0:#B392F0;--1:#B392F0">links</span><span style="--0:#E1E4E8;--1:#E1E4E8">]]</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">7</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">name = </span><span style="--0:#9ECBFF;--1:#9ECBFF">"GitHub"</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">8</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">icon = </span><span style="--0:#9ECBFF;--1:#9ECBFF">"fa6-brands:github"</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">9</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">url = </span><span style="--0:#9ECBFF;--1:#9ECBFF">"https://github.com/cleeate"</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>

<h3 id="2-内容目录不是-content">2. 内容目录不是 <code>content/</code><a class="anchor" href="#2-%e5%86%85%e5%ae%b9%e7%9b%ae%e5%bd%95%e4%b8%8d%e6%98%af-content"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h3>
<p>这是最容易踩的坑之一。Hugo 默认读 <code>content/</code>，但这个主题的 <code>hugo.toml</code> 里写了：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="toml" class="wrap" style="--ecMaxLine:38ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">contentDir = </span><span style="--0:#9ECBFF;--1:#9ECBFF">".hugo/content"</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">staticDir = [</span><span style="--0:#9ECBFF;--1:#9ECBFF">"public"</span><span style="--0:#E1E4E8;--1:#E1E4E8">, </span><span style="--0:#9ECBFF;--1:#9ECBFF">".hugo/static"</span><span style="--0:#E1E4E8;--1:#E1E4E8">]</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>也就是说，<strong>Hugo 不直接读 <code>src/content/</code></strong>。构建时先由 <code>scripts/prepare-content.mjs</code> 把 <code>src/content/</code> 复制并预处理到 <code>.hugo/content/</code>（丢弃 <code>config.ts</code>、预渲染代码块），Hugo 再从那里读。</p>
<p>所以如果手动跑 <code>hugo</code> 而没先跑 <code>prepare-content</code>，<code>hugo list all</code> 只会输出一个表头、一篇文章都没有。这个坑我第一次就踩了。</p>

<h3 id="3-return-每个-partial-只能有一个">3. <code>return</code> 每个 partial 只能有一个<a class="anchor" href="#3-return-%e6%af%8f%e4%b8%aa-partial-%e5%8f%aa%e8%83%bd%e6%9c%89%e4%b8%80%e4%b8%aa"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h3>
<p>这是最坑的一个。Hugo 的 <code>return</code> 语句有个硬限制：<strong>每个 partial 文件只允许一个 <code>return</code>，且必须在最后</strong>。原 Astro 移植版里有几个递归 partial（<code>sectionize-recurse.html</code>、<code>github-cards.html</code>）在 <code>if/else</code> 分支里各写了一个 <code>return</code>，构建时直接崩：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="plaintext" class="wrap" style="--ecMaxLine:58ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#e1e4e8;--1:#e1e4e8">at &#x3C;return>: wrong number of args for return: want 0 got 1</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>这个错误很迷惑，因为 <code>return $var</code> 看起来完全合法。原因就是 Hugo 只认”最后一个 return”，中间的分支 return 会被当成普通函数调用。解决办法是重构成”变量累积 + 末尾单一 return”：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="go" class="wrap" style="--ecMaxLine:64ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">&#123;&#123;</span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8"> $result </span><span style="--0:#F97583;--1:#F97583">:=</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">""</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8">}}</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">&#123;&#123;</span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">if</span><span style="--0:#E1E4E8;--1:#E1E4E8"> not $heads </span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8">}}</span></div></div><div class="ec-line" style="--ecIndent:2ch"><div class="gutter"><div class="ln" aria-hidden="true">3</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">  </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">&#123;&#123;</span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#99A0A6;--1:#99A0A6">/* 处理 */</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8">}}</span></div></div><div class="ec-line" style="--ecIndent:2ch"><div class="gutter"><div class="ln" aria-hidden="true">4</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">  </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">&#123;&#123;</span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8"> $result </span><span style="--0:#F97583;--1:#F97583">=</span><span style="--0:#E1E4E8;--1:#E1E4E8"> $out </span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8">}}</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">5</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">&#123;&#123;</span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">else</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8">}}</span></div></div><div class="ec-line" style="--ecIndent:2ch"><div class="gutter"><div class="ln" aria-hidden="true">6</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">  </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">&#123;&#123;</span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#99A0A6;--1:#99A0A6">/* 处理 + 递归 */</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8">}}</span></div></div><div class="ec-line" style="--ecIndent:2ch"><div class="gutter"><div class="ln" aria-hidden="true">7</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">  </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">&#123;&#123;</span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8"> $result </span><span style="--0:#F97583;--1:#F97583">=</span><span style="--0:#E1E4E8;--1:#E1E4E8"> partial </span><span style="--0:#9ECBFF;--1:#9ECBFF">"sectionize-recurse.html"</span><span style="--0:#E1E4E8;--1:#E1E4E8"> (dict </span><span style="--0:#F97583;--1:#F97583">...</span><span style="--0:#E1E4E8;--1:#E1E4E8">) </span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8">}}</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">8</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">&#123;&#123;</span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8"> end </span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8">}}</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">9</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">&#123;&#123;</span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">return</span><span style="--0:#E1E4E8;--1:#E1E4E8"> $result </span><span style="--0:#F97583;--1:#F97583">-</span><span style="--0:#E1E4E8;--1:#E1E4E8">}}</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>

<h3 id="4-paginate-在-hugo-0128-已移除">4. <code>paginate</code> 在 Hugo 0.128+ 已移除<a class="anchor" href="#4-paginate-%e5%9c%a8-hugo-0128-%e5%b7%b2%e7%a7%bb%e9%99%a4"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h3>
<p>旧配置里的 <code>paginate = 8</code> 在新版 Hugo 会直接报错（不是警告）：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="plaintext" class="wrap" style="--ecMaxLine:82ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#e1e4e8;--1:#e1e4e8">site config key paginate was deprecated in Hugo v0.128.0 and subsequently removed.</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>要改成：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="toml" class="wrap" style="--ecMaxLine:13ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">[</span><span style="--0:#B392F0;--1:#B392F0">pagination</span><span style="--0:#E1E4E8;--1:#E1E4E8">]</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">pagerSize = </span><span style="--0:#79B8FF;--1:#79B8FF">8</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>

<h3 id="5-图标要显式注册">5. 图标要显式注册<a class="anchor" href="#5-%e5%9b%be%e6%a0%87%e8%a6%81%e6%98%be%e5%bc%8f%e6%b3%a8%e5%86%8c"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h3>
<p>主题用的是 Iconify 图标，但渲染时只认 <code>data/icons.json</code> 里<strong>已存在</strong>的图标——没有的话静默不渲染（不报错）。所以导航项配了 <code>icon = &quot;material-symbols:home&quot;</code>，如果图标库里没有 <code>material-symbols:home</code>，那个图标就是空白。</p>
<p>补图标的方式是从 Iconify API 拉 SVG body 合并进 <code>data/icons.json</code>：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="plaintext" class="wrap" style="--ecMaxLine:90ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#e1e4e8;--1:#e1e4e8">https://api.iconify.design/material-symbols.json?icons=archive,build-outline,image-outline</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>

<h2 id="功能增强">功能增强<a class="anchor" href="#%e5%8a%9f%e8%83%bd%e5%a2%9e%e5%bc%ba"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>移植过程中顺手加了几个原版没有的功能：</p>
<ul>
<li><strong>导航下拉子菜单</strong>：给 <code>navbar.html</code> 和移动端菜单加了 <code>children</code> 渲染，支持”工具 → 图床”这种下拉。桌面端 hover 显示，箭头旋转 + 面板淡入上移的动效。</li>
<li><strong>菜单图标</strong>：每个导航项前面带小图标，和原版 Astro 一致。</li>
<li><strong>单 return 重构</strong>：修掉了上面说的构建崩溃。</li>
</ul>

<h2 id="性能优化">性能优化<a class="anchor" href="#%e6%80%a7%e8%83%bd%e4%bc%98%e5%8c%96"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>移植完做了一次真实的加载分析（Performance API），首屏实际下载 176KB、831ms。做了两个优化：</p>
<ul>
<li><strong>Pagefind 延迟加载</strong>：搜索库从”DOMContentLoaded 立即加载”改成 <code>requestIdleCallback</code> 空闲时加载，不再阻塞首屏。</li>
<li><strong>preload 关键资源</strong>：给 <code>main.css</code> 和正文字体加 <code>&lt;link rel=&quot;preload&quot;&gt;</code>，让浏览器更早抓取。</li>
</ul>
<p>优化后首屏降到 149KB / 764ms。CF Pages 自带 gzip/brotli，HTML 实际传输只有 11.4KB——压缩这块其实已经到位，没必要再折腾 minify。</p>

<h2 id="文档也要跟上">文档也要跟上<a class="anchor" href="#%e6%96%87%e6%a1%a3%e4%b9%9f%e8%a6%81%e8%b7%9f%e4%b8%8a"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>移植最容易忽略的是<strong>文档</strong>。代码全改完了，README 和写作指南里还是”<code>npm create fuwari</code>、编辑 <code>src/config.ts</code>、<code>pnpm dev</code> 在 4321 端口、输出到 <code>./dist/</code>”——全是 Astro 的。这类残留对使用者误导极大。移植时把 README、写作指南、贡献指南都 Hugo 化了一遍，翻译版只保留中英文。</p>

<h2 id="部署">部署<a class="anchor" href="#%e9%83%a8%e7%bd%b2"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<ul>
<li>博客站：Cloudflare Pages，构建命令 <code>pnpm build</code>，输出 <code>public/</code>，Node 22。</li>
<li>主题演示站：GitHub Pages，用 GitHub Actions 自动构建部署。</li>
</ul>

<h2 id="总结">总结<a class="anchor" href="#%e6%80%bb%e7%bb%93"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>Astro → Hugo 的移植，代码量不算大，但<strong>细节坑非常多</strong>：return 单语句限制、paginate 废弃、contentDir 指向生成目录、图标要显式注册、文档残留……每一个都可能让你卡半天。</p>
<p>移植完成后，构建速度和部署简单性都有明显提升，主题功能也完整保留。如果你也想把某个 Astro 主题搬到 Hugo，希望这篇能帮你少踩几个坑。</p>
]]></content:encoded></item><item><title>博客升级：导航栏新增&#39;工具&#39;菜单与图床服务</title><link>https://npq.kdns.fr/posts/tools-gallery-update/</link><guid isPermaLink="true">https://npq.kdns.fr/posts/tools-gallery-update/</guid><description>记录本次博客导航栏的升级：在「文章」和「关于」之间增加「工具」下拉菜单，并接入图床服务。</description><pubDate>Sun, 08 Nov 2026 00:00:00 GMT</pubDate><content:encoded><![CDATA[
<h2 id="本次升级">本次升级<a class="anchor" href="#%e6%9c%ac%e6%ac%a1%e5%8d%87%e7%ba%a7"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>这次给博客加了个导航菜单：<strong>「工具」 &gt; 「图床」</strong>。点开后通过新的标签页打开图床服务（<code>https://gofor.hyperphp.com</code>），不在站内跳转。</p>
<p>新增的菜单放在「文章」和「关于」之间，这样层级关系比较清晰：</p>
<ul>
<li><strong>主页</strong> — 首页</li>
<li><strong>文章 ▶</strong> — 归档、分类、标签、系列</li>
<li><strong>工具 ▶</strong> — <strong>图床</strong>（外链新窗口打开）</li>
<li><strong>关于我</strong> — 关于页面</li>
</ul>

<h2 id="为什么加图床">为什么加图床<a class="anchor" href="#%e4%b8%ba%e4%bb%80%e4%b9%88%e5%8a%a0%e5%9b%be%e5%ba%8a"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>图床是写博客时的刚需。写文章要配图，图床来解决：</p>
<ol>
<li><strong>外链托管</strong>，不用把图片塞进博客仓库</li>
<li><strong>图片压缩与 CDN</strong>，博客页面的加载速度不拖后腿</li>
<li><strong>统一管理</strong>，以后所有文章的图片上传后都能直接引用</li>
</ol>
<p>这个图床是一个基于 PHP 的单文件 S3 兼容存储端点（<code>php-s3-lite</code>），适配常见的 Hosting 环境，目标是轻量部署、直接能用。</p>

<h2 id="技术方案">技术方案<a class="anchor" href="#%e6%8a%80%e6%9c%af%e6%96%b9%e6%a1%88"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>博客用的是 Astro + 自定义 Firefly 主题，导航菜单数据在 <code>src/config/navBarConfig.ts</code> 里维护：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="ts" class="wrap" style="--ecMaxLine:45ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">links.</span><span style="--0:#B392F0;--1:#B392F0">push</span><span style="--0:#E1E4E8;--1:#E1E4E8">({</span></div></div><div class="ec-line" style="--ecIndent:2ch"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">  </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">name: </span><span style="--0:#9ECBFF;--1:#9ECBFF">"工具"</span><span style="--0:#E1E4E8;--1:#E1E4E8">,</span></div></div><div class="ec-line" style="--ecIndent:2ch"><div class="gutter"><div class="ln" aria-hidden="true">3</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">  </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">url: </span><span style="--0:#9ECBFF;--1:#9ECBFF">"#"</span><span style="--0:#E1E4E8;--1:#E1E4E8">,</span></div></div><div class="ec-line" style="--ecIndent:2ch"><div class="gutter"><div class="ln" aria-hidden="true">4</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">  </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">icon: </span><span style="--0:#9ECBFF;--1:#9ECBFF">"material-symbols:build-outline"</span><span style="--0:#E1E4E8;--1:#E1E4E8">,</span></div></div><div class="ec-line" style="--ecIndent:2ch"><div class="gutter"><div class="ln" aria-hidden="true">5</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">  </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">children: [</span></div></div><div class="ec-line" style="--ecIndent:4ch"><div class="gutter"><div class="ln" aria-hidden="true">6</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">    </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">{</span></div></div><div class="ec-line" style="--ecIndent:6ch"><div class="gutter"><div class="ln" aria-hidden="true">7</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">      </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">name: </span><span style="--0:#9ECBFF;--1:#9ECBFF">"图床"</span><span style="--0:#E1E4E8;--1:#E1E4E8">,</span></div></div><div class="ec-line" style="--ecIndent:6ch"><div class="gutter"><div class="ln" aria-hidden="true">8</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">      </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">url: </span><span style="--0:#9ECBFF;--1:#9ECBFF">"https://gofor.hyperphp.com"</span><span style="--0:#E1E4E8;--1:#E1E4E8">,</span></div></div><div class="ec-line" style="--ecIndent:6ch"><div class="gutter"><div class="ln" aria-hidden="true">9</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">      </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">external: </span><span style="--0:#79B8FF;--1:#79B8FF">true</span><span style="--0:#E1E4E8;--1:#E1E4E8">,</span></div></div><div class="ec-line" style="--ecIndent:6ch"><div class="gutter"><div class="ln" aria-hidden="true">10</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">      </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">icon: </span><span style="--0:#9ECBFF;--1:#9ECBFF">"material-symbols:image-outline"</span><span style="--0:#E1E4E8;--1:#E1E4E8">,</span></div></div><div class="ec-line" style="--ecIndent:4ch"><div class="gutter"><div class="ln" aria-hidden="true">11</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">    </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">},</span></div></div><div class="ec-line" style="--ecIndent:2ch"><div class="gutter"><div class="ln" aria-hidden="true">12</div></div><div class="code"><span class="indent"><span style="--0:#E1E4E8;--1:#E1E4E8">  </span></span><span style="--0:#E1E4E8;--1:#E1E4E8">],</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">13</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">});</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>一个细节：子菜单只有一个时，框架默认会把单个子菜单 <strong>塌陷</strong> 成顶级链接。但外链菜单不能塌，否则「工具」菜单就少了一层，所以我改了一下 <code>resolveNavMenuLinks</code>：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="ts" class="wrap" style="--ecMaxLine:69ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#F97583;--1:#F97583">if</span><span style="--0:#E1E4E8;--1:#E1E4E8"> (filteredChildren.</span><span style="--0:#79B8FF;--1:#79B8FF">length</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">===</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">1</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">&#x26;&#x26;</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">!</span><span style="--0:#E1E4E8;--1:#E1E4E8">filteredChildren[</span><span style="--0:#79B8FF;--1:#79B8FF">0</span><span style="--0:#E1E4E8;--1:#E1E4E8">].external) {</span></div></div><div class="ec-line" style="--ecIndent:2ch"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span class="indent">  </span><span style="--0:#F97583;--1:#F97583">return</span><span style="--0:#E1E4E8;--1:#E1E4E8"> filteredChildren[</span><span style="--0:#79B8FF;--1:#79B8FF">0</span><span style="--0:#E1E4E8;--1:#E1E4E8">];</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">3</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">}</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>这样「工具 &gt; 图床」就能正常展开成下拉，而「关于 &gt; 关于我」的语义保持不变。</p>

<h2 id="多语言">多语言<a class="anchor" href="#%e5%a4%9a%e8%af%ad%e8%a8%80"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>新增的菜单文字同步补到了所有语言包：</p>
<table>
  <thead>
      <tr>
          <th>语言</th>
          <th>工具</th>
          <th>图床</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>简体中文</td>
          <td>工具</td>
          <td>图床</td>
      </tr>
      <tr>
          <td>繁體中文</td>
          <td>工具</td>
          <td>圖床</td>
      </tr>
      <tr>
          <td>英语</td>
          <td>Tools</td>
          <td>Image Hosting</td>
      </tr>
      <tr>
          <td>日语</td>
          <td>ツール</td>
          <td>画像ホスティング</td>
      </tr>
      <tr>
          <td>韩语</td>
          <td>도구</td>
          <td>이미지 호스팅</td>
      </tr>
      <tr>
          <td>俄语</td>
          <td>Инструменты</td>
          <td>Хостинг изображений</td>
      </tr>
  </tbody>
</table>

<h2 id="部署流程">部署流程<a class="anchor" href="#%e9%83%a8%e7%bd%b2%e6%b5%81%e7%a8%8b"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>博客的 CI/CD 很简单：</p>
<ol>
<li>修改源码 -&gt; 推送到 GitHub（SSH 被禁，所以通过 GitHub API 的 Git Data 接口实现，不走 <code>git push</code>）</li>
<li>Cloudflare Pages 监听到推送，自动 <code>pnpm run build</code>，生成 <code>dist</code></li>
<li>构建成功后静态网站自动上架</li>
</ol>
<p>本次升级过程中踩了一个坑：<strong>第一次推送时错误地把文件内容 base64 编码了</strong>，导致远端文件乱码，Pages 构建失败。发现后重新以原始文本推送，部署恢复成功。</p>

<h2 id="总结">总结<a class="anchor" href="#%e6%80%bb%e7%bb%93"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>这次升级的主要改动是加了「工具」菜单和图床入口。图床服务刚上线，后续我会继续优化，比如增加更多上传功能和更好的 CDN 加速。</p>
<p>如果你有什么有趣的工具想让我加到菜单里，欢迎在评论区告诉我。</p>
]]></content:encoded></item><item><title>新博客上线：AstroPaper 7、分仓库部署与一次滚动修复</title><link>https://npq.kdns.fr/posts/astropaper-7-deploy/</link><guid isPermaLink="true">https://npq.kdns.fr/posts/astropaper-7-deploy/</guid><description>新博客上线记录：AstroPaper 7、分仓库部署、滚动修复与两次部署踩坑。</description><pubDate>Sat, 07 Nov 2026 00:00:00 GMT</pubDate><content:encoded><![CDATA[<p>新博客上线了，就在 <a href="https://cleeate.github.io/">cleeate.github.io</a>。这篇记录它是怎么搭起来的，以及上线当天修掉的两个问题。</p>

<h2 id="搭了什么">搭了什么<a class="anchor" href="#%e6%90%ad%e4%ba%86%e4%bb%80%e4%b9%88"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<ul>
<li><strong>AstroPaper 7.1.0 / Astro 7.4.5</strong>，Node 24、pnpm，语言 zh-CN、时区 Asia/Shanghai。</li>
<li><strong>分仓库</strong>：源码在私有仓库 <code>blog-source</code>，构建产物在公开仓库 <code>cleeate.github.io</code>。免费版 GitHub Pages 只能从公开仓库发布，源码私有、产物公开是最干净的做法。旧测试站 <code>blog-astro</code>（AstroPaper v5）的两篇文章迁了过来，旧仓库没动。</li>
<li><strong>部署链</strong>：推一次源码库 <code>main</code>，Action 构建后把 <code>dist/</code> 推到输出库，再由输出库的 Pages 工作流发布。</li>
</ul>

<h2 id="构建时修的两个问题">构建时修的两个问题<a class="anchor" href="#%e6%9e%84%e5%bb%ba%e6%97%b6%e4%bf%ae%e7%9a%84%e4%b8%a4%e4%b8%aa%e9%97%ae%e9%a2%98"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<ol>
<li><strong>动态 OG 图被关掉了。</strong> satori 生成中文标题的 OG 图时会挂起构建，改用静态 <code>default-og.jpg</code>。</li>
<li><strong>RSS 构建报错 <code>MissingLocale</code>。</strong> <code>astro.config.ts</code> 里把 i18n  locales 设为 zh-CN/en、默认 zh-CN 之后通过。</li>
</ol>

<h2 id="滚动位置-bug两次修复才确认">滚动位置 bug：两次修复才确认<a class="anchor" href="#%e6%bb%9a%e5%8a%a8%e4%bd%8d%e7%bd%ae-bug%e4%b8%a4%e6%ac%a1%e4%bf%ae%e5%a4%8d%e6%89%8d%e7%a1%ae%e8%ae%a4"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>上线后发现一个问题：用浏览器前进、后退离开文章页再回来，总是回到文章顶部，而不是之前读到的位置。</p>
<p>原因是文章页里有一段上游主题带过来的代码，在每次页面切换后无条件执行 <code>window.scrollTo(0, 0)</code>。而 Astro 的 <code>ClientRouter</code> 本来会在前进、后退时恢复滚动位置，这段代码把恢复好的位置又覆盖回了顶部。</p>
<ul>
<li><strong>第一版修复</strong>：只在前进导航时滚回顶部，后退时不动。部署后实测没起作用。</li>
<li><strong>第二版修复</strong>：把那段监听整个删掉。<code>ClientRouter</code> 本来就负责这两件事：前进滚到顶部，后退恢复位置，不需要主题再补一段。</li>
</ul>
<p>但第二版实测一开始也显示失败。最后发现问题在测试方法上：站点头部不是吸顶的，滚到一半时 logo 已经滚出屏幕，要点它得先滚回顶部，而这一滚就把保存的位置改成了 0，回来自然是顶部。换成干净的测法——滚到中间后只按浏览器后退、前进，不点链接也不滚动——位置分毫不差，y=1996，两次都一样。</p>
<p>顺带一个结论：如果你平时是滚回顶部再点导航离开文章，那回来是顶部就是浏览器本身的行为，因为离开那一刻存的就是顶部位置。直接用浏览器前进、后退键，才能回到之前读到的地方。</p>

<h2 id="部署链上的一个坑">部署链上的一个坑<a class="anchor" href="#%e9%83%a8%e7%bd%b2%e9%93%be%e4%b8%8a%e7%9a%84%e4%b8%80%e4%b8%aa%e5%9d%91"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>输出库的部署用 <code>force_orphan</code> 强制推送，会把整个分支替换掉。第一次推送后，输出库里的 Pages 工作流文件 <code>.github/workflows/pages.yml</code> 被清掉了——部署用的 action 默认排除 <code>.github</code> 目录。这样下次部署就没人触发 Pages 发布，网站会停在旧版本。</p>
<p>修复办法：源码库里留一份 <code>.github/pages-output.yml</code> 做源头，部署时拷进 <code>dist/.github/workflows/pages.yml</code>，并把 <code>exclude_assets</code> 设为空，让 <code>.github</code> 能一起推过去。</p>

<h2 id="收尾">收尾<a class="anchor" href="#%e6%94%b6%e5%b0%be"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>排查滚动问题时临时加过一个调试框（左下角绿字，实时显示滚动位置和路由方向），确认结论后已经从源码里删掉。这篇就是新博客的第一篇原创文章。</p>
]]></content:encoded></item><item><title>让 Hermes 替你</title><link>https://npq.kdns.fr/posts/hermes-telegram/</link><guid isPermaLink="true">https://npq.kdns.fr/posts/hermes-telegram/</guid><description>在 Telegram 上运行 Hermes 的配置与验证方法。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded><![CDATA[<p>Hermes Agent 是一个开源的 AI Agent 框架，它可以在 <strong>终端、桌面应用、Telegram、Discord、微信</strong> 等各种表面上运行。本文只讲你最常用的那一面——<strong>Telegram</strong>。</p>
<p>简单说，你发短信，Hermes 干活，把结果推回来。整个过程不需要任何面板，Terminal、文件、搜索、发邮件、日程——只要是一个 AI Agent 能碰到的，Hermes 都能通过通知接口直接操作。</p>
<p>
<img src="https://img.cdn1.vip/i/6aed7b397bf2e_1793948473.webp" alt="Hermes 接进 Telegram：一条消息怎么变成一次执行">
</p>

<h2 id="前置条件">前置条件<a class="anchor" href="#%e5%89%8d%e7%bd%ae%e6%9d%a1%e4%bb%b6"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<ol>
<li><strong>一个已经能用的 Hermes 实例</strong>。你可以从 <a href="https://hermes-agent.nousresearch.com/docs/">hermes-agent.nousresearch.com</a> 下载和安装。它不需要特殊的依赖，只要 Python 环境即可。</li>
<li><strong>一个 Telegram 账号</strong>。</li>
<li><strong>一个 Telegram Bot 的 Token</strong>。没有的话，先给 <a href="https://t.me/BotFather">@BotFather</a> 发消息 <code>/newbot</code>，按提示创建即可。</li>
</ol>

<h2 id="配置-telegram-频道">配置 Telegram 频道<a class="anchor" href="#%e9%85%8d%e7%bd%ae-telegram-%e9%a2%91%e9%81%93"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>Hermes 的设定非常灵活，但最核心的步骤是把 Telegram 加到 <code>config.yaml</code> 的 platform 配置里。把下面这一小段配置粘贴到 config.yaml 中对应的区域：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="yaml" class="wrap" style="--ecMaxLine:28ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#85E89D;--1:#85E89D">platforms</span><span style="--0:#E1E4E8;--1:#E1E4E8">:</span></div></div><div class="ec-line" style="--ecIndent:2ch"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span class="indent">  </span><span style="--0:#85E89D;--1:#85E89D">telegram</span><span style="--0:#E1E4E8;--1:#E1E4E8">:</span></div></div><div class="ec-line" style="--ecIndent:4ch"><div class="gutter"><div class="ln" aria-hidden="true">3</div></div><div class="code"><span class="indent">    </span><span style="--0:#85E89D;--1:#85E89D">bot_token</span><span style="--0:#E1E4E8;--1:#E1E4E8">: </span><span style="--0:#9ECBFF;--1:#9ECBFF">"你的BOT_TOKEN"</span></div></div><div class="ec-line" style="--ecIndent:4ch"><div class="gutter"><div class="ln" aria-hidden="true">4</div></div><div class="code"><span class="indent">    </span><span style="--0:#85E89D;--1:#85E89D">admin</span><span style="--0:#E1E4E8;--1:#E1E4E8">: </span><span style="--0:#9ECBFF;--1:#9ECBFF">"你的CHAT_ID"</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>从技术上讲，<strong>Chat ID</strong> 是你想接收通知的频道或私聊。</p>

<h2 id="验证">验证<a class="anchor" href="#%e9%aa%8c%e8%af%81"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>配置好之后，直接向你的 Bot 发消息。如果一切正常，Hermes 会把结果通过对话频道返回。</p>

<h2 id="总结">总结<a class="anchor" href="#%e6%80%bb%e7%bb%93"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>Hermes 的价值只有一个：<strong>你想在 Telegram 里实现的控制能力</strong>。它支持 <code>Monday</code>、<code>Friday</code>、<code>crontab</code> 等各种定时任务，剩下的事情只需要通过 Bot 发消息即可。</p>
<p>配置非常简单，几步之后你就能在 Telegram 里指挥 AI 干活了。</p>
]]></content:encoded></item><item><title>在 Debian 12 小 VPS 上从零部署 DSH 并接通 Telegram 机器人</title><link>https://npq.kdns.fr/posts/vps-dsh/</link><guid isPermaLink="true">https://npq.kdns.fr/posts/vps-dsh/</guid><description>本文记录一次真实部署的完整过程和踩坑经验。环境：Debian 12、2 核 CPU、约 925MB 内存、39GB 磁盘。</description><pubDate>Wed, 04 Nov 2026 00:00:00 GMT</pubDate><content:encoded><![CDATA[<blockquote>
<p>本文记录一次真实部署的完整过程和踩坑经验。环境：Debian 12、2 核 CPU、约 925MB 内存、39GB 磁盘。
文中所有密钥、Token、密码、用户 ID、机器人用户名一律用占位符表示，公开发布前请务必替换，并不要把真实 Token 写进文章或代码仓库。</p></blockquote>

<h2 id="避坑总览先看这五条">避坑总览：先看这五条<a class="anchor" href="#%e9%81%bf%e5%9d%91%e6%80%bb%e8%a7%88%e5%85%88%e7%9c%8b%e8%bf%99%e4%ba%94%e6%9d%a1"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<ol>
<li><strong>小内存先加 Swap，再装 DSH。</strong> 不加 Swap，npm 安装 DSH 时很容易被 OOM killer 杀掉，表现为安装莫名中断、dsh 命令缺失、服务起不来。</li>
<li><strong>不要装旧的 <code>dsh-telegram</code>。</strong> 新版教程用的是 <code>@xmanrui/dsh-im</code>，两者不要混装。</li>
<li><strong>Token 只走 DSH 设置界面。</strong> 不要把 Bot Token 写进 <code>cordis.patch.yml</code>、<code>settings.yaml</code> 或任何会被提交的文件。</li>
<li><strong>私聊一定要开白名单。</strong> dsh-im 默认对所有私聊开放，不设白名单等于谁都能指挥你的机器人。</li>
<li><strong>模型选错是最高频的报错来源。</strong> 要 Key 的官方模型、要 GitHub 授权的 EAC 模型、免密的 Kilo 免费池，这三类不要混着选。</li>
</ol>

<h2 id="一服务器准备">一、服务器准备<a class="anchor" href="#%e4%b8%80%e6%9c%8d%e5%8a%a1%e5%99%a8%e5%87%86%e5%a4%87"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>

<h3 id="1-改主机名可选但建议做">1. 改主机名（可选，但建议做）<a class="anchor" href="#1-%e6%94%b9%e4%b8%bb%e6%9c%ba%e5%90%8d%e5%8f%af%e9%80%89%e4%bd%86%e5%bb%ba%e8%ae%ae%e5%81%9a"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h3>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame is-terminal"><figcaption class="header"><span class="title"></span><span class="sr-only">Terminal window</span></figcaption><pre data-language="bash" class="wrap" style="--ecMaxLine:27ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">hostnamectl</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">set-hostname</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">b2</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>并在 <code>/etc/hosts</code> 里加一行：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="plaintext" class="wrap" style="--ecMaxLine:12ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#e1e4e8;--1:#e1e4e8">127.0.1.1 b2</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>

<h3 id="2-检查资源">2. 检查资源<a class="anchor" href="#2-%e6%a3%80%e6%9f%a5%e8%b5%84%e6%ba%90"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h3>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame is-terminal"><figcaption class="header"><span class="title"></span><span class="sr-only">Terminal window</span></figcaption><pre data-language="bash" class="wrap" style="--ecMaxLine:32ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">free</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">-m</span><span style="--0:#E1E4E8;--1:#E1E4E8">        </span><span style="--0:#99A0A6;--1:#99A0A6"># 查看内存与已有 Swap</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">df</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">-h</span><span style="--0:#E1E4E8;--1:#E1E4E8">          </span><span style="--0:#99A0A6;--1:#99A0A6"># 确认根分区剩余空间大于 2GB</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>如果 <code>free -m</code> 里 Swap 全为 0，说明机器没有预置交换，继续下一步。</p>

<h3 id="3-创建-2gb-swap">3. 创建 2GB Swap<a class="anchor" href="#3-%e5%88%9b%e5%bb%ba-2gb-swap"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h3>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame is-terminal"><figcaption class="header"><span class="title"></span><span class="sr-only">Terminal window</span></figcaption><pre data-language="bash" class="wrap" style="--ecMaxLine:25ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">fallocate</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">-l</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">2G</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">/swapfile</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">chmod</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">600</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">/swapfile</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">3</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">mkswap</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">/swapfile</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">4</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">swapon</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">/swapfile</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>老版本若不支持 <code>fallocate</code>，可用 <code>dd if=/dev/zero of=/swapfile bs=1M count=2048</code> 代替。</p>
<p>开机自动挂载并调低 swappiness：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame is-terminal"><figcaption class="header"><span class="title"></span><span class="sr-only">Terminal window</span></figcaption><pre data-language="bash" class="wrap" style="--ecMaxLine:47ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#79B8FF;--1:#79B8FF">echo</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">'/swapfile none swap sw 0 0'</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">>></span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">/etc/fstab</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">sysctl</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">vm.swappiness=</span><span style="--0:#79B8FF;--1:#79B8FF">10</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">3</div></div><div class="code"><span style="--0:#79B8FF;--1:#79B8FF">echo</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">'vm.swappiness=10'</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">>></span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">/etc/sysctl.conf</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>swappiness 默认是 60，小内存机器会把数据过早换出、拖慢性能；设为 10 表示只在内存紧张时才动用 Swap。再执行 <code>free -m</code>，Swap 应显示约 2048MB。</p>
<p>补充说明：如果云厂商给你的是静态公网 IP，但网卡上只显示内网地址，这多半是 NAT 映射，属正常现象，只要出站 IP 和入站 SSH 到的都是同一台机器即可。</p>

<h3 id="4-装基础工具">4. 装基础工具<a class="anchor" href="#4-%e8%a3%85%e5%9f%ba%e7%a1%80%e5%b7%a5%e5%85%b7"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h3>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame is-terminal"><figcaption class="header"><span class="title"></span><span class="sr-only">Terminal window</span></figcaption><pre data-language="bash" class="wrap" style="--ecMaxLine:45ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">apt</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">update</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">apt</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">install</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">-y</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">curl</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">ca-certificates</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">gnupg</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">git</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>

<h2 id="二安装-node-和-dsh">二、安装 Node 和 DSH<a class="anchor" href="#%e4%ba%8c%e5%ae%89%e8%a3%85-node-%e5%92%8c-dsh"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>用 NodeSource 装 Node 26：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame is-terminal"><figcaption class="header"><span class="title"></span><span class="sr-only">Terminal window</span></figcaption><pre data-language="bash" class="wrap" style="--ecMaxLine:57ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">curl</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">-fsSL</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">https://deb.nodesource.com/setup_26.x</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">|</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#B392F0;--1:#B392F0">bash</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">-</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">apt</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">install</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">-y</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">nodejs</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">3</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">node</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">-v</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">4</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">npm</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">-v</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>实测版本：Node v26.13.0、npm 11.20.0。</p>
<p>全局安装 DSH，并补装 pnpm（插件安装需要它，缺了会报 pnpm 未找到）：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame is-terminal"><figcaption class="header"><span class="title"></span><span class="sr-only">Terminal window</span></figcaption><pre data-language="bash" class="wrap" style="--ecMaxLine:31ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">npm</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">install</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">-g</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">@deepseek-ai/dsh</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">npm</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">install</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">-g</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">pnpm</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">3</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">dsh</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">--version</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>实测 DSH 版本：0.2.1-rc.5。</p>
<p>长耗时安装建议脱离 SSH 会话运行，例如用 <code>setsid</code> / <code>nohup</code> 后台跑，避免 SSH 断线把安装进程一起带走。SSH 偶尔出现 banner 交换超时，多半是网络抖动，先重试，不要轻易判定服务器挂了。</p>

<h2 id="三安装免费模型插件和-im-插件">三、安装免费模型插件和 IM 插件<a class="anchor" href="#%e4%b8%89%e5%ae%89%e8%a3%85%e5%85%8d%e8%b4%b9%e6%a8%a1%e5%9e%8b%e6%8f%92%e4%bb%b6%e5%92%8c-im-%e6%8f%92%e4%bb%b6"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>

<h3 id="1-免费模型插件">1. 免费模型插件<a class="anchor" href="#1-%e5%85%8d%e8%b4%b9%e6%a8%a1%e5%9e%8b%e6%8f%92%e4%bb%b6"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h3>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame is-terminal"><figcaption class="header"><span class="title"></span><span class="sr-only">Terminal window</span></figcaption><pre data-language="bash" class="wrap" style="--ecMaxLine:66ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">dsh</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">plugin</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">--profile</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">web</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">add</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">github:Ebony-Vinyl/dsh-our-free-model</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>实测版本：2.8.0。</p>
<p>注意两点：</p>
<ul>
<li>不要同时把它写进 <code>cordis.patch.yml</code>，重复注册会出问题。</li>
<li>用下面的命令检查，<code>our-free-model</code> 应该只出现一次：</li>
</ul>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame is-terminal"><figcaption class="header"><span class="title"></span><span class="sr-only">Terminal window</span></figcaption><pre data-language="bash" class="wrap" style="--ecMaxLine:31ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">dsh</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">--profile</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">web</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">--dump-config</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>

<h3 id="2-im-插件telegram-对接">2. IM 插件（Telegram 对接）<a class="anchor" href="#2-im-%e6%8f%92%e4%bb%b6telegram-%e5%af%b9%e6%8e%a5"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h3>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame is-terminal"><figcaption class="header"><span class="title"></span><span class="sr-only">Terminal window</span></figcaption><pre data-language="bash" class="wrap" style="--ecMaxLine:47ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">dsh</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">plugin</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">--profile</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">web</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">add</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">-w</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">@xmanrui/dsh-im</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>实测版本：5.9.1。</p>
<p>最终 bundles 顺序应为：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="plaintext" class="wrap" style="--ecMaxLine:24ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#e1e4e8;--1:#e1e4e8">@deepseek-ai/dsh-base</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span style="--0:#e1e4e8;--1:#e1e4e8">@deepseek-ai/dsh-web-app</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">3</div></div><div class="code"><span style="--0:#e1e4e8;--1:#e1e4e8">dsh-our-free-model</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">4</div></div><div class="code"><span style="--0:#e1e4e8;--1:#e1e4e8">@xmanrui/dsh-im</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>再次检查 dump-config，确认 <code>our-free-model</code> 和 <code>@xmanrui/dsh-im</code> 都在，且没有旧的 <code>dsh-telegram</code>。</p>

<h2 id="四用-systemd-跑-dsh不要对外暴露-web-ui">四、用 systemd 跑 DSH，不要对外暴露 Web UI<a class="anchor" href="#%e5%9b%9b%e7%94%a8-systemd-%e8%b7%91-dsh%e4%b8%8d%e8%a6%81%e5%af%b9%e5%a4%96%e6%9a%b4%e9%9c%b2-web-ui"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>教程本身只要求前台跑 <code>dsh --profile web</code>，但为了让机器人 survives 重启，建议写一个 systemd 服务。关键点：Web UI 只监听本地，Telegram 走长轮询，不需要开放任何入站端口。</p>
<p><code>/etc/systemd/system/dsh.service</code> 示例：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="ini" class="wrap" style="--ecMaxLine:36ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">[Unit]</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span style="--0:#F97583;--1:#F97583">Description</span><span style="--0:#E1E4E8;--1:#E1E4E8">=DSH Telegram Agent</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">3</div></div><div class="code"><span style="--0:#F97583;--1:#F97583">After</span><span style="--0:#E1E4E8;--1:#E1E4E8">=network-online.target</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">4</div></div><div class="code"><span style="--0:#F97583;--1:#F97583">Wants</span><span style="--0:#E1E4E8;--1:#E1E4E8">=network-online.target</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">5</div></div><div class="code">
</div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">6</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">[Service]</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">7</div></div><div class="code"><span style="--0:#F97583;--1:#F97583">Type</span><span style="--0:#E1E4E8;--1:#E1E4E8">=simple</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">8</div></div><div class="code"><span style="--0:#F97583;--1:#F97583">User</span><span style="--0:#E1E4E8;--1:#E1E4E8">=root</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">9</div></div><div class="code"><span style="--0:#F97583;--1:#F97583">WorkingDirectory</span><span style="--0:#E1E4E8;--1:#E1E4E8">=/root</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">10</div></div><div class="code"><span style="--0:#F97583;--1:#F97583">Environment</span><span style="--0:#E1E4E8;--1:#E1E4E8">=</span><span style="--0:#F97583;--1:#F97583">DSH_HOME</span><span style="--0:#E1E4E8;--1:#E1E4E8">=/root/.dsh</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">11</div></div><div class="code"><span style="--0:#F97583;--1:#F97583">Environment</span><span style="--0:#E1E4E8;--1:#E1E4E8">=</span><span style="--0:#F97583;--1:#F97583">HOME</span><span style="--0:#E1E4E8;--1:#E1E4E8">=/root</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">12</div></div><div class="code"><span style="--0:#F97583;--1:#F97583">ExecStart</span><span style="--0:#E1E4E8;--1:#E1E4E8">=/usr/bin/dsh --profile web</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">13</div></div><div class="code"><span style="--0:#F97583;--1:#F97583">Restart</span><span style="--0:#E1E4E8;--1:#E1E4E8">=always</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">14</div></div><div class="code"><span style="--0:#F97583;--1:#F97583">RestartSec</span><span style="--0:#E1E4E8;--1:#E1E4E8">=10</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">15</div></div><div class="code">
</div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">16</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">[Install]</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">17</div></div><div class="code"><span style="--0:#F97583;--1:#F97583">WantedBy</span><span style="--0:#E1E4E8;--1:#E1E4E8">=multi-user.target</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>启动并验证：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame is-terminal"><figcaption class="header"><span class="title"></span><span class="sr-only">Terminal window</span></figcaption><pre data-language="bash" class="wrap" style="--ecMaxLine:31ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">systemctl</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">daemon-reload</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">systemctl</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">enable</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">dsh</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">3</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">systemctl</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">start</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">dsh</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">4</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">systemctl</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">status</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">dsh</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">--no-pager</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">5</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">ss</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">-tlnp</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">|</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#B392F0;--1:#B392F0">grep</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">-E</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">'3080|8326'</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>正常情况下服务是 <code>active</code>，且 3080、8326 只出现在 <code>127.0.0.1</code> 上，不要在防火墙或安全组里放行它们。</p>

<h2 id="五绑定-telegram-机器人">五、绑定 Telegram 机器人<a class="anchor" href="#%e4%ba%94%e7%bb%91%e5%ae%9a-telegram-%e6%9c%ba%e5%99%a8%e4%ba%ba"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<ol>
<li>在 BotFather 创建机器人，拿到 Bot Token，记好但不要发到公开场合。</li>
<li>打开 DSH 的「设置 → IM机器人」，选择 Telegram，粘贴 Token 并保存。</li>
<li><strong>务必开启私聊白名单模式</strong>，填入自己的数字 USER_ID，例如：</li>
</ol>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="plaintext" class="wrap" style="--ecMaxLine:14ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#e1e4e8;--1:#e1e4e8">&#x3C;你的数字 USER_ID></span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>只放你一个人。群聊默认是开放模式，如需收紧要另外设置，不要以为开了私聊白名单群聊就自动安全了。</p>
<p>绑定成功后，机器人应显示已连接、长轮询正常。绑定信息保存在 <code>~/.dsh/integrations/dsh-telegram/</code>，Token 在里面是引用形式，不是明文，但这不等于可以把该目录公开分享。</p>

<h2 id="六模型选择避坑这是本次部署最关键的一节">六、模型选择避坑：这是本次部署最关键的一节<a class="anchor" href="#%e5%85%ad%e6%a8%a1%e5%9e%8b%e9%80%89%e6%8b%a9%e9%81%bf%e5%9d%91%e8%bf%99%e6%98%af%e6%9c%ac%e6%ac%a1%e9%83%a8%e7%bd%b2%e6%9c%80%e5%85%b3%e9%94%ae%e7%9a%84%e4%b8%80%e8%8a%82"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>dsh-im 的模型列表里混了三类模型，选错就会报错：</p>
<table>
  <thead>
      <tr>
          <th>类型</th>
          <th>表现</th>
          <th>能不能在服务器上用</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>DeepSeek 官方模型，如 <code>deepseek-flash</code></td>
          <td>没有 Key 时报缺少凭据</td>
          <td>没配 Key 就不能用</td>
      </tr>
      <tr>
          <td>EAC 模型，如 <code>opencode/deepseek-v4.1-flash-free</code></td>
          <td>报 401，需要 GitHub 授权并 star 仓库</td>
          <td>服务器上用不了，它是桌面端取向的渠道</td>
      </tr>
      <tr>
          <td>Kilo 免费池，如 <code>kilo-auto/free</code></td>
          <td>免账号、免 Key</td>
          <td>可以，这就是默认该选的</td>
      </tr>
  </tbody>
</table>
<p>正确做法：把默认模型写进 <code>~/.dsh/profiles/web/cordis.patch.yml</code> 的 <code>agent-default-model</code>：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame"><figcaption class="header"></figcaption><pre data-language="yaml" class="wrap" style="--ecMaxLine:46ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#E1E4E8;--1:#E1E4E8">- </span><span style="--0:#85E89D;--1:#85E89D">id</span><span style="--0:#E1E4E8;--1:#E1E4E8">: </span><span style="--0:#9ECBFF;--1:#9ECBFF">agent-default-model</span></div></div><div class="ec-line" style="--ecIndent:2ch"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span class="indent">  </span><span style="--0:#85E89D;--1:#85E89D">name</span><span style="--0:#E1E4E8;--1:#E1E4E8">: </span><span style="--0:#9ECBFF;--1:#9ECBFF">"@deepseek-ai/dsh-agent-default-model"</span></div></div><div class="ec-line" style="--ecIndent:2ch"><div class="gutter"><div class="ln" aria-hidden="true">3</div></div><div class="code"><span class="indent">  </span><span style="--0:#85E89D;--1:#85E89D">config</span><span style="--0:#E1E4E8;--1:#E1E4E8">:</span></div></div><div class="ec-line" style="--ecIndent:4ch"><div class="gutter"><div class="ln" aria-hidden="true">4</div></div><div class="code"><span class="indent">    </span><span style="--0:#85E89D;--1:#85E89D">provider</span><span style="--0:#E1E4E8;--1:#E1E4E8">: </span><span style="--0:#9ECBFF;--1:#9ECBFF">our-free-model</span></div></div><div class="ec-line" style="--ecIndent:4ch"><div class="gutter"><div class="ln" aria-hidden="true">5</div></div><div class="code"><span class="indent">    </span><span style="--0:#85E89D;--1:#85E89D">model</span><span style="--0:#E1E4E8;--1:#E1E4E8">: </span><span style="--0:#9ECBFF;--1:#9ECBFF">kilo-auto/free</span></div></div><div class="ec-line" style="--ecIndent:4ch"><div class="gutter"><div class="ln" aria-hidden="true">6</div></div><div class="code"><span class="indent">    </span><span style="--0:#85E89D;--1:#85E89D">reasoningEffort</span><span style="--0:#E1E4E8;--1:#E1E4E8">: </span><span style="--0:#9ECBFF;--1:#9ECBFF">high</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p>改完重启服务：</p>
<div class="expressive-code"><script type="module" src="/js/ec.js"></script><figure class="frame is-terminal"><figcaption class="header"><span class="title"></span><span class="sr-only">Terminal window</span></figcaption><pre data-language="bash" class="wrap" style="--ecMaxLine:62ch"><code><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">1</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">systemctl</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">restart</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">dsh</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">2</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">systemctl</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">is-active</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">dsh</span></div></div><div class="ec-line"><div class="gutter"><div class="ln" aria-hidden="true">3</div></div><div class="code"><span style="--0:#B392F0;--1:#B392F0">dsh</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">--profile</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">web</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">--dump-config</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#F97583;--1:#F97583">|</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#B392F0;--1:#B392F0">grep</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#79B8FF;--1:#79B8FF">-A4</span><span style="--0:#E1E4E8;--1:#E1E4E8"> </span><span style="--0:#9ECBFF;--1:#9ECBFF">agent-default-model</span></div></div></code><button class="copy-btn" aria-label="Copy code"><div class="copy-btn-icon"><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon copy-icon"><path d="M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z"></path></svg><svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" class="copy-btn-icon success-icon"><path d="m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z"></path></svg></div></button></pre></figure></div>
<p><strong>重要：改完模型一定要在 Telegram 里先发 <code>/new</code> 开新会话，再发正常消息。</strong> 旧会话还钉在旧模型上，不换会话，报错会继续出现。这一步最容易被忽略。</p>

<h2 id="七验证清单">七、验证清单<a class="anchor" href="#%e4%b8%83%e9%aa%8c%e8%af%81%e6%b8%85%e5%8d%95"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p>按顺序全部通过，才算部署完成：</p>
<ul>
<li><input disabled="" type="checkbox"> <code>systemctl status dsh</code> 是 <code>active</code></li>
<li><input disabled="" type="checkbox"> 3080、8326 只监听在 <code>127.0.0.1</code></li>
<li><input disabled="" type="checkbox"> Telegram 发 <code>/start</code> 有回复</li>
<li><input disabled="" type="checkbox"> Telegram 发 <code>/status</code> 能看到会话和模型</li>
<li><input disabled="" type="checkbox"> Telegram 发 <code>/new</code> 后，再发一句正常消息能正常回复</li>
<li><input disabled="" type="checkbox"> 没有出现“任务结果未确认”“内部未知错误”之类的提交失败提示</li>
</ul>

<h2 id="八常见问题">八、常见问题<a class="anchor" href="#%e5%85%ab%e5%b8%b8%e8%a7%81%e9%97%ae%e9%a2%98"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<p><strong>Q：npm 安装 DSH 装到一半就没了，dsh 命令也不存在？</strong>
A：先看内存和 Swap，十有八九是 OOM killer 杀了 npm。按第一节补 2GB Swap 再重装，不要反复在没 Swap 的机器上硬装。</p>
<p><strong>Q：插件安装报 pnpm 未找到？</strong>
A：先全局装 pnpm 再装插件。</p>
<p><strong>Q：/start 失败，提示缺少凭据？</strong>
A：会话默认模型走了 DeepSeek 官方渠道，但你没配 Key。按第六节把默认模型改成 Kilo 免费池，再 <code>/new</code>。</p>
<p><strong>Q：正常消息报 401，要 GitHub 授权 star 仓库？</strong>
A：你选到了 EAC 模型。换回 <code>kilo-auto/free</code>，再 <code>/new</code>。不要尝试绕过 EAC 的授权闸门。</p>
<p><strong>Q：改了模型还是报错？</strong>
A：先确认你是不是还在旧会话里。<code>/new</code> 之后再测一次；同时用 <code>journalctl -u dsh --no-pager | tail -n 100</code> 看服务日志，用 Telegram 的 <code>/status</code> 看当前会话到底用的是哪个模型。</p>
<p><strong>Q：SSH 经常断，b2 是不是挂了？</strong>
A：不一定。先重试连接，再看服务状态。长安装一定要脱离 SSH 会话跑，断线才不会中断安装。</p>

<h2 id="九发布前的安全提醒">九、发布前的安全提醒<a class="anchor" href="#%e4%b9%9d%e5%8f%91%e5%b8%83%e5%89%8d%e7%9a%84%e5%ae%89%e5%85%a8%e6%8f%90%e9%86%92"><span class="anchor-icon" data-pagefind-ignore="">#</span></a></h2>
<ul>
<li>不要把 Bot Token、服务器密码、API Key 写进教程、截图或代码仓库。</li>
<li>数字 USER_ID、白名单、机器人用户名在公开发布时建议用占位符或打码。</li>
<li>Web UI 只监听本地是刻意为之，不要为了图方便把它暴露到公网。</li>
</ul>
]]></content:encoded></item></channel></rss>
