Saretheya/dsh-lantern

LANtern 🏮 局域网模型灯塔

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

English · 中文

platform-web
license
dsh

这是什么

你在本机 DSH 里已经配好了一堆 AI 模型（各家 provider、各自登录态、各自额度）。
手机、平板、另一台电脑却用不上它们 —— 除非你把 key 再复制一份到每台设备上。

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

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

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

| 你可能关心 | 答案 |
|---|---|
| 要重新配一遍各家 key 吗？ | 不用。直接复用 DSH 里已有的 provider 与登录态 |
| 会改我的 DSH 设置吗？ | 不会。所有数据写在插件自己的目录里 |
| 局域网里谁能用？ | 只有持有你签发的 API Key 的设备 |
| 模型名怎么填？ | @，例如 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 不会热应用到正在运行的进程，必须重启；重启后刷新浏览器页面。

3. 打开设置面板

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

4. 四步跑通

| 步骤 | 在哪 | 做什么 |
|---|---|---|
| ① | 状态与安全 → 服务开关 | 打开总开关（默认关闭） |
| ② | 状态与安全 → 监听与端口 | 选 standalone，绑定 0.0.0.0，端口随意（如 3081） |
| ③ | 状态与安全 → API Key 管理 | 点「生成 Key」，立刻复制明文（只显示一次） |
| ④ | 手机 / 另一台电脑 | 用下面的地址与 Key 调用 |

5. 在另一台设备上调用

把  换成局域网 IP（Windows 上 ipconfig 可查）， 换成第 ② 步填的：

OpenAI 兼容
curl http://:/v1/chat/completions \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{"model":"@","messages":[{"role":"user","content":"你好"}]}'

先看看有哪些模型可用
curl http://:/v1/models \
-H "Authorization: Bearer "

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

LANtern 强制使用全名制：@。

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

为什么这么设计：同一个模型名可能来自多个 provider（不同账号、不同额度、不同区域版本）。
不写后缀就无法知道你指的是哪一个，所以强制写全。404 的响应里会附带可用模型列表，照着填即可。

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

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

公开的端点

| 端点 | 方法 | 说明 |
|---|---|---|
| /v1/models | GET | 模型目录（支持 ?provider= 过滤） |
| /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://:/v1 | 你生成的 Key |
| 认 Anthropic 协议的工具 | http://: | 你生成的 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 把它拼成
@ 作为公开名，理由是：

1. 唯一性：同名模型可能来自多个 provider
2. 可读性：一眼看出请求会走哪个账号
3. 强制显式：避免"以为在用 A，实际走了 B"的静默行为

唯一提供者也不省略后缀 —— 规则一视同仁，才不会在新增 provider 后突然歧义。

排错
局域网连不上

1. 先确认绑定地址：设置 → LANtern → 监听与端口，看「绑定」列
- 显示 127.0.0.1 → 只绑了本机，局域网必然连不上
- 显示 0.0.0.0 → 绑定正确，问题在防火墙或网络
2. 检查防火墙：Windows 首次监听会弹窗询问，需要允许“专用网络”
3. 确认端口：standalone 用你填的端口；reuse 用 DSH 自己的端口
4. 两台设备在同一网段吗？（手机连的是不是同一个 WiFi）

返回 401

Key 不对或没带。检查请求头：OpenAI 风格用 Authorization: Bearer ，
Anthropic 风格用 x-api-key: 。

返回 404 且提示未知模型

模型名没写 @provider 后缀。响应体里附带可用列表，照抄即可。

返回 429

触发了限速（每 Key rpm/tpm）或上游限流。前者去设置里调限额；后者等冷却结束。

返回 503

可能是熔断生效（上游连续限流）。设置 → 诊断 里能看到熔断状态与剩余冷却时间。

流式响应中途出现 error 事件

上游出错了。LANtern 会以协议内的错误帧如实透出，而不是伪装成“正常结束的空回答”。

责任边界：只透出 DSH 已感知到的错误；provider 自身的静默行为（例如忽略某个参数）
原样转发，不伪造。

已知限制

1. 上游额度共享 —— 局域网请求与本机对话共用额度，这是设计前提，无法消除。
2. 依赖 DSH 的模型注册表 —— DSH 未注册的 provider，LANtern 也看不到。
3. 能力声明 ≠ 网关放行 —— 某个模型声明支持某能力，不代表上游真的能跑通；
可以用模型页的「功能测试」实测（真实调用，消耗额度）。
4. 功能测试与性能测试会消耗上游额度 —— 且测试结果不会自动改写能力声明，
仅供你参考；要改声明请直接点能力行的复选框。

兼容性

| 项目 | 要求 |
|---|---|
| DSH | 0.1.5-rc.2 上实测可用 |
| 平台 | web |
| Node.js | ^22.19.0 \|\| >=24.0.0 |
| 依赖 | @deepseek-ai/dsh-llm（由 DSH 环境提供） |

许可证

MIT