From 321bde10c1356272ac531910f6c25cdeab1b0e46 Mon Sep 17 00:00:00 2001
From: modusensus <guanqishi26@gmail.com>
Date: Mon, 21 Sep 2026 13:38:55 +0800
Subject: [PATCH] =?UTF-8?q?feat(serve):=20--demo=20=E7=94=A8=E5=86=85?=
 =?UTF-8?q?=E7=BD=AE=E7=A4=BA=E4=BE=8B=E6=95=B0=E6=8D=AE=E5=90=AF=E5=8A=A8?=
 =?UTF-8?q?=E7=9C=8B=E6=9D=BF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

看板只从真实的配置与守护进程状态文件取数据，于是"先看一眼前端长什么样"这件事以前只有
两条路：对着真基础设施跑，或者手搓一份状态文件。后者会随 payload 契约漂移而悄悄失真，
而它长得和真数据一模一样——最容易被当成真的。

--demo 把它收进产品：不读配置、不碰守护进程，用一份内置的确定性时间轴驱动同一个 HTTP
服务。三个 profile 覆盖看板会渲染的每一种状态——web 健康→断线→退避→重连；db 连上了但
服务器那一侧端口没监听（**确定失败**，而在线率并不低：这两列本就不是一回事）；metrics
探针得不出结论（端口显示"未观测"而不是"未监听"，即 #25 的语义）。

时间轴是"现在 − 启动时刻"算出来的纯函数，不是后台定时器线程：同一时刻永远是同一份
payload（测试因此能钉住时刻，而不是靠 sleep 去等一个事件发生），看板的 5 秒轮询自己
提供采样。周期互质（180/120/210 秒），所以三条隧道的状态变化会错开出现。

数据在三处自证是演示：payload 的 demo 标记（/status.json 一样）、页头的"演示数据"徽记
与页脚说明、命令行的一行黄字。一张看板截图里写着服务器地址与端口，它不该被误读成某个人
的真实基础设施——示例主机名一律 example.com。绑定校验照旧：非回环 --host 仍要求令牌。

顺带修掉一处自相矛盾：启动后的第一个周期里还没断过线时，"上次断线"会回头去取上一轮，
于是页面写得出"已运行 1 分 20 秒"+"上次断线 2 分钟前"——一条比进程本身还老的故障记录。
这条是看着运行中的看板发现的，现在钉进了测试：沿全时间轴扫描，任何记录都必须落在
[启动时刻, 现在] 之间。

---------

Co-authored-by: Codebuff <noreply@codebuff.com>
---
 CHANGELOG.md       |  14 ++
 README.md          |  18 ++-
 ponte/demo.py      | 369 +++++++++++++++++++++++++++++++++++++++++++++
 ponte/main.py      |  59 ++++++--
 ponte/serve.py     |  29 +++-
 tests/test_demo.py | 287 +++++++++++++++++++++++++++++++++++
 6 files changed, 759 insertions(+), 17 deletions(-)
 create mode 100644 ponte/demo.py
 create mode 100644 tests/test_demo.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 57b6f05..e9b4484 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -199,6 +199,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`ponte serve --demo` serves the dashboard on built-in sample data.** The page
+  names your servers, users and ports, so the only ways to look at it without a
+  tunnel were to run it against real infrastructure or to hand-write a status
+  file — and a hand-written one drifts from the payload contract while looking
+  exactly like the real thing. `--demo` reads no config and never touches a
+  daemon: it drives a small deterministic timeline that connects, drops, backs
+  off and reconnects on its own, so the page shows every state it can render —
+  healthy, broken, and *unknown* (a probe that could not answer, where the ports
+  read `未观测` rather than `未监听`). It labels itself in three places —
+  `"demo": true` in `/status.json`, a `演示数据` pill and a footer note on the
+  page, and a yellow line on the terminal — because a dashboard screenshot must
+  not be mistakable for somebody's real infrastructure. Sample hosts are
+  `example.com`. The bind rules are unchanged: a non-loopback `--host` still
+  demands a token.
 - **The jump chain is part of the status, next to the destination.**
   `ProfileStatus.jump` carries the `ssh -J` value, so `ponte status --json` and
   the dashboard can tell "cannot reach the server" apart from "cannot reach the
diff --git a/README.md b/README.md
index ca19dc4..0b7548f 100644
--- a/README.md
+++ b/README.md
@@ -120,7 +120,7 @@ import package stay `ponte`; a checkout installs the same way (`pipx install .`)
 | `check [--profile NAME]` | verify tunnel ports are listening (`-R` on the server, `-L`/`-D` locally) |
 | `doctor [--offline] [--timeout S] [--json]` | one-shot checkup of config, key, connectivity, ports, auto-start and notifications, each row with a fix (`--json` for scripts) |
 | `notify-test [--profile NAME]` | send a test alert through the configured ntfy / webhook channels |
-| `serve [--host H] [--port P] [--token T] [--open]` | local HTTP dashboard, `/healthz` probe, Prometheus `/metrics`, `/status.json` snapshot |
+| `serve [--host H] [--port P] [--token T] [--open] [--demo]` | local HTTP dashboard, `/healthz` probe, Prometheus `/metrics`, `/status.json` snapshot; `--demo` serves built-in sample data |
 | `install` / `uninstall` | register / remove the OS auto-start service |
 | `config [--ssh-command]` | print the effective configuration, its source file and any warnings (`--ssh-command` prints the exact `ssh` argv) |
 
@@ -140,6 +140,14 @@ ponte serve            # http://127.0.0.1:8787/  (loopback only by default)
 ponte serve --open     # ...and open it in your browser
 ```
 
+**No tunnels yet?** `ponte serve --demo` runs the same server on built-in sample
+data: a small timeline that connects, drops, backs off and reconnects on its own,
+so the page shows every state it has — healthy, broken, and *unknown* (a probe
+that could not answer). It reads no config and never touches a daemon, and the
+payload (`"demo": true`), the page header and the CLI output all say the data is
+a demo: a dashboard screenshot names your servers, so it must not be mistakable
+for somebody's real infrastructure. Sample hosts use `example.com`.
+
 | Endpoint | What it answers |
 |----------|-----------------|
 | `/` | the dashboard: one row per tunnel — verdict, destination and jump chain, forwarded ports as chips, session age, availability, last disconnect reason; click a row for the full statistics and the event feed. Light and dark, refreshed in place (expanded rows and scroll position survive), and a `<noscript>` reload if scripting is off |
@@ -441,7 +449,7 @@ ponte install           # 注册开机自启 + 崩溃重启
 | `check [--profile NAME]` | 检查隧道端口（`-R` 在服务器上，`-L`/`-D` 在本机） |
 | `doctor [--offline] [--timeout S] [--json]` | 一键体检配置、密钥、连通性、端口、自启与通知，每项给出修法（`--json` 供脚本消费） |
 | `notify-test [--profile NAME]` | 通过已配置的 ntfy / webhook 通道发一条测试通知 |
-| `serve [--host H] [--port P] [--token T] [--open]` | 本地 HTTP 看板、`/healthz` 探活、Prometheus `/metrics`、`/status.json` 快照 |
+| `serve [--host H] [--port P] [--token T] [--open] [--demo]` | 本地 HTTP 看板、`/healthz` 探活、Prometheus `/metrics`、`/status.json` 快照；`--demo` 用内置示例数据 |
 | `install` / `uninstall` | 注册 / 移除开机自启服务 |
 | `config [--ssh-command]` | 打印生效配置、来源文件与配置告警（`--ssh-command` 打印实际执行的 ssh 命令） |
 
@@ -460,6 +468,12 @@ ponte serve            # http://127.0.0.1:8787/（默认只监听本机）
 ponte serve --open     # 顺手在浏览器里打开
 ```
 
+**还没有隧道？** `ponte serve --demo` 用内置的示例数据把同一个服务跑起来：一份自己会
+连接、断线、退避、重连的小时间轴，于是页面上该有的状态都会出现——健康、异常，以及
+**未知**（探针没能得出结论）。它不读配置、也不碰守护进程；payload（`"demo": true`）、
+页面头部与命令行输出三处都写明这是演示数据：看板截图里写着服务器地址与端口，它不该被
+误读成某个人的真实基础设施。示例主机名一律用 `example.com`。
+
 | 接口 | 回答什么问题 |
 |------|--------------|
 | `/` | 看板：一行一条隧道——状态、目标与跳板机、端口 chips、会话时长、在线率、上次断线原因；点开该行看完整统计与事件流。跟随浅色/深色主题，原地刷新（展开的行与滚动位置都不会丢），关掉脚本则退化为整页刷新 |
diff --git a/ponte/demo.py b/ponte/demo.py
new file mode 100644
index 0000000..b9b70cb
--- /dev/null
+++ b/ponte/demo.py
@@ -0,0 +1,369 @@
+"""``ponte serve --demo`` 的内置演示数据：一条按真实节奏推进的时间轴。
+
+为什么这件事该在产品里，而不是让每个人自己在外头造一份状态文件：看板是纯函数渲染出来的
+HTML，但它只从**真实**的配置与守护进程状态文件取数据。于是"先看一眼前端长什么样"这件事，
+在你还没有隧道、或者不想为了看页面去连真服务器时，只能靠手搓状态文件——那份文件会随
+payload 契约漂移而悄悄失真，而它长得和真数据一模一样，最容易被当成真的。演示模式把它收进
+产品里，并且**在页面、JSON 与命令行三处都标明这是演示数据**。
+
+数据是**确定性的**：每个 profile 是一条循环时间轴，同一时刻的 payload 完全相同，所以测试
+可以钉住某个时刻断言，而不是靠 `sleep` 去等一个事件发生。
+
+三个 profile 分别覆盖看板会渲染的三种状态：
+
+===================  ==========================================================
+``web``              稳态 + 偶发断线重连：健康 → 异常 → 再连上，会话统计与事件流都在动
+``db``               SSH 在、但服务器上的端口不监听：健康是**确定失败**，而可用率并不低
+                     —— 这两列本来就不是一回事，演示数据把它显出来
+``metrics``          探针偶尔得不出结论：端口是"**未观测**"而不是"未监听"（#25 的语义）
+===================  ==========================================================
+
+用法：``ponte serve --demo``（见 ``ponte.main.serve``）。
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import time
+from dataclasses import dataclass
+from typing import Any
+
+#: 时间轴上的状态。前三个对应守护进程真实经历的三段，``UNKNOWN`` 对应"探针没问出结论"。
+CONNECTED = "connected"
+DISCONNECTED = "disconnected"
+RETRYING = "retrying"
+UNKNOWN = "unknown"
+
+#: 事件流保留多少条（与看板的 ``_FEED_LIMIT`` 对齐；多几条无妨，看板会自己截断）。
+_FEED_LIMIT = 8
+
+#: 这些状态下 SSH 会话还活着——可用率因此把它们算成"在线"。
+_ALIVE_STATES = frozenset({CONNECTED, UNKNOWN})
+
+
+@dataclass(frozen=True)
+class Phase:
+    """时间轴的一段：``seconds`` 秒里，看板看到的一切都由 ``state`` 决定。
+
+    ``reason`` 的含义随状态变：``CONNECTED`` 时它是**检查错误**（连上了但端口没通），
+    ``DISCONNECTED``/``RETRYING`` 时它是**循环错误/上次断线原因**，``UNKNOWN`` 时它是
+    **探测失败的原因**。
+    """
+
+    state: str
+    seconds: float
+    reason: str = ""
+    #: ``RETRYING`` 段里每隔多久算一次失败的尝试（也用来算退避等待）。
+    attempt_interval: float = 5.0
+
+
+@dataclass(frozen=True)
+class DemoProfile:
+    """一条演示隧道：身份、端口，以及它循环经历的时间轴。"""
+
+    name: str
+    destination: str
+    remote_ports: tuple[int, ...]
+    local_ports: tuple[int, ...]
+    phases: tuple[Phase, ...]
+    jump: str | None = None
+    #: 每隔多少个循环发一次"通知"（对应看板明细里的"上次通知"一行）；0 = 从不。
+    notify_every: int = 0
+
+    @property
+    def cycle_seconds(self) -> float:
+        return sum(phase.seconds for phase in self.phases)
+
+    @property
+    def reconnect_index(self) -> int:
+        """这一轮里"重连成功"之后会话从第几段开始。
+
+        没有 RETRYING 就返回 ``len(phases)``——一个永远到不了的序号，于是"本轮是否已经重连过"
+        对所有 profile 都是同一个判断（否则一条从不掉线的隧道会被凭空记出更多会话）。
+        """
+        retries = [i for i, phase in enumerate(self.phases) if phase.state == RETRYING]
+        return retries[-1] + 1 if retries else len(self.phases)
+
+    @property
+    def retry_phase(self) -> Phase | None:
+        retries = [p for p in self.phases if p.state == RETRYING]
+        return retries[-1] if retries else None
+
+    @property
+    def disconnects(self) -> bool:
+        """这条隧道会不会真的掉线（`metrics` 那条就不会）。"""
+        return any(p.state in (DISCONNECTED, RETRYING) for p in self.phases)
+
+
+#: 演示用域名一律是 reserved 域名：截图里也能一眼看出这不是真基础设施。
+_PROFILES: tuple[DemoProfile, ...] = (
+    DemoProfile(
+        name="web",
+        destination="deploy@edge.example.com:22",
+        jump="ops@bastion.example.com",
+        remote_ports=(23334,),
+        local_ports=(1080,),
+        phases=(
+            Phase(CONNECTED, 140.0),
+            Phase(DISCONNECTED, 6.0, "ssh exited with code 255"),
+            Phase(RETRYING, 18.0),
+            Phase(CONNECTED, 16.0),
+        ),
+    ),
+    DemoProfile(
+        name="db",
+        destination="ops@db.internal.example.com:22",
+        remote_ports=(5432,),
+        local_ports=(5432,),
+        notify_every=2,
+        phases=(
+            # 连上了、本地也在听，但服务器那一侧的 5432 没起来：健康是确定失败。
+            Phase(CONNECTED, 25.0, "remote port 5432 is not listening"),
+            Phase(DISCONNECTED, 5.0, "ssh exited with code 255"),
+            Phase(RETRYING, 90.0),
+        ),
+    ),
+    DemoProfile(
+        name="metrics",
+        destination="ops@metrics.example.com:22",
+        remote_ports=(9090,),
+        local_ports=(9090,),
+        phases=(
+            Phase(CONNECTED, 170.0),
+            Phase(UNKNOWN, 40.0, "ssh exited with code 255 while probing"),
+        ),
+    ),
+)
+
+
+def _is_up(state: str) -> bool:
+    return state in _ALIVE_STATES
+
+
+def _phase_starts(profile: DemoProfile) -> list[float]:
+    """每一段在循环内的起点（秒）。"""
+    starts: list[float] = []
+    cursor = 0.0
+    for phase in profile.phases:
+        starts.append(cursor)
+        cursor += phase.seconds
+    return starts
+
+
+def _locate(profile: DemoProfile, offset: float) -> int:
+    """``offset``（循环内秒数）落在第几段。"""
+    starts = _phase_starts(profile)
+    for index in range(len(profile.phases) - 1, -1, -1):
+        if offset >= starts[index]:
+            return index
+    return 0  # pragma: no cover - offset 非负时上面的循环总会命中
+
+
+def _up_stretch_start(profile: DemoProfile, index: int) -> float:
+    """当前这段"在线"是从这一轮的哪个偏移开始的（用来算会话时长）。"""
+    starts = _phase_starts(profile)
+    start = 0.0
+    for i, phase in enumerate(profile.phases):
+        if i == index:
+            break
+        if phase.state in (DISCONNECTED, RETRYING):
+            start = starts[i] + phase.seconds
+    return start
+
+
+def _events(profile: DemoProfile, started: float, now: float) -> list[dict[str, Any]]:
+    """最近几次状态转换，按时间升序（与守护进程写进状态文件的顺序一致）。
+
+    转换发生在每一段的起点，所以"最近几条"可以从当前这一轮往回数出来——不需要在内存里
+    维护历史，也不需要真的等它发生。
+    """
+    starts = _phase_starts(profile)
+    elapsed = max(0.0, now - started)
+    cycle = profile.cycle_seconds
+    offset = elapsed % cycle
+    events: list[dict[str, Any]] = []
+    index = min(_locate(profile, offset), len(profile.phases) - 1)
+
+    for cycle_index in range(int(elapsed // cycle), -1, -1):
+        for i in range(index, -1, -1):
+            at = started + cycle_index * cycle + starts[i]
+            if at > now:
+                continue
+            events.append(_event_for(profile.phases[i], at))
+            if len(events) >= _FEED_LIMIT:
+                break
+        if len(events) >= _FEED_LIMIT:
+            break
+        index = len(profile.phases) - 1
+    events.reverse()
+    return events
+
+
+def _event_for(phase: Phase, at: float) -> dict[str, Any]:
+    """一段的起点对应什么事件。``UNKNOWN`` 不发事件——"探针没问出结论"不是隧道发生的事。"""
+    if phase.state == CONNECTED:
+        return {"at": at, "type": "connected"}
+    if phase.state == DISCONNECTED:
+        return {"at": at, "type": "disconnected", "reason": phase.reason}
+    if phase.state == RETRYING:
+        return {
+            "at": at,
+            "type": "retrying",
+            "attempt": 1,
+            "delay": phase.attempt_interval,
+        }
+    return {}  # UNKNOWN：填位，下面过滤掉
+
+
+def _profile_payload(profile: DemoProfile, *, started: float, now: float) -> dict[str, Any]:
+    """把时间轴上的某一刻换算成一段状态文件里的段落。"""
+    cycle = profile.cycle_seconds
+    elapsed = max(0.0, now - started)
+    cycles, offset = divmod(elapsed, cycle)
+    index = _locate(profile, offset)
+    phase = profile.phases[index]
+    starts = _phase_starts(profile)
+    into = offset - starts[index]
+    up = _is_up(phase.state)
+
+    # 可用 / 不可用时间的累计：整轮 + 本轮已经走过的部分。
+    up_per_cycle = sum(p.seconds for p in profile.phases if _is_up(p.state))
+    up_before = sum(p.seconds for p in profile.phases[:index] if _is_up(p.state))
+    uptime = cycles * up_per_cycle + up_before + (into if up else 0.0)
+    downtime = max(0.0, elapsed - uptime)
+    total = uptime + downtime
+
+    # 会话：第 0 秒就有第一条；只有在真的会掉线的 profile 上，每轮"重连回来"那一 段再添一条。
+    retry = profile.retry_phase
+    per_cycle_reconnects = 1 if retry is not None else 0
+    sessions = (
+        1
+        + int(cycles) * per_cycle_reconnects
+        + (1 if index >= profile.reconnect_index else 0)
+    )
+    reconnects = sessions - 1
+    attempts = 1
+    if retry is not None:
+        per_cycle = max(1, int(math.ceil(retry.seconds / retry.attempt_interval)))
+        attempts += int(cycles) * (1 + per_cycle)
+        if index >= profile.reconnect_index:
+            attempts += per_cycle
+        elif phase.state == RETRYING:
+            attempts += int(into // retry.attempt_interval)
+
+    # 最近一次断线：本轮里在当前位置之前的那次，否则上一轮的最后一次。
+    disconnects = [
+        (starts[i], p.reason)
+        for i, p in enumerate(profile.phases)
+        if p.state == DISCONNECTED
+    ]
+    last_down_at: float | None = None
+    last_down_reason: str | None = None
+    if disconnects:
+        before = [item for item in disconnects if item[0] <= offset]
+        if before:
+            at_offset, last_down_reason = before[-1]
+            last_down_at = started + cycles * cycle + at_offset
+        elif cycles >= 1:
+            # 上一轮确实走完了，取那一轮的最后一次断线。
+            at_offset, last_down_reason = disconnects[-1]
+            last_down_at = started + (cycles - 1) * cycle + at_offset
+        # 否则就是"还没断过"：进程启动还不满一个周期、本轮也还没走到断线那一段。回头去取
+        # 上一轮是错的——那一轮根本没发生过，页面会写出"已运行 1 分 20 秒"+"上次断线 2 分钟
+        # 前"这种自相矛盾的组合，而这恰恰是演示模式最不该犯的错（它的全部用处就是给人看页面）。
+
+    notified: float | None = None
+    if profile.notify_every:
+        bucket = int(cycles) - (int(cycles) % profile.notify_every)
+        candidate = started + bucket * cycle + starts[profile.reconnect_index - 1]
+        notified = candidate if candidate <= now else None
+
+    # 会话起点：从不掉线的那条从启动算起（否则每一轮都会"重新开始"，而会话数却没变）；
+    # 会掉线的那条，起点就是本轮这条"在线"区间的开头。
+    if profile.disconnects:
+        session_start = started + cycles * cycle + _up_stretch_start(profile, index)
+    else:
+        session_start = started
+
+    healthy = phase.state == CONNECTED and not phase.reason
+    conclusive = phase.state != UNKNOWN
+    return {
+        "destination": profile.destination,
+        "jump": profile.jump,
+        "healthy": healthy,
+        "process_alive": up,
+        "health_error": phase.reason if phase.state == CONNECTED and phase.reason else None,
+        "health_conclusive": conclusive,
+        "probe_error": phase.reason if phase.state == UNKNOWN else None,
+        "error": phase.reason if phase.state in (DISCONNECTED, RETRYING) and phase.reason else None,
+        "remote_ports": {
+            str(port): _port_state(phase, remote=True) for port in profile.remote_ports
+        },
+        "local_ports": {
+            str(port): _port_state(phase, remote=False) for port in profile.local_ports
+        },
+        "connect_attempts_total": attempts,
+        "sessions_total": sessions,
+        "reconnects_total": reconnects,
+        "tunnel_uptime_seconds": round(uptime, 1),
+        "tunnel_downtime_seconds": round(downtime, 1),
+        "availability": round(uptime / total, 3) if total else None,
+        "current_session_at": (session_start if up else None),
+        "last_disconnect_at": last_down_at,
+        "last_disconnect_reason": last_down_reason,
+        "last_notification_at": notified,
+        "recent_events": [event for event in _events(profile, started, now) if event],
+    }
+
+
+def _port_state(phase: Phase, *, remote: bool) -> bool:
+    """端口在某一刻的样子。
+
+    ``UNKNOWN`` 返回 ``False`` 只是为了给出一个值——调用方在那种状态下会把整个映射**丢掉**
+    （"未观测"必须与"观测到关闭"区分开），见 :func:`_profile_payload`。
+    """
+    if phase.state != CONNECTED:
+        return False
+    return not (remote and phase.reason)
+
+
+
+
+
+class DemoStatus:
+    """``ponte serve`` 的状态来源：一个可调用的演示 payload 生成器。
+
+    只要能被调用、且返回 ``ponte status --json`` 那样的字典，就可以当 provider——看板的
+    HTTP 层因此不需要为演示模式改动任何东西。
+    """
+
+    def __init__(self, *, started_at: float | None = None) -> None:
+        self.started_at = time.time() if started_at is None else started_at
+        #: 演示的"守护进程"就是提供看板的这个进程，pid 因此是真的。
+        self.pid = os.getpid()
+
+    def payload(self, *, now: float | None = None) -> dict[str, Any]:
+        """某一刻的完整 payload（``now`` 可注入，便于测试钉住时刻）。"""
+        moment = time.time() if now is None else now
+        profiles: dict[str, dict[str, Any]] = {}
+        for profile in _PROFILES:
+            section = _profile_payload(profile, started=self.started_at, now=moment)
+            if not section["health_conclusive"]:
+                # "未观测"与"观测到关闭"必须区分开（#25）：整张映射丢掉，而不是留一堆 False。
+                section["remote_ports"] = {}
+                section["local_ports"] = {}
+            profiles[profile.name] = section
+        healthy = all(section["healthy"] for section in profiles.values())
+        return {
+            "running": True,
+            "pid": self.pid,
+            "started_at": self.started_at,
+            "uptime_seconds": max(0.0, moment - self.started_at),
+            "healthy": healthy,
+            "demo": True,
+            "profiles": profiles,
+        }
+
+    def __call__(self) -> dict[str, Any]:
+        return self.payload()
diff --git a/ponte/main.py b/ponte/main.py
index 6832226..533b67c 100644
--- a/ponte/main.py
+++ b/ponte/main.py
@@ -17,6 +17,7 @@
 import sys
 import time
 import webbrowser
+from collections.abc import Callable
 from pathlib import Path
 from typing import TYPE_CHECKING, NoReturn
 
@@ -41,6 +42,7 @@
 )
 from ponte.core import ProbeError
 from ponte.daemon import _format_duration
+from ponte.demo import DemoStatus
 from ponte.doctor import FAIL, OK, SKIP, WARN, counts, run_checks
 from ponte.serve import create_server, serve_url
 
@@ -720,24 +722,51 @@ def serve(
         None, "--refresh", min=1, help="看板自动刷新间隔（秒）"
     ),
     open_browser: bool = typer.Option(False, "--open", help="启动后在浏览器里打开看板"),
+    demo: bool = typer.Option(
+        False,
+        "--demo",
+        help="用内置的示例数据启动（不读配置、不看守护进程）；页面与 payload 会标明是演示数据",
+    ),
 ) -> None:
     """启动本地 HTTP 服务：看板 / 、探活 /healthz、指标 /metrics、快照 /status.json。"""
-    try:
-        daemon = _daemon()
-        effective = _serve_config(
-            daemon.config.serve, host=host, port=port, token=token, refresh=refresh
-        )
-        # 与配置文件走同一条校验：绑定非回环地址却没有令牌时直接拒绝，
-        # 不提供“先跑起来再说”的选项。
-        effective.check_bind()
-    except typer.Exit:
-        raise
-    except Exception as exc:
-        _fail(str(exc))
+    if demo:
+        # 演示模式刻意不碰配置、也不碰守护进程：还没有隧道的人（或者不想为了看一眼页面
+        # 去连真服务器的人）也该能看见这个页面长什么样。数据是内置的，而且在页面、
+        # payload 与下面这行输出里都标明它是演示数据（见 ``ponte.demo``）。
+        try:
+            effective = _serve_config(
+                ServeConfig(), host=host, port=port, token=token, refresh=refresh
+            )
+            # 绑定校验照旧：演示数据看起来仍然像一张内网拓扑图，暴露到网上一样危险。
+            effective.check_bind()
+        except typer.Exit:
+            raise
+        except Exception as exc:
+            _fail(str(exc))
+        provider: Callable[[], dict] = DemoStatus()
+    else:
+        try:
+            daemon = _daemon()
+            effective = _serve_config(
+                daemon.config.serve, host=host, port=port, token=token, refresh=refresh
+            )
+            # 与配置文件走同一条校验：绑定非回环地址却没有令牌时直接拒绝，
+            # 不提供“先跑起来再说”的选项。
+            effective.check_bind()
+        except typer.Exit:
+            raise
+        except Exception as exc:
+            _fail(str(exc))
+
+        def live_status() -> dict:
+            """每次请求都重新取一次真实状态（接口本身从不缓存）。"""
+            return _status_payload(daemon.status())
+
+        provider = live_status
 
     try:
         server = create_server(
-            lambda: _status_payload(daemon.status()),
+            provider,
             host=effective.host,
             port=effective.port,
             token=effective.token,
@@ -750,6 +779,10 @@ def serve(
         )
 
     url = serve_url(effective.host, effective.port)
+    if demo:
+        console.print(
+            "[yellow]演示模式：看板展示的是内置示例数据（example.com），不是你的隧道[/yellow]"
+        )
     console.print(f"[green]ponte 看板已启动：{url}[/green]")
     console.print(
         f"[dim]指标 {url}metrics · 探活 {url}healthz · 快照 {url}status.json[/dim]"
diff --git a/ponte/serve.py b/ponte/serve.py
index e8ad87a..4ecc494 100644
--- a/ponte/serve.py
+++ b/ponte/serve.py
@@ -783,7 +783,7 @@ def add(
 <main id="board">$board</main>
 <footer>
   <span class="live" id="live">每 $refresh 秒自动刷新（无脚本时整页刷新）</span>
-  <button class="pause" id="pauser" type="button" hidden>暂停</button>
+  <button class="pause" id="pauser" type="button" hidden>暂停</button>$demo_note
   <span class="links">数据来自 ponte status 的同一份状态，点任意一行看明细 ·
   <a href="/status.json">status.json</a> ·
   <a href="/metrics">metrics</a> ·
@@ -1075,6 +1075,16 @@ def _feed(section: Mapping[str, Any]) -> str:
     return "".join(lines)
 
 
+def _demo_note(payload: Mapping[str, Any]) -> str:
+    """Footer line for ``ponte serve --demo``: says where the data came from, in words."""
+    if not payload.get("demo"):
+        return ""
+    return (
+        '\n  <span class="muted">演示模式：内置示例数据（example.com），不是你的隧道；'
+        "看自己的状态请用 <code>ponte status</code> / <code>ponte serve</code></span>"
+    )
+
+
 def _identity(name: str, section: Mapping[str, Any]) -> str:
     """Who this tunnel is: its name, verdict, destination and jump chain."""
     parts = [
@@ -1238,7 +1248,21 @@ def _tunnel(name: str, section: Mapping[str, Any], *, now: float) -> str:
 
 
 def _summary(payload: Mapping[str, Any], profiles: Mapping[str, Any]) -> str:
-    """The header: the verdict, one tile per state that occurs, then daemon facts.
+    """The header, with a leading marker when this payload is ``ponte serve --demo`` data.
+
+    The marker comes first because it qualifies *everything* after it: a screenshot of
+    this page must never be readable as somebody's real infrastructure. It rides on the
+    payload (``demo: true``) rather than a server flag, so ``/status.json`` says the same
+    thing and the in-place refresh cannot "lose" the marker by re-rendering.
+    """
+    text = _summary_body(payload, profiles)
+    if payload.get("demo"):
+        return _pill("演示数据", "unknown") + text
+    return text
+
+
+def _summary_body(payload: Mapping[str, Any], profiles: Mapping[str, Any]) -> str:
+    """The verdict, one tile per state that occurs, then daemon facts.
 
     The counts are tiles rather than a sentence because "two of eleven" is read
     from the page's shape long before any of the words are: a zero-count tile is
@@ -1324,6 +1348,7 @@ def dashboard_html(
         title="隧道看板",
         summary=_summary(payload, profiles),
         board=board,
+        demo_note=_demo_note(payload),
     )
 
 
diff --git a/tests/test_demo.py b/tests/test_demo.py
new file mode 100644
index 0000000..4362291
--- /dev/null
+++ b/tests/test_demo.py
@@ -0,0 +1,287 @@
+"""``ponte serve --demo`` 的测试：内置示例时间轴、payload 契约与命令接线。
+
+演示模式的价值全在"它说的是真的"上：一份随时间推进、覆盖看板会渲染的每种状态的数据，
+而且**确定**——同一时刻永远是同一个 payload。所以这些测试钉的是**时刻**，不是运气：
+时间通过 ``now`` 注入，测试里没有一处 ``sleep``。
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+from typer.testing import CliRunner
+
+from ponte import demo
+from ponte.daemon import DaemonStatus, ProfileStatus
+from ponte.main import _status_payload, app
+from ponte.serve import dashboard_html, health_response, render_metrics
+
+_START = 1_000_000.0
+
+
+def _payload(seconds: float) -> dict:
+    """演示的某一刻（``started_at`` 固定，避免依赖真实时间）。"""
+    return demo.DemoStatus(started_at=_START).payload(now=_START + seconds)
+
+
+def _section(seconds: float, name: str) -> dict:
+    return _payload(seconds)["profiles"][name]
+
+
+# ---------------------------------------------------------------------------
+# 时间轴：三种状态都真的会出现，而且会自己走
+# ---------------------------------------------------------------------------
+
+
+def test_timeline_walks_a_tunnel_through_disconnect_and_reconnect() -> None:
+    """``web`` 这条演示隧道：健康 → 断线 → 重连退避 → 又连上，会话数跟着加一。
+
+    这是看板存在的理由那件事：状态**会变**，所以页面上的数字、事件流与"上次断线"都该动。
+    """
+    connected = _section(10.0, "web")
+    assert connected["healthy"] is True
+    assert connected["process_alive"] is True
+    assert connected["remote_ports"] == {"23334": True}
+    assert connected["current_session_at"] == _START
+
+    disconnected = _section(145.0, "web")
+    assert disconnected["healthy"] is False
+    assert disconnected["health_conclusive"] is True
+    assert disconnected["process_alive"] is False
+    assert disconnected["remote_ports"] == {"23334": False}
+    assert disconnected["current_session_at"] is None
+    assert "code 255" in disconnected["last_disconnect_reason"]
+
+    retrying = _section(152.0, "web")
+    assert retrying["healthy"] is False
+    assert retrying["connect_attempts_total"] > disconnected["connect_attempts_total"]
+
+    recovered = _section(170.0, "web")
+    assert recovered["healthy"] is True
+    assert recovered["sessions_total"] == disconnected["sessions_total"] + 1
+    assert recovered["reconnects_total"] == recovered["sessions_total"] - 1
+    assert recovered["availability"] < 1.0, "掉过线就不该是 100% 可用"
+
+
+def test_probe_without_a_verdict_is_not_reported_as_a_dead_port() -> None:
+    """``metrics`` 那条演示：探针没问出结论时，端口是**未观测**，不是"未监听"（#25）。
+
+    这条盯的是演示数据会不会把"我们没法问"渲染成"问了，答案是坏"——那正是 #25 修掉的
+    误导，一份用来展示前端的示例数据同样不该犯。
+    """
+    unknown = _section(175.0, "metrics")
+    assert unknown["healthy"] is False
+    assert unknown["health_conclusive"] is False
+    assert unknown["probe_error"]
+    assert unknown["remote_ports"] == {}
+    assert unknown["local_ports"] == {}
+
+    # db 在"SSH 连上了、服务器那一侧端口没起来"那段里是**确定失败**（取它本轮的前 25 秒，
+    # 其余时间是掉线 + 退避）：两种 false 必须能被看板区分开。
+    broken = _section(10.0, "db")
+    assert broken["healthy"] is False
+    assert broken["health_conclusive"] is True
+    assert broken["health_error"]
+    assert broken["remote_ports"] == {"5432": False}
+    assert broken["local_ports"] == {"5432": True}, "本机在听、服务器没听：两列本就不同"
+
+
+def test_nothing_claims_to_have_happened_before_the_process_started() -> None:
+    """演示数据不能声称在守护进程**启动之前**断过线，也不能报出未来的时刻。
+
+    页头写着“已运行 1 分 20 秒”，而 web 那行写着“上次断线 2 分钟前”——一条比进程本身还老的
+    故障记录。这条测试沿时间轴扫一遍，把“事件／断线时刻必须落在 [启动时刻, 现在] 之间”钉死。
+    """
+    # 启动后第一个周期里还没断过线时，“上次断线”是空的，不是回头取上一轮。
+    early = _section(80.0, "web")
+    assert early["healthy"] is True
+    assert early["last_disconnect_at"] is None
+    assert early["last_disconnect_reason"] is None
+    assert _section(10.0, "db")["last_disconnect_at"] is None
+
+    # 真的断过之后就有值，而且就是那一刻（web 在 140s 断线）。
+    assert _section(145.0, "web")["last_disconnect_at"] == pytest.approx(_START + 140.0)
+
+    # 全时间轴扫一遍：没有任何一条记录落在启动之前或现在之后。
+    for seconds in range(0, 1200, 3):
+        now = _START + seconds
+        for name in ("web", "db", "metrics"):
+            section = _section(float(seconds), name)
+            for key in ("last_disconnect_at", "current_session_at", "last_notification_at"):
+                moment = section[key]
+                assert moment is None or _START <= moment <= now, (seconds, name, key, moment)
+            for event in section["recent_events"]:
+                assert _START <= event["at"] <= now, (seconds, name, event)
+
+
+def test_a_tunnel_that_never_disconnects_keeps_one_session() -> None:
+    """从不掉线的 ``metrics`` 不该被凭空记出更多会话或更多的可用时间。"""
+    # 第 0 秒还没有任何累计值，可用率诚实地是 None（看板显示”—“）而不是编一个 100%。
+    assert _section(0.0, "metrics")["availability"] is None
+    for seconds in (210.0, 1000.0, 5000.0):
+        section = _section(seconds, "metrics")
+        assert section["sessions_total"] == 1, seconds
+        assert section["reconnects_total"] == 0, seconds
+        assert section["current_session_at"] == _START, seconds
+        assert section["availability"] == 1.0, seconds
+
+
+def test_counters_never_go_backwards() -> None:
+    """统计只增不减——看板把它们当累计值显示，倒退比数字难看严重得多。"""
+    previous: dict[str, float] = {}
+    for seconds in range(0, 1200, 7):
+        section = _section(float(seconds), "web")
+        for key in ("sessions_total", "reconnects_total", "connect_attempts_total",
+                    "tunnel_uptime_seconds", "tunnel_downtime_seconds"):
+            value = section[key]
+            assert value >= previous.get(key, 0.0), f"{key} 在 {seconds}s 退回去了"
+            previous[key] = value
+
+
+def test_the_event_feed_grows_and_stays_ordered() -> None:
+    """事件流按时间升序、带上真实时刻，而且会随断线重连多起来（看板的 feed 就靠它动）。"""
+    early = _section(30.0, "web")["recent_events"]
+    later = _section(400.0, "web")["recent_events"]
+    assert len(later) > len(early), "过了几轮之后事件流该更长"
+    assert len(later) <= demo._FEED_LIMIT
+
+    stamps = [event["at"] for event in later]
+    assert stamps == sorted(stamps), "事件必须按时间升序（看板按这个顺序倒着渲染）"
+    assert all(stamp <= _START + 400.0 for stamp in stamps), "不该出现未来的事件"
+    assert {"connected", "disconnected"} <= {event["type"] for event in later}
+
+
+# ---------------------------------------------------------------------------
+# payload 契约：演示数据必须长得和真数据一样，否则它就在教看板错误的样子
+# ---------------------------------------------------------------------------
+
+
+def test_payload_matches_the_status_json_contract_exactly() -> None:
+    """与真实的 ``ponte status --json``（``_status_payload``）逐键对比。
+
+    这是这份数据唯一真正危险的地方：它是**手写的**。契约以后长出新字段时，演示数据会悄悄
+    落后，而它看起来完全一样——所以这里直接问产品自己那份构造器要键集合，而不是抄一份
+    清单下来自己维护。
+    """
+    real = _status_payload(
+        DaemonStatus(
+            running=True,
+            pid=4242,
+            started_at=_START,
+            uptime_seconds=3600.0,
+            profiles=[ProfileStatus(name="web", destination="deploy@edge.example.com:22")],
+        )
+    )
+    demo_payload = _payload(10.0)
+
+    assert set(demo_payload) - set(real) == {"demo"}, "演示 payload 只该多一个 demo 标记"
+    assert set(real) - set(demo_payload) == set()
+    assert set(demo_payload["profiles"]["web"]) == set(real["profiles"]["web"])
+
+    assert demo_payload["demo"] is True
+    assert set(demo_payload["profiles"]) == {"web", "db", "metrics"}
+
+
+def test_demo_data_is_labelled_in_the_payload_and_on_the_page() -> None:
+    """演示数据必须在**三处**都自证：payload、页面头部、页面页脚。
+
+    第一处给脚本和 ``/status.json``，后两处给截图——一张看板截图看起来就像某个人的内网
+    拓扑图，所以它自己得说清楚这不是。
+    """
+    payload = _payload(152.0)
+    assert payload["demo"] is True
+    assert payload["pid"] == os.getpid(), "演示的\"守护进程\"就是提供页面的这个进程"
+    assert payload["running"] is True
+    assert payload["uptime_seconds"] == pytest.approx(152.0)
+
+    html = dashboard_html(payload, refresh=5, now=_START + 152.0)
+    assert "演示数据" in html
+    assert "演示模式" in html
+
+    without_flag = {key: value for key, value in payload.items() if key != "demo"}
+    assert "演示数据" not in dashboard_html(without_flag, refresh=5, now=_START + 152.0)
+
+
+def test_the_endpoints_consume_demo_data_at_every_moment() -> None:
+    """整条时间轴上，三个端点都渲染得出来——包括刚启动的第 0 秒。
+
+    首次加载恰好发生在 t≈0（那时可用率还没有累计值，是 ``None``），所以这里从头到尾走一遍，
+    而不是只挑几个"数据好看"的时刻。
+    """
+    for seconds in (0.0, 1.0, 30.0, 145.0, 152.0, 170.0, 175.0, 210.0, 1000.0):
+        payload = _payload(seconds)
+        html = dashboard_html(payload, refresh=5, now=_START + seconds)
+        assert html.startswith("<!DOCTYPE html>"), seconds
+        code, body = health_response(payload)
+        assert code in (200, 503), seconds
+        assert body["profiles"] == 3, seconds
+        assert "ponte_" in render_metrics(payload, now=_START + seconds), seconds
+
+
+def test_same_moment_always_renders_the_same_payload() -> None:
+    """确定性：同一时刻两次取到的 payload 完全相同（否则测试只能靠等，看板也只能靠猜）。"""
+    provider = demo.DemoStatus(started_at=_START)
+    assert provider.payload(now=_START + 152.0) == provider.payload(now=_START + 152.0)
+    assert provider.payload(now=_START + 1.0) != provider.payload(now=_START + 152.0)
+
+
+# ---------------------------------------------------------------------------
+# 命令接线：--demo 不读配置、不碰守护进程，但绑定校验照旧
+# ---------------------------------------------------------------------------
+
+
+def test_demo_mode_needs_no_config_and_never_touches_the_daemon(monkeypatch) -> None:
+    """``serve --demo`` 在没有配置文件、没有守护进程时也要能起来。
+
+    "不碰守护进程"是这条测试的重点：一旦它去读配置，演示模式就又有了一道"先有隧道才行"
+    的门槛，而这个模式存在的全部理由就是没有隧道也能看见页面。
+    """
+
+    def explode(*args, **kwargs):  # pragma: no cover - 被调用即测试失败
+        raise AssertionError("演示模式不该碰守护进程或配置加载")
+
+    monkeypatch.setattr("ponte.main._daemon", explode)
+    monkeypatch.setattr("ponte.main.get_config", explode)
+
+    captured: dict = {}
+
+    class _Server:
+        def serve_forever(self, poll_interval: float = 0.5) -> None:
+            raise KeyboardInterrupt  # 让命令干净地退出，而不是在测试里真的服务
+
+        def server_close(self) -> None:
+            captured["closed"] = True
+
+    def fake_create_server(provider, **kwargs):
+        captured["provider"] = provider
+        captured["options"] = kwargs
+        return _Server()
+
+    monkeypatch.setattr("ponte.main.create_server", fake_create_server)
+
+    result = CliRunner().invoke(app, ["serve", "--demo", "--port", "8791"])
+
+    assert result.exit_code == 0, result.output
+    assert "演示模式" in result.output
+    assert captured["closed"] is True
+    assert captured["options"] == {
+        "host": "127.0.0.1",
+        "port": 8791,
+        "token": "",
+        "refresh": 5,
+    }
+    payload = captured["provider"]()
+    assert payload["demo"] is True
+    assert set(payload["profiles"]) == {"web", "db", "metrics"}
+
+
+def test_demo_mode_still_refuses_to_expose_the_dashboard_without_a_token(monkeypatch) -> None:
+    """演示数据看起来仍然像一张内网拓扑图，所以绑定规则不能因为是演示而放松。"""
+    monkeypatch.setattr(
+        "ponte.main.create_server",
+        lambda *a, **k: pytest.fail("校验不该走到建服务器这一步"),
+    )
+    result = CliRunner().invoke(app, ["serve", "--demo", "--host", "0.0.0.0"])
+    assert result.exit_code != 0
+    assert "令牌" in result.output