dsh-lantern

dsh plugin --profile web add dsh-lantern

<div align="center">

LANtern 🏮 局域网模型灯塔

把本机 DSH 的全部模型，照亮给同一局域网。

[English](README.en.md) · 中文




</div>

---

这是什么

你在本机 DSH 里已经配好了一堆 AI 模型（各家 provider、各自登录态、各自额度）。

手机、平板、另一台电脑却用不上它们 —— 除非你把 key 再复制一份到每台设备上。

LANtern 解决这一件事：在本机起一个 OpenAI / Anthropic 兼容的小网关，把 DSH 里已有的模型原样开放给局域网。

┌──────────────┐      ┌───────────────────┐      ┌──────────────┐
│ 手机 / 平板   │ ───► │  LANtern 网关      │ ───► │  各家 API     │
│ 另一台电脑    │ ◄─── │ （本机 DSH 内）    │ ◄─── │ （已有登录态） │
└──────────────┘      └───────────────────┘      └──────────────┘
     局域网内                 你的电脑                  上行

它不新增账号、不改你的 DSH 配置、不碰其它插件：只读地读取 DSH 已注册的模型清单，然后转发请求。

你可能关心 · 答案

要重新配一遍各家 key 吗？ · 不用。直接复用 DSH 里已有的 provider 与登录态

会改我的 DSH 设置吗？ · 不会。所有数据写在插件自己的目录里

局域网里谁能用？ · 只有持有你签发的 API Key 的设备

模型名怎么填？ · <模型>@<provider>，例如 deepseek-v4-pro@buddy（见[下文](#模型名怎么填最容易被忽略的一步)）

---

快速开始

1. 安装

需要 Node.js 与 dsh：

npm install -g @deepseek-ai/dsh

安装本插件（把 web 换成你的 profile 名，通常就是 web）：

dsh plugin --profile web add dsh-lantern

2. 重启 dsh 并刷新页面

dsh --profile web

新增的 bundle 不会热应用到正在运行的进程，必须重启；重启后刷新浏览器页面。

需要 DSH 0.1.5-rc.2 以上（0.1.5 与 0.2.0 均已实测支持，见下方「兼容的 DSH 版本」）。

3. 打开设置面板

侧边栏底部齿轮 → 左侧会多出一项 LANtern。

4. 四步跑通

步骤 · 在哪 · 做什么

① · 状态与安全 → 服务开关 · 打开总开关（默认关闭）

② · 状态与安全 → 监听与端口 · 选 standalone，绑定 0.0.0.0，端口随意（如 3081）

③ · 状态与安全 → API Key 管理 · 点「生成 Key」，立刻复制明文（只显示一次）

④ · 手机 / 另一台电脑 · 用下面的地址与 Key 调用

5. 在另一台设备上调用

把 <你的电脑IP> 换成局域网 IP（Windows 上 ipconfig 可查），<端口> 换成第 ② 步填的：

# OpenAI 兼容
curl http://<你的电脑IP>:<端口>/v1/chat/completions \
  -H "Authorization: Bearer <你生成的Key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"<模型>@<provider>","messages":[{"role":"user","content":"你好"}]}'

# 先看看有哪些模型可用
curl http://<你的电脑IP>:<端口>/v1/models \
  -H "Authorization: Bearer <你生成的Key>"

---

模型名怎么填（最容易被忽略的一步）

LANtern 强制使用全名制：<模型>@<provider>。

deepseek-v4-pro@buddy          ✅
deepseek-v4-pro                ❌ 不带 @provider 一律 404

为什么这么设计：同一个模型名可能来自多个 provider（不同账号、不同额度、不同区域版本）。

不写后缀就无法知道你指的是哪一个，所以强制写全。404 的响应里会附带可用模型列表，照着填即可。

模型清单与后缀名可以在两处看到：

• 浏览器：GET /v1/models
• 设置面板：左侧每个 provider 页里列出的模型公开名

---

公开的端点

端点 · 方法 · 说明

/v1/models · GET · 模型目录（支持 ?provider=<slug> 过滤）

/v1/models/{id} · GET · 单个模型详情（含能力与来源）

/v1/chat/completions · POST · OpenAI 兼容主推理端点（流式 / 非流式）

/v1/messages · POST · Anthropic 兼容端点（默认关闭，可在设置里开）

/v1/lantern/health · GET · 自检端点（无需鉴权，可用于探活）

Anthropic 兼容端点默认关闭。需要用 Claude Code 一类只认 Anthropic 协议的客户端时，

在 设置 → LANtern → 状态与安全 → 协议通道 里打开。

客户端怎么填

客户端 · Base URL · Key

认 OpenAI 协议的工具 · http://<IP>:<端口>/v1 · 你生成的 Key

认 Anthropic 协议的工具 · http://<IP>:<端口> · 你生成的 Key（x-api-key 头）

Key 格式默认是 sk- + 43 位 base64url（与主流厂商同形）。明文只在生成时显示一次，

服务端只存 sha256，之后无法再查看 —— 请当场保存。

---

设置面板能做什么

区块 · 作用

服务开关 · 总开关（默认关闭）；关闭后局域网请求一律被拒

监听与端口 · 增删改监听条目。standalone = 插件自开端口；reuse = 复用 DSH 端口

API Key 管理 · 生成 / 改名 / 启停 / 删除 / 轮换（新 Key 生效、旧 Key 保留过渡期）

限额与并发 · 最大并发、每 Key 每分钟请求数 / token 数、单次 max_tokens 上限、为本机保留的并发槽

模型与来源过滤 · 黑名单（命中不公开）+ 白名单（非空时只公开其中的）

协议通道 · 打开 Anthropic 兼容端点

图片输入 · 是否接受图片（默认关闭，详见下文）

用量统计 · 按 Key / 按调用类型统计 token 用量，可导出 HTML 报告

诊断 · 导出脱敏诊断信息、查看在飞请求与熔断状态

危险操作 · 解除熔断、恢复出厂设置、立即停止服务（均需二次确认）

关于 reuse 模式（重要）

reuse 复用 DSH 自己已监听的端口，它的绑定地址由 DSH 启动参数 --host 决定，本插件无权修改。

DSH 默认只监听 127.0.0.1，此时局域网访问不到。想让 reuse 也暴露到局域网，

需要以 --host 0.0.0.0 启动 DSH。

想省事就用 standalone —— 绑定地址完全由插件决定，不依赖 DSH 怎么启动。

设置页的「绑定」列显示的是实际生效的地址（不是你的配置值），并会标注它是否继承自 DSH。

---

隔离与安全性

本插件的设计原则是 只读复用、写入自留地。

写入足迹一览

位置 · 是否写入 · 说明

<插件目录>/data/ · ✅ 唯一写入处 · 配置、Key、用量账本、报告

~/.dsh/settings.yaml · ❌ 绝不写入 · 不注册任何 settings 命名空间

其它插件目录 · ❌ 绝不触碰 ·

你的会话与历史 · ❌ 绝不改动 ·

llm 注册表 · 👁 只读 · 只读取模型清单，不修改

卸载即干净

dsh plugin --profile web remove dsh-lantern

本插件自带装配层（cordis.patch.yml），卸载时会把包移出 profile 的

dsh.profile.bundles，装配层随之不再被加载 —— 不会留下悬空的 insert 行。

删掉插件目录后，data/ 里的全部数据一并消失，零残留。

卸载后同样需要重启 dsh + 刷新页面。

唯一无法消除的影响

上游额度共享。 局域网请求与你本机对话共用同一批上游账号额度。

这是它提供价值的前提（复用已有登录态），无法两全。

为此内置了保护（见下一节），目标是"宁可局域网慢一点，也不拖慢本机"。

---

保护机制：熔断、限速与过滤

机制 · 行为

并发闸门 · 限制局域网总并发；为本机保留并发槽 让本机永远有空位

每 Key 限速 · 每分钟请求数（rpm）与输出 token 数（tpm），超限返回 429

熔断 · 上游连续限流时自动暂停局域网通道（冷却期内立即 503、不打向上游、不耗额度），到期自动半开

模型过滤 · 黑名单命中即不公开；白名单非空时只公开其中的。过滤同时作用于 /v1/models 与直接调用（隐藏不等于能绕过）

能力闸门 · 不支持的请求（如给非视觉模型发图）在到达上游之前就被拒，不浪费额度

熔断只对限流触发。余额不足（402）、网络超时等不会熔断 —— 那些不是"被刷量"的信号。

---

图片功能与其影响（默认关闭）

默认关闭。关闭时图片请求直接返回 400，且零落盘。

打开后，图片字节会短暂写入本机磁盘（插件自己的附件目录），请求结束后由账本回收。

为什么必须落盘：DSH 的附件服务要求图片先入库拿到引用，才能交给模型；

本插件无法绕开这一层。

误删风险与三道防护：账本只清理"本插件自己新建、且已无引用"的对象，

复用本机既有对象永不删除；另有两道校验（引用计数 + 会话引用检查）。

默认处于 dry-run：只记日志、不真删。观察一段时间确认无误后，再在设置面板里关闭 dry-run。

若你不需要局域网发图，保持关闭即可 —— 这是更安全的默认。

---

用量统计

只统计经由本插件的调用（不含你本机 DSH 自身的对话）。

• 按时间：今日 / 本周 / 本月 / 今年
• 按 API Key：每个 Key 的调用数、token 分项、命中率
• 按调用类型：推理调用 / 功能测试 / 性能测试
• 可导出自包含单文件 HTML（无外部资源，可直接分享或存档）

口径说明（容易误解，故写明）：

• 输入分未命中与命中两部分，互不重叠
• 合计 = 未命中 + 命中 + 缓存写 + 输出（推理 token 已含在输出内，不重复计）
• 缓存命中率为 Σ命中 / Σ(未命中 + 命中)，是加权而非各行平均
• 无缓存数据时显示 —（不是 0%）

---

命名规则：为什么模型名带 @provider

DSH 的模型注册表里，model 与 provider 是两个独立维度。LANtern 把它拼成

<model>@<provider> 作为公开名，理由是：

1. 唯一性：同名模型可能来自多个 provider

2. 可读性：一眼看出请求会走哪个账号

3. 强制显式：避免"以为在用 A，实际走了 B"的静默行为

…(truncated)