LANtern 🏮 局域网模型灯塔
把本机 DSH 的全部模型，照亮给同一局域网。
English · 中文
这是什么
你在本机 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 不会热应用到正在运行的进程，必须重启；重启后刷新浏览器页面。
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> 作为公开名，理由是：
- 唯一性：同名模型可能来自多个 provider
- 可读性：一眼看出请求会走哪个账号
- 强制显式：避免"以为在用 A，实际走了 B"的静默行为
唯一提供者也不省略后缀 —— 规则一视同仁，才不会在新增 provider 后突然歧义。
排错
局域网连不上
- 先确认绑定地址：设置 → LANtern → 监听与端口，看「绑定」列
- 显示
127.0.0.1 → 只绑了本机，局域网必然连不上
- 显示
0.0.0.0 → 绑定正确，问题在防火墙或网络
- 检查防火墙：Windows 首次监听会弹窗询问，需要允许"专用网络"
- 确认端口：
standalone 用你填的端口；reuse 用 DSH 自己的端口
- 两台设备在同一网段吗？（手机连的是不是同一个 WiFi）
返回 401
Key 不对或没带。检查请求头：OpenAI 风格用 Authorization: Bearer <Key>，
Anthropic 风格用 x-api-key: <Key>。
返回 404 且提示未知模型
模型名没写 @provider 后缀。响应体里附带可用列表，照抄即可。
返回 429
触发了限速（每 Key rpm/tpm）或上游限流。前者去设置里调限额；后者等冷却结束。
返回 503
可能是熔断生效（上游连续限流）。设置 → 诊断 里能看到熔断状态与剩余冷却时间。
流式响应中途出现 error 事件
上游出错了。LANtern 会以协议内的错误帧如实透出，而不是伪装成"正常结束的空回答"。
责任边界：只透出 DSH 已感知到的错误；provider 自身的静默行为（例如忽略某个参数）
原样转发，不伪造。
已知限制
- 上游额度共享 —— 局域网请求与本机对话共用额度，这是设计前提，无法消除。
- 依赖 DSH 的模型注册表 —— DSH 未注册的 provider，LANtern 也看不到。
- 能力声明 ≠ 网关放行 —— 某个模型声明支持某能力，不代表上游真的能跑通；
可以用模型页的「功能测试」实测（真实调用，消耗额度）。
- 功能测试与性能测试会消耗上游额度 —— 且测试结果不会自动改写能力声明，
仅供你参考；要改声明请直接点能力行的复选框。
兼容性
| 项目 | 要求 |
|---|
| DSH | 0.1.5-rc.2 上实测可用 |
| 平台 | web |
| Node.js | ^22.19.0 || >=24.0.0 |
| 依赖 | @deepseek-ai/dsh-llm（由 DSH 环境提供） |
许可证
MIT
