doc/FAQ.md

Rama main · réplica de lectura del repositorio original.

# 常见问题（FAQ）

[文档导航](README.md) · [首次部署](first-deployment.md) · [部署与维护](../deploy/README.md)

## 如何设置接入框架的插件的新会话默认模型？

管理员打开 `/auth` →“模型设置”，选择模型卡片右上角的单选项，自动保存到官方宿主设置，无需重启。仅新会话使用新默认，已有会话按官方记录恢复待生效或最近使用的模型，分支读取分支点之前的记录。模型密钥在下方“服务商 API 密钥”中管理；选择模型不会验证余额或执行付费请求。第三方插件需要接入 kit 的 `conversationModel()`，硬编码模型不会自动改变；专用识图等能力路由可由插件保留。模型目录和保存能力由官方 `agentDefaultModel` 等服务提供；宿主缺少能力或路由不可用时会报错，不静默切到硬编码模型。

## 如何添加或停用自定义模型？

自定义模型目录由官方宿主管理，Auth 展示该目录并选择默认值。先确认目标提供方的实际型号、路由、输入能力和账号调用权限，再备份站点 DSH home 的 `settings.yaml`，通过官方控制台添加配置；不要把临时型号视为框架固定默认值。

直接编辑 `llm-deepseek.models` 等官方提供方配置时，保留已有模型条目；显式列表会替换默认目录。模型 ID、API 路由和 `inputModalities` 应按提供方与宿主说明填写，不能凭名称推测图片能力。

默认宿主会热加载模型目录，无需重启或重建镜像。保存后在 `/auth` 的模型设置中核对目录，并验证真实请求；需要设为普通新会话默认时，再单独选择。目录中可见不等于账号额度、模型调用或图片工作流已验证通过。

停用或到期前先选回可用模型，并检查仍记录原型号的旧会话；更改默认值不会迁移已有会话。站点模型目录配置不改变框架版本。

## Auth 登录后为什么根路径仍提示认证？

<!-- excerpt:root-auth -->
根路径出现 `dsh web authentication required`，表示官方控制台需要其自己的启动认证地址。/auth 的插件账号、官方控制台令牌和模型 API 密钥是三种不同凭据。仅使用业务应用时从 /auth 进入已授权应用即可。

需要官方控制台时，在私有本机文件中读取本次启动生成的认证 URL（默认 .local/data/dsh-web-auth-url.txt；自定义路径看实际输出），仅在自己的浏览器访问。不分享其中 token；填模型 API 密钥不会修复控制台登录，重启后应使用本次的新地址。
<!-- /excerpt:root-auth -->

## 官方认证地址为什么会失效？

启动令牌随官方 DSH 进程重新生成。服务重启后重新读取当前文件，不用旧书签中的 token。清理 Cookie、更换浏览器或更换域名后，也可能需要重新认证。有效的既有 Cookie 不一定随每次重启失效。

如果文件中的域名不对，检查私有 env 的 `DSH_PUBLIC_URL`、`DSH_PUBLIC_ORIGIN` 与实际访问地址，并按部署流程应用配置。如果完整的新地址仍返回 401，检查反向代理是否保留查询参数、正确转发 Host 和 Cookie；不要通过关闭认证解决。

## 控制台能打开，但模型和插件报 HTTP 403 怎么办？

检查实际访问域名是否进入官方 DSH 的 `trustedHosts`。仅配置 `publicUrl`、`publicOrigin` 不会自动允许公网域名调用控制台 API。在私有 `env.conf` 中填写 `DSH_TRUSTED_HOSTS=["dsh.example.com"]`，将示例域名替换为实际主机名，保留其他设置及已有信任项。旧显式站点 JSON 仍使用 `trustedHosts` 字段；已有站点先让部署入口导入旧文件，不能复制默认模板，使部署入口忽略旧配置。值不带协议或路径；需要限定端口时，使用与请求 Host 一致的 `主机名:端口`。

按正常部署流程应用配置并受控重启，再读取当前认证地址，验证模型、插件及工作区接口。不要修改生成的 Compose 或临时运行文件来代替持久配置。仍返回 403 时检查代理和 Host/Origin 是否一致；不要关闭认证。字段和示例见[访问地址配置](framework-configuration.md#首次填写)。

## 第一次如何在服务器手动录入 DeepSeek API 密钥？

优先由管理员在 /auth 的模型设置填写。交互 CLI、适用宿主和文件覆盖条件集中在[密钥管理规则](framework-configuration.md#密钥由谁管理)。不要将密钥拼入 shell 命令或复制到日志；业务插件 config 不是模型凭据来源。

## 页面显示的指纹能还原密钥吗？“已配置”代表有效吗？

不能。后端只返回 SHA-256 指纹，不返回原密钥；这是不可逆摘要，不是可解密的密文。宿主调用模型仍需原始凭据，因此原密钥由私有配置文件或官方凭据来源保存在服务器，不能仅保存摘要。管理员可比较指纹判断是否更换成功；“已配置”只表示存在凭据，不代表认证、余额、网络或模型调用验证通过。

## 为什么显示外部环境只读？

当前值来自文件或启动环境覆盖。核对实际 env.conf 和原服务管理者配置，按[来源规则](framework-configuration.md#密钥由谁管理)调整后受控应用。不要通过清空官方凭据存储来排错。

## 密钥已保存，为什么问答仍然失败？

按实际错误逐项核对：

1. **核对运行状态**：在“模型设置”刷新配置状态与指纹。写入官方存储时默认宿主无需重启，修改框架文件需受控重启；如果自定义了凭据存储路径或关闭文件监听，使用网页更新实际运行服务。
2. **写错实例**：使用与当前站点相同的 `.local/deployment.json`；CLI 参数和环境变量可覆盖实例路径，避免遗留 `DSH_HOME`、`DSH_DATA_DIR` 指向其他实例。脚本会核验活动 Compose 容器的 home 挂载。
3. **密钥被外部环境覆盖**：检查是否显示只读，以及实际模型是否使用对应的 `DEEPSEEK_API_KEY` 或 `ZHIPU_API_KEY` 引用。自定义提供方或凭据引用不在此页面的管理范围。
4. **模型选择不匹配**：设置 `DEEPSEEK_API_KEY` 不会选择模型，也不会配置其他提供方。通过 Auth“模型设置”或官方控制台选择可用默认模型，操作见[模型准备](../packages/plugin-manager/DELIVERY.md#问答应用的模型准备)。
5. **密钥或服务不可用**：核对具体模型错误，包括认证失败、余额或配额不足、限流及服务器网络异常；脚本的格式校验不验证这些条件。
6. **旧会话沿用旧模型**：改变默认模型后，新建对话再试；已有会话按官方记录恢复模型选择，不因全局默认改变而切换。

不要把包含密钥、token 或完整业务数据的日志公开。排错可以提供脱敏错误、模型与提供方标识、失败时间及相关版本。

## root 执行脚本后，容器会不会读不到密钥？

Compose 部署脚本确认活动容器与 home 后，使用 `docker exec` 以容器配置用户运行官方写入逻辑，凭据文件权限为 `0600`。独立进程部署要求以 home 和凭据文件的所有者运行，拒绝以其他用户替换文件。已有错误属主应按实际运行用户单独修正，不能递归改变整个数据目录权限。

## 健康接口都是 200，是否代表模型能回答？

不代表。探针检查宿主、安装状态及插件就绪，不执行付费模型调用。真实宿主配合模型替身的测试验证集成行为，也不能证明真实提供方的密钥、额度或网络可用。仍需在应用中新建对话，验证真实回答、流式输出与历史恢复。页面能打开并不表示模型提供方可用。

## 更新或者更换密钥会清空账号和对话吗？

网页更新选定提供方，脚本仅更新 DeepSeek 的官方存储，保留其他凭据、账号和对话；这类存储更新默认无需重启。文件覆盖模式需受控重启，应等待正在进行的回答结束。正常服务更新仍须沿用已有站点数据。保留 `.local/data`、`.local/artifacts` 和备份，不要删除 `.local` 来绕过错误，也不要对正式环境重新执行空数据初始化。

## example 能解释当前框架源码吗？

可以询问函数、接口、文件或部署流程；example 会搜索并读取随插件构建的公共源码快照，回答应引用路径、行号与快照版本。快照不包含私有插件、凭据、运行数据或历史发布说明，也不代表服务器此刻的部署状态。部署入口应查看公共 `deploy/build.sh`、`deploy/build.ps1` 及 worker；私有集成可能替换的根 build 脚本不在快照中。只更新仓库而未重新构建、部署 example 时，问答仍使用原归档中的知识与源码快照。

## 没有模型时能阅读 example 指南吗？

可以。进入已授权的 `/example`，点击“阅读 FAQ（无需模型）”，或打开同站点的 `/example/guide.md`。页面直接读取随包指南，不创建 Agent 或调用模型，仍保留应用鉴权。快捷提问和自由问答需要模型；离线指南、模型生成回答与现场部署验证是不同能力。

## 对话标题为什么在回答结束后才变化？

官方首句标题提炼可以晚于正文结束，example 会保存晚到结果并有限次刷新当前新会话历史。手动改名、分支和升级前标题受保护，后续提问不会反复改名。失败时保留回退标题，完整等待与接入规则见[自动标题](conversation-management.md#自动标题)。

## 源码更新会自动备份全部运行数据吗？

不会。build 入口保留发布产物、操作记录和本次私有配置副本，在停服后核验原容器及挂载，再安装更新；这些记录不是账号、对话或业务数据的全量备份。需要数据恢复能力时，应在更新前按数据所有者的要求独立备份并验证恢复。普通 build 只收敛部署，不恢复业务数据。

## 普通用户登录成功却不能进入应用怎么办？

由管理员检查该账号的应用授权，以及目标插件是否启用。授予应用访问权不等于授予全部业务数据权限；业务数据范围仍由应用检查。不要用官方控制台 token 替代应用授权。

## Windows、macOS 和 Linux 的源码部署入口是什么？

Windows 使用根 build.ps1，macOS/Linux 使用 build.sh。新部署包的默认方式为 archives；框架源码检出保持 source。环境、字段差异见[框架配置](framework-configuration.md)，操作见[首次部署](first-deployment.md)和[源码运维](../deploy/README.md)。

## 旧服务尚未停止，为什么提示保留源码锁？

停服前的核验也可能失败，状态不能仅凭“尚未停服”判断。普通 build 从当前现场重新收敛：先由原管理者处理仍活跃的服务再 build。遗留锁先通过 doctor 核验归属，profile unlock 不能替代站点解锁。完整规则只在[重试说明](../deploy/README.md#安装与重试)维护。

## 只改了一个插件，怎么只重建它？

站点内置插件固定全量构建，不再支持按插件点名重建（旧 `--rebuild-plugins` 已移除）：这避免了旧成功记录复用带来的误判。作者侧仍可用 `pnpm package --plugins "<ID列表>"` 只打包自己负责的插件，然后把完整发布目录整体替换 incoming 对应目录。规则与重试条件见[部署与管理](../deploy/README.md#服务器源码发版)。

## 类型检查报 TS2717，说同一个属性被声明了两次？

那是「同一个包被两条路径解析」的症状：TypeScript 按解析到的路径区分模块身份，kit 的事件通道声明（`src/events.ts` 里的 `declare module '@deepseek-ai/cordis'`）一旦被加载两次，就会报 TS2717，而两个类型看起来完全一样。做法是让每个事件通道只在 kit 的 `src/events.ts` 里声明一次，谁需要就导入那个模块；新增通道也加在那里，不要在别的文件里重复写。`pnpm check` 与打包遇到这个报错时会直接给出这条提示。

## 打包报 MISSING_EXPORT，说某个类型没有导出？

源码型内部包（只有 `src`、不产出声明文件）被按包名导入时，打包器找不到 `index.d.ts`，就把「没有这个导出」当成事实。把这类导入改成源码相对路径（例如 `../packages/common/src/participant.ts`），或者让该包像 kit 一样产出声明文件并在 `package.json` 里声明 `types`。打包与检查失败时同样会给出这条提示。