<blockquote><p><strong>TL;DR</strong>：一句话说清根因与修法，让读者 5 秒判断是否与他相关。</p></blockquote>

<h2>元信息</h2>
<ul>
  <li><strong>适用版本</strong>：intranet-tunnel v1.2.1 / Halo 2.26.1 / PostgreSQL 15.4</li>
  <li><strong>最后验证时间</strong>：2026-09-13</li>
  <li><strong>环境</strong>：Ubuntu 24.04.4 LTS，Docker 27.x，部署目录 <code>/home/docker/&lt;项目名&gt;/</code></li>
</ul>

<h2>现象</h2>
<p>用户视角看到了什么。要写<strong>可观察的事实</strong>（报错原文、界面表现、返回值），不要写推测。</p>
<pre><code class="language-text">把原始报错整段贴进来，不要截断、不要"美化"。</code></pre>

<h2>排查过程</h2>
<ol>
  <li><strong>先确认 X</strong>：执行 <code>docker inspect &lt;容器&gt; --format '{{.State.ExitCode}}'</code>，结果 <code>0</code> → 排除崩溃。</li>
  <li><strong>再确认 Y</strong>：……（写明"当时以为是什么、为什么排除"）</li>
</ol>
<blockquote><p>⚠️ 踩坑提示：这里写"看似像 A 问题其实不是"的分叉点——这是本文最有价值的部分。</p></blockquote>

<h2>根因</h2>
<p>机制层面的解释：<strong>哪一行代码 / 哪一个配置项 / 哪一条链路</strong>导致了现象。附上关键代码或配置片段。</p>
<pre><code class="language-go">// 只贴关键几行，标注文件路径
// server/internal/proxy/tunnel_stats.go
func (c *Collector) AddIn(name string, n int64) { /* ... */ }</code></pre>

<h2>修复</h2>
<pre><code class="language-bash"># 可直接复制的命令，按顺序执行
docker compose build tunnel-server
docker compose up -d tunnel-server</code></pre>
<p>说明为什么这样改，以及<strong>为什么不是另一种改法</strong>。</p>

<h2>验证（判据）</h2>
<ul>
  <li>✅ 正向断言：访问隧道域名 3 次，<code>bytes_in/bytes_out</code> 增量非 0。</li>
  <li>✅ <strong>反向断言</strong>：未被访问的隧道统计<strong>仍为 0</strong>（只看总量涨了会把"统计挂错了隧道"放过去）。</li>
  <li>✅ 操作本身的成功信号：接口返回 200，且读回值符合预期。</li>
</ul>

<h2>通用教训</h2>
<p>能迁移到其他场景的那一条原则（可被未来的自己在别的项目里复用）。</p>

<h2>相关</h2>
<ul>
  <li><a href="/archives/xxx">相关文章</a></li>
  <li><a href="/docs/view/tech-docs/tunnel-troubleshoot">文档库 · 隧道排错手册</a></li>
</ul>

> **TL;DR**：一句话说清根因与修法。

## 元信息

| 项 | 值 |
|---|---|
| 适用版本 | intranet-tunnel v1.2.1 / Halo 2.26.1 |
| 最后验证时间 | 2026-09-13 |
| 环境 | Ubuntu 24.04.4 / Docker 27.x |

## 现象

可观察的事实 + 原始报错：

```text
Error: command timed out after 30 seconds

nohup ./long-task.sh > /tmp/task.log 2>&1 &

> **注意**：Markdown 代码块的围栏嵌套在本文档里展示时会冲突，实际写入时按正常 ```` ``` ```` 使用。

### D.4 模板 ②：项目文档 / README 风格（Markdown，用于 MiniDocs 与代码仓库）

````markdown
# intranet-tunnel 服务端部署手册

| 项 | 值 |
|---|---|
| 文档状态 | 现行有效 |
| 适用版本 | v1.2.1 及以上 |
| 最后验证 | 2026-09-13（真实环境验证通过） |
| 维护人 | sushike |

## 这是什么

一段话说清：这个项目解决什么问题、给谁用、不做什么。

## 架构

```text
浏览器 ──TLS──> 宝塔 nginx ──> 127.0.0.1:48080 内置反代 ──> 隧道 ──> 内网服务
                                   │
                                   └── 控制面 :47800 / 面板 :47801

mkdir -p /home/docker/intranet-tunnel && cd /home/docker/intranet-tunnel
cp .env.example .env    # 再填入真实值，切勿提交
docker compose up -d tunnel-server postgres db-backup

### D.5 模板 ③：教程 / 长文（HTML 版，用于 Halo 文章）

Ethereal 的文章页**自动生成目录**，条件是标题层级正确 + 主题设置开启（本实例 `post.toc.enable_toc = true`、`toc_depth = 2`，即**目录抓取到 H2 深度**）。因此长文请**统一用 H2 作为主章节**。

```html
<h2>这篇教程适合谁</h2>
<p>前置知识、需要准备的东西、预计耗时、最终能达成什么效果。</p>
<ul>
  <li><strong>前置</strong>：一台能跑 Docker 的机器，一个已备案的域名。</li>
  <li><strong>产出</strong>：可在公网访问的自建服务。</li>
</ul>

<h2>第一步：准备工作</h2>
<p>说清"为什么需要这一步"，再给命令：</p>
<pre><code class="language-bash">ssh root@&lt;服务器IP&gt;
mkdir -p /home/docker/&lt;项目名&gt;</code></pre>
<p><strong>验证</strong>：<code>ls -ld /home/docker/&lt;项目名&gt;</code> 输出目录存在且属主正确。</p>

<h2>第二步：…（依次推进，每步都必须有验证判据）</h2>

<h2>原理补充（可跳过）</h2>
<blockquote><p>💡 这一段解释"为什么这样做有效"，不影响操作，供后续排错时回看。</p></blockquote>

<h2>常见坑</h2>
<ol>
  <li><strong>坑一</strong>：现象 → 原因 → 处理。</li>
  <li><strong>坑二</strong>：……</li>
</ol>

<h2>小结</h2>
<p>三句话总结，并给出下一步可做的事（附内链）。</p>

  <blockquote><p>⚠️ 注意：覆盖正在运行的 exe 会失败，先确认程序没在跑。</p></blockquote>
  <blockquote><p>💡 提示：本机未安装 make，直接用 git 命令。</p></blockquote>

# ① 文档结构完整（应输出 15 个章节标题 + 附录）
Select-String -Path H:\Works\halo-kb\README.md -Pattern '^## ' | Measure-Object

# ② 【硬约束】密钥形态扫描 —— 必须 0 命中
#    注意：Select-String -Path <目录>\* 会把子目录当成文件而报“访问被拒绝”，那是噪声不是命中；
#    要覆盖全部文件（含隐藏文件）请用下面这条 -File -Force 的写法：
Get-ChildItem -Path H:\Works\halo-kb -Recurse -File -Force |
  Select-String -Pattern 'pat_[A-Za-z0-9_\-\.]{80,}|hmcp_[A-Za-z0-9_-]{60,}|sk-[A-Za-z0-9]{20,}' -AllMatches

# ③ 本文档不含真实凭据（应只在说明文字里出现占位符）
Select-String -Path H:\Works\halo-kb\README.md -Pattern '<TOKEN>|<REDACTED>'

# ④ 章节顺序检查（应依次出现 一 ~ 十五）
Select-String -Path H:\Works\halo-kb\README.md -Pattern '^## (一|二|三|四|五|六|七|八|九|十|十一|十二|十三|十四|十五)、'