30秒速读：手里多家大模型 Key，客户端换一个就得改一处配置。本篇讲清这款自托管网关的安装方式怎么选、安装步骤里的关键卡点、装完先改的设置，以及它适合谁。
本文介绍 Cartethyia——一个自托管的多提供商 AI 网关：它把 OpenAI、Anthropic 等多种客户端协议统一收敛到一个本地入口，按模型、账户健康度、配额与冷却状态自动选路上游，上游出问题时自动故障转移，还自带控制台看流量、看用量、看账户健康。读完这篇，你会知道它适不适合你、该装哪个版本、装完先改哪几个设置。
软件信息表
| 项目 | 内容 |
|---|---|
| 软件名 | Cartethyia |
| 版本 | 2.5.3（npm 包，据项目说明滚动更新） |
| 运行平台 | 多平台（Linux / macOS / Windows，需 Bun 1.4.0 以上） |
| 技术栈 | Bun + TypeScript + Elysia |
| 许可证 | GNU GPL v3.0（仅此版本） |
| 数据存储 | Lite 模式内置 SQLite；Full 模式用 PostgreSQL，可选 Redis 协同 |
| 核验日期 | 2026-10-22（按当日项目 README 核验） |
版本选择：npm 全局安装 vs Docker vs 源码
| 方式 | 一句话说明 | 适合谁 |
|---|---|---|
| npm 全局安装 | npm install -g cartethyia，装完跑 cartethyia setup 走初始化向导 |
个人本机，最快上手 |
| Docker Compose | 默认 Full 模式，数据库配好即跑 | VPS、多人共用 |
| 源码（Bun） | 拉仓库自己构建 | 要改代码、二次开发 |
结论先行：个人先用 npm 全局安装，一条命令加向导，十分钟就能跑起来；要给团队用、或者 SQLite 成为瓶颈时，再切 Docker 的 Full 模式，配置可以导出 JSON 迁移，不用重配。
安装步骤（只讲关键卡点）
- 先装 Bun 1.4.0 或更新版本。卡点：版本太旧装完跑不起来，装前先
bun --version确认。 - 全局安装：
npm install -g cartethyia。卡点：-g不能漏；局部安装会把命令丢进node_modules/.bin，不在 PATH 里，敲cartethyia会提示找不到。 - 跑
cartethyia setup按向导选 Lite 还是 Full。卡点：单人本机选 Lite；Docker Compose 默认 Full，别两头混着配。 - 在控制台录入上游提供商账户、签发 API Key，然后把客户端（OpenCode、Claude Code、Cline、Codex 等）的请求地址指到网关。
- 调
/v1/models看一眼这把 Key 能调哪些模型，通了再切正式流量。
装完先改的 4 个设置
- 路由与故障转移策略（控制台 → 路由配置）。把”健康度优先、配额耗尽自动冷却切换”打开。体感差别：上游 429 或 5xx 时请求自动换路走，不用再半夜手动换 Key。
- 配额与冷却（控制台 → 账户/配额）。给免费额度的上游设日上限。体感差别：某个脚本跑飞也不会一夜刷爆免费额度。
- 请求捕获（设置 → Payload capture）。打开脱敏捕获。体感差别：协议转换前后、上下游各自看到什么一目了然，排障从”猜”变成”看”。
- 数据备份（设置 → Backup）。Lite 模式就是 SQLite 单文件，定期导出 JSON 备份。体感差别：换机器或切 Full 模式时直接导入恢复，不用重配一遍。
注意事项与常见问题
- 仓库地址认准镜像。原仓库曾因异常点星行为被 GitHub 限制公开可见，项目方已声明这不是代码、安全或许可问题，项目本身不受影响；当前可用镜像为 risunCodex/Cartethyia，Release 与 npm 包都从镜像走，控制台里的版本检查也默认链镜像。
- Embeddings 与音频两路是”只转发不翻译”。网关只做路由、准入和计费，不做协议转换，也没有内置适配器；对接时上游必须本身就兼容对应接口，模型行配好对应的服务类型即可。
- 许可证是 GPL-3.0-only。自己用、改着用都没问题；但如果你要发布修改版或把它集成进对外分发的产品，必须同样开源。
- 视频生成看上游脸色。目前只有 CodeBuddy、WorkBuddy 等少数上游声明支持，走异步任务轮询而不是直接返回成片；配路由前先确认上游能力，别指望网关变出视频来。
适合谁、不适合谁
一句话判断：适合同时用 OpenAI 系和 Anthropic 系客户端、手里有多家 Key 想统一管起来的个人开发者和小团队；不适合只想稳定转发单一上游的场景——跟纯反向代理比，Cartethyia 是”带路由大脑”的网关，代价是 GPL 的传染性和 Bun 生态的学习成本，需求简单时选更轻的反代更划算。
附：13 个路由端点速查
这是据 README 整理的独家对照表，配客户端时直接查：
| 端点 | 用途 |
|---|---|
/v1/chat/completions |
OpenAI 风格对话 |
/v1/responses |
Responses API，含 Codex 工具 |
/v1/messages |
Anthropic Messages，含 Claude Code |
/v1/models |
查这把 Key 能调哪些模型 |
/v1/completions |
老式文本补全 |
/v1/responses/compact |
Responses 压缩 |
/v1/search |
联网搜索 |
/v1/systemone |
System One |
/v1/images/generations |
文生图 |
/v1/videos/generations |
视频生成（看上游能力） |
/v1/embeddings |
向量（透传） |
/v1/audio/transcriptions |
语音转文字（透传） |
/v1/audio/speech |
文字转语音（透传） |
明确取舍：要”统一协议 + 智能路由 + 可观测”三件套就选它；只要转发，就别为它付 GPL 和 Bun 的学习成本。
版本对比与推荐
结论先行：推荐 2.5.3 版，先用 npm 全局安装。一条命令加向导就能跑起来；要给团队用、或 SQLite 成为瓶颈时，再切 Docker 的 Full 模式。
| 版本形态 | 版本 | 适合谁 | 推荐 |
|---|---|---|---|
| npm 全局安装 | 2.5.3（滚动更新，以官网为准） | 个人本机，最快上手 | 稳定推荐，先用这个 |
| Docker Compose（Full） | 2.5.3（滚动更新，以官网为准） | VPS、多人共用 | SQLite 成瓶颈时切 |
| 源码（Bun） | 以官网为准 | 改代码、二次开发 | 仅开发时选 |
以上安装步骤先装 Bun 1.4.0 或更新版本，版本太旧装完跑不起来。
补充设置与常见问题
补充设置：控制台访问先做限制（通用建议）
入口：网关控制台的访问入口。做法：控制台不要公网裸奔，先限制到内网或可信来源再放行。体感差别：路由、配额、Key 都集中在这里，入口收紧后半夜少很多提心吊胆。
补充设置：配额告警阈值先设好（通用建议）
入口：控制台 → 账户/配额。做法：给免费额度的上游设日上限之外，再设一个告警阈值，额度快用完时先收到提醒。体感差别：从突然被冷却切换变成提前知道、从容调整。
常见问题补充
- 某个模型突然调不通先查什么？先调 /v1/models 看这把 Key 能调哪些模型，再看账户健康度与冷却状态；上游 429 或 5xx 时路由会自动换路。
- Lite 切 Full 要重配吗？不用，配置可以导出 JSON 迁移，换模式后直接导入恢复。
- Embeddings 调不通是网关的问题吗？先确认上游本身兼容对应接口：网关对 Embeddings 与音频两路只转发不翻译，不做协议转换。
注意事项补充
- 许可证是 GPL-3.0-only：自己用、改着用没问题，对外分发修改版或集成进对外产品时必须同样开源。
- 视频生成看上游能力：目前只有少数上游声明支持，走异步任务轮询，配路由前先确认上游能力。
- 生产 Key 与测试 Key 分开保管，泄露时先吊销再换（通用建议），不要只改客户端配置。
开源地址
GitHub 国内访问较慢，如打不开可多刷新几次
关注「软件教程管家」
回复软件名即取即下：网盘下载链接 + 提取码，一步直达，不用再跳转。
本站资源仅供个人学习交流，请勿用于商业用途。软件与资料版权归原作者所有；如有侵权，请通过公众号「软件教程管家」联系我们，我们将在 24 小时内下架处理。查看免责声明 ›
