六、附录
适用版本：LobeHub
2.2.20（自建版） 本篇是速查与排错，不需要从头读，遇到问题按目录跳。
A 功能速查
A.1 左侧导航（实测 8 项）
| 导航 | 一句话 |
|---|---|
| 首页 | 新对话起点，输入框 + 推荐卡片 |
| 任务 | 定时任务与后台作业 |
| 看板 | 指标卡与监控组件 |
| 资源 | 文稿/文档/图片/音频/视频/文件/作品/知识库 |
| 社区 | 助手市场 |
| 文稿 | 长文编辑器 |
| 记忆 | 五类长期记忆 |
| 生成 | 图片/视频生成入口 |
底部另有：搜索、助理列表、设置（齿轮）、帮助中心。
A.1.1
新手引导（/onboarding）现状
新账号首次登录会进 /onboarding，依次是「认识首席 Agent →
连接应用 → 了解你的世界 → 你的资料 → 推荐新手任务」，走完会在
users.onboarding 写入 finishedAt。库里 5
个账号都是 currentStep: 4
且已完成，说明流程本身能跑通。
但这个自建版有个已知缺陷：「先把几个 Agent
加入你的资料库」这一步会显示「加载模板失败，请稍后再试」。服务端日志对应
market.agent.getOnboardingFull 返回
Unauthorized，因为模板拉的是官方市场接口，自建版没有对应凭证。这时直接点「暂时跳过」就能继续，不影响后续使用。
A.1.2 帮助入口：现在点「使用文档」就是这本手册
左下角的问号图标能展开帮助菜单，其中的 「使用文档」已改为指向本站这份手册 （发布在 Halo 博客的静态目录下）。也就是说，你在界面里随手点一下，就能回到这本指南查操作，不用再去官方站翻英文文档。
这份手册和 LobeHub 是同一个域名体系下的两个站点：LobeHub 在
lobechat.1661688.xyz，手册挂在博客
blog.1661688.xyz 上。它不依赖 LobeHub
容器启动，所以即使应用正在重启，手册本身也打得开。
同一菜单里还有：应用设置、联系我们、Discord、更新日志、获取应用、GitHub。
维护提示（给运维看，普通用户可跳过）：手册正文改完后要重新构建并同步一次，链接才会跟着新内容走。若哪天博客换了主题，同步脚本会把手册自动铺到新主题目录并改写链接，无需手工重配。
A.2 设置（19 个有效路由）
侧栏「设置」里能点到的就是下面这些。旧教程常见的
/settings/agent 在本版本直访会
404（页面显示「页面不存在」），语音/ASR 等配置实际在
/settings/service-model。
| 路由 | 管什么 |
|---|---|
/settings/profile |
昵称、头像 |
/settings/appearance |
主题、语言 |
/settings/hotkey |
快捷键 |
/settings/stats |
用量统计 |
/settings/devices |
登录设备 |
/settings/provider/all |
模型供应商与模型列表 |
/settings/service-model |
标题生成、向量化、语音消息转写等服务模型（每个可选功能各自带开关） |
/settings/skill |
技能管理 |
/settings/labels |
标签 |
/settings/connector |
连接器 |
/settings/memory |
记忆 |
/settings/tools |
联网搜索与网页读取的服务顺序（不含语音，语音在
service-model） |
/settings/credential |
凭证 |
/settings/apikey |
API Key |
/settings/storage |
存储 |
/settings/trash |
回收站 |
/settings/about |
版本信息 |
/settings/advanced |
高级选项 |
/settings/labs |
实验特性 |
A.3 资源八个子类
文稿 · 文档 · 图片 · 音频 · 视频 · 文件 · 作品 · 知识库
A.4 记忆五类
身份 identities · 偏好 preferences · 上下文 contexts · 经历 activities · 规则 rules
B 常见问题
B.1 模型报错
| 症状 | 原因 | 怎么办 |
|---|---|---|
| 在对话里找不到生图模型 | 模型选择器只列对话模型，图像模型被有意分流 | 去「生成」页选，那里才有 |
| 传图后说看不到图 | 模型属于纯文本模型（如 deepseek-v4-pro） |
换用平台其余 16 款已支持视觉识别的模型（如 Gemini、GPT-6、GLM-5.3、混元4 等） |
| 回答中途断掉 | 上下文超限或上游限流 | 拆小问题；换模型重试 |
| 一直「蓄力中」不动 | 上游排队 | 等 30 秒；换 glm-5.3-flash |
| 报 429 | 触发速率限制 | 降低频率，等 1 分钟 |
报 403 Insufficient user balance |
渠道侧余额耗尽，与提示词无关 | 找管理员充值或换渠道 |
B.2 搜索无结果
| 症状 | 原因 | 怎么办 |
|---|---|---|
| 没有来源卡片 | 没触发搜索 | 加「请联网查证」 |
| 有卡片但没引用 | 搜到没用上 | 追问「只基于搜到的来源回答」 |
| 卡片空 | 三级源都失败 | 换更具体关键词 |
| 来源质量差 | 命中聚合站 | 指定「优先期刊官网」 |
B.3 沙箱超时
| 症状 | 原因 | 怎么办 |
|---|---|---|
| 卡在同一步超过 3 分钟 | 任务过重或网络问题 | 中止，拆成小任务 |
| 提示依赖缺失 | 沙箱镜像没装该库 | 换用内置库，或让助手先装 |
| 批准弹窗一直不动 | 在等你点批准 | 点「批准」 |
B.4 技能不触发
| 症状 | 原因 | 怎么办 |
|---|---|---|
| 说了需求但没挂技能 | 模型判断不需要 | 明说「使用 XX 技能」 |
| 挂了但产出是文本 | 没要求文件格式 | 补「请产出 .docx 文件」 |
| 提示技能不存在 | 没装到你账号 | 去「设置 → 技能」启用 |
B.5 上传失败
| 症状 | 原因 | 怎么办 |
|---|---|---|
| 上传卡住 | 文件过大 | 压到几十 MB 以内（注意：客户端不设上限，见下） |
| 解析出来是空白 | 扫描版 PDF | 换带视觉的模型 |
| 表格读串行 | 行列结构复杂 | 说明「请按列读取」 |
| 传了奇怪后缀没报错 | 客户端不校验类型，按文本静默接收 | 自己保证格式正确，别指望它拦 |
实测补充：11 MB、30 MB 文件都能直接传进去，全程没有任何超限提示；不认识的扩展名也不会被拒。这一层没有护栏，体积和类型要自己把关，否则大文件会挤占上下文、拖慢甚至拖垮回答。
B.6 登录异常
| 症状 | 原因 | 怎么办 |
|---|---|---|
| 输完密码没反应 | 账号未验证邮箱 | 联系管理员 |
| 页面白屏 | 部署更新后旧 chunk 失效 | 强制刷新 |
| Zero Trust 无权限 | 邮箱不在组织策略 | 联系管理员加白名单 |
| 登录后立刻跳回登录页 | Cookie 被拦 | 关闭拦截插件重试 |
「页面白屏」这一类长这样：主区显示「页面暂时不可用 / ERROR」，右下角同时弹出「There is a new version for the web app. Refresh the page to update」。看到那个新版本提示就别排查账号了，直接点「重新加载」。
刷新即恢复，数据不会丢。这是自部署站点更新后的正常短暂现象。
C 术语表
| 术语 | 解释 | 类比 |
|---|---|---|
| 上下文窗口（Context Window） | 模型一次能「看到」的 token 上限 | 桌子大小，桌子越大能摊开的资料越多 |
| Token | 模型处理文本的最小单位，约等于 0.7 个汉字 | 计价和容量都按它算 |
| Function Call | 模型调用外部工具的能力 | 它不只是说，还能伸手去拿 |
| RAG | 先检索资料再回答 | 开卷考试 |
| Embedding | 把文本变成向量，用于相似度检索 | 把句子变成坐标，意思近的离得近 |
| Agent | 有目标、能多步执行的助手 | 不是问答机，是实习生 |
| Skill | 固化的做事流程 | 菜谱 |
| Sandbox | 隔离的执行环境 | 沙盘，跑崩了不影响主站 |
| Fallback | 主方案失败时的备用方案 | 备用轮胎 |
D 移动端差异
实测结论：当前版本在窄屏（430px）下没有做移动端适配，而是把桌面三栏直接压缩。
实测数据：在 430×932
视口下，主内容区（#home-main）实际宽度只有
92px，输入框、推荐卡片、最近话题全部被挤成一条竖线，基本不可用。
| 功能 | 移动端状态 |
|---|---|
| 登录 | ✅ 正常，表单会自适应 |
| 首页浏览 | ⚠️ 主区被压到 92px，几乎不可读 |
| 对话 | ⚠️ 输入框极窄，难以输入 |
| 文稿编辑 | ⚠️ 未验证，预期同样受挤压 |
| 生图 | ⚠️ 参数面板会溢出 |
| 设置 | ⚠️ 列表可用，表单单列后勉强能填 |
当前建议：手机上只用来看结果和做简单确认，正式操作请用桌面浏览器（宽度 ≥ 1280px）。
这不是你操作的问题，是响应式布局缺失。截图
P6-03-mobile.png 和 P6-03b-mobile-chat.png
是证据。
430px 宽视口下的首页。左侧导航占满，主内容区被压成一条竖线，输入框几乎无法使用。
同一视口下的对话页。右侧动态栏和左侧导航同时存在，中间几乎没有可用空间。
E 版本与维护
E.1 适用版本
本指南基于 LobeHub 2.3.x（Next.js 16.3.8 / 2026-10-29
增强版）实测编写。全量 23 款模型配置、15
项启动补丁与路由规则均已同步验证。
E.2 四类改动触发同步
出现以下任一情况，本指南需要更新对应章节：
| 改动 | 影响章节 |
|---|---|
| 版本升级 | 全文界面描述 |
| 模型清单增删 | 2.1 模型速查 |
| 技能增删 | 2.4 技能分组 |
| 补丁变更 | 附录 B 排错 |
E.3 本版已修复的运行问题（运维参考）
写作过程中发现并修复了两个会影响 API 调用的问题，记录在此供维护者参考：
问题一：个人用户调用 /api/v1/chat 一律
403
- 现象：
{"error":"no permission,current user has no ALL permission..."} - 根因：该路由用
getAllScopePermissions("AI_MODEL_INVOKE")，只产出:all作用域；个人默认权限只有:owner。 - 修复：改为
getScopePermissions("AI_MODEL_INVOKE", ["ALL","OWNER"])。
问题二：同名模型归属判定取到别人的行
- 现象：修完权限后仍 403，提示资源不属于当前用户。
- 根因：
ai_models的唯一键是id + provider_id + user_id，同名模型在多个账号下都有记录；getResourceBelongTo只按id查，可能命中别人的行。 - 修复：先按
id + user_id查自己的副本，查不到再回退原逻辑。
问题三：第三方生图 Usage 缺失
input_tokens_details 导致报 image_tokens
异常
- 现象：NewAPI 渠道成功返回图片，但 LobeHub 界面显示「Cannot read properties of undefined (reading image_tokens)」。
- 根因：服务端
convertOpenAIImageUsage硬编码读取input_tokens_details.image_tokens，第三方上游只提供标准prompt_tokens时触发未捕获 TypeError。 - 修复：编写通用补丁
patch-image-usage.cjs，自动注入安全链与回退兼容，开箱解决所有第三方生图 Usage 统计。
问题四：全模态能力参数（Vision / Search / Audio）未标全
- 现象：部分原生具备视觉识图与联网搜索能力的模型（如
hy4-preview、glm-5.3、codex-auto-review、step-5-preview）在界面中无法传图或无法开搜索。 - 修复：全面对齐数据库
ai_models、环境变量NEWAPI_MODEL_LIST与前端缓存版本（v9），16 款对话模型已全局激活视觉识图，全量对话模型全覆盖联网搜索。
上述补丁均已固化写入容器启动脚本
desc-patch/entrypoint.sh，镜像更新或容器重建后会自动重放。
E.4 反馈
发现文档与界面不符，优先核对版本号；版本一致仍不符，按「截图 + 路由 + 操作步骤」记录后反馈给维护者。