简体中文
常见问题
Ferry 是客户端，还是模型服务？
Ferry 是运行在你自己的机器上的 AI 网关，连接客户端和上游。你继续使用 Claude Code、Codex、OpenCode、Pi 等客户端，按其配置方式填写 Ferry 的入口、Key 和逻辑模型。具体协议、工具调用和续轮能力取决于实际路由。
自带账号、模型或免费额度吗？
不提供。你需要自己的 API Key 或受支持的订阅账号。订阅登录不等于拥有全部模型的调用权限，上游账号条款和费用仍由相应供应商决定。
最简单的安装方法是什么？
使用 Docker Compose 两步安装：下载版本对应的 Compose 文件，再运行 docker compose up -d。首次进入控制台创建管理员、添加上游、检查路由并创建客户端 Key。无需拉取源码、安装 Node.js、外部数据库或 OpenBao。首次发行前，镜像和下载链接尚不可用于外部安装。
为什么服务器上的控制台打不开？
默认 Compose 只绑定宿主机 loopback，其他设备不能直接访问。先使用 SSH 隧道完成初始化；长期远程访问再配置 HTTPS 反向代理与访问限制。宿主管理端口为 17910，推理端口为 17810，不要混用。
模型显示在列表里，为什么仍调用失败？
模型目录只说明发现了模型名，不证明当前账号、端点和协议可用。检查 Key 权限、上游余额或配额、准确模型 ID、Provider 与 Connection 状态，然后查看 Requests 的选路与尝试记录。各渠道的验证范围不同。
限流后会一直 Thinking，直到成功吗？
符合策略的请求可在恢复窗口内等待，条件允许后继续。客户端显示 Thinking 不代表上游持续推理，也不是无限等待。恢复受到时间、次数、可用线路和客户端取消约束；账号欠费、无权限等问题不一定能通过等待恢复。
响应已经输出一半，还能无缝换上游吗？
不能保证。可见输出一旦提交给客户端，Ferry 不会拼接另一条上游流来替换它。恢复和换路受提交边界与策略限制，不能把“自动接力”理解为所有中断都能续上。配置方式见长任务指南。
并发控制能避免封号吗？
它用于限制同时发出的请求并在容量不足时排队，有助于管理请求节奏，但不保证账号不被限流或封禁。应遵守上游的账号和使用规则。
三种协议可以完全互换吗？
Ferry 提供 Chat、Responses 和 Messages 入口。转换受目标协议与模型能力限制，不能无损表达的字段可能被拒绝或按已声明规则降级。上线前用自己的客户端验证流式输出、工具调用和多轮续接。详见协议行为。
会增加费用吗？统计等于上游账单吗？
恢复尝试、能力探测和自动消息可能产生额外调用。Ferry 的费用统计依据用量记录与定价配置，不替代供应商账单；缺少价格或用量证据不代表免费。
数据在哪里？换容器会丢失吗？
发行版 Compose 使用 ferry-data 卷，挂载到 /data，数据库位于 /data/state。重建容器会保留卷，删除卷会删除数据。数据库含配置、凭据与请求记录，默认备份仅含当前配置与恢复凭据；保留完整历史需显式添加 -backup-history。两者默认都没有静态加密；保存在受保护的本地存储上。不要用 docker compose down --volumes 做日常停止操作。
能否多副本共享数据库或提供多租户后台？
目前适合个人和小团队单实例使用，采用单管理员模式。每份本地 SQLite 数据只运行一个实例，不支持多个进程共享数据目录或多租户管理后台。
如何升级、备份和恢复？
固定镜像版本，升级前生成并校验备份，再按Docker 运维步骤操作。不要直接复制运行中的数据库。配置备份恢复后历史为空，显式完整备份才恢复备份时点的历史；之后的写入不会合并，回退镜像也不会撤销数据库迁移。
为什么改 YAML 或系统主题没有生效？
YAML 只在空库首次导入，初始化后通过控制台或管理 API 修改配置。主题若手动选成浅色或深色，会覆盖系统偏好；切回“跟随系统”。这些问题的具体排查见排障指南。
如何提问题、提 PR 或报告漏洞？
Bug 与功能建议使用 Issues。附版本、运行方式、脱敏复现及请求 ID；不要附数据库、令牌或真实对话。小修复、翻译和文档可以直接提 PR，步骤见贡献指南。疑似漏洞按安全说明私密报告。中文和英文均可。