API网关LLM 网关后端【免费下载链接】ccxClaude / Codex / Gemini API Proxy - CCX项目地址https://gitcode.com/gh_mirrors/cc/ccx点击查看免费下载本文基于 CCX 仓库 docs/en/guide/architecture.md 官方架构文档系统梳理 CCX 作为 Claude / Codex / Gemini AI API 代理与协议转换网关的整体设计单端口部署形态、六类渠道与路由面、核心请求流、调度与高可用机制含上下文路由以及可观测性与构建版本体系。读完本文你将掌握 CCX 的模块划分与调用链能够定位各模块源码入口并理解多渠道调度 上下文能力过滤 故障转移这套核心路由逻辑如何在 backend-go/main.go 中被装配起来。系统概览单端口、单二进制的统一网关CCX 的核心设计主张是单端口部署一个进程、一个监听地址同时承载 Web 管理界面、管理 API 与全部代理 API。根据 backend-go/main.go 的路由注册代码这个统一入口由以下几部分组成Go 后端负责路由、认证、调度、协议转换、日志与指标核心代码位于backend-go/Vue 3 Vuetify 前端提供 Web 管理界面代码位于 frontend/前端构建产物通过 Go 标准库embed.FS嵌入后端二进制见 backend-go/main.go 中//go:embed all:frontend/dist声明因此部署时只需分发单个可执行文件统一入口同时承载 Web UI静态资源、管理 API/api/*与代理 API/v1/*、/v1beta/*。从 backend-go/main.go 可以看到服务器装配的完整骨架Gin 引擎依次挂载FilteredLogger、gin.Recovery、CORS、Gzip、WebAuth 中间件再注册健康检查GET /health与GET /:routePrefix/health、配置保存POST /admin/config/save、管理 API 组/api与各协议代理端点。启动时还会按需初始化限速管理器、会话管理器、指标持久化存储、多渠道调度器、渠道保活验证healthcheck以及 Autopilot 健康中心等子系统并在收到 SIGINT/SIGTERM 时按依赖顺序优雅关闭先停预置更新器、保活验证、discovery runner再关指标存储、调度器与限速器。启动后控制台会打印协议、监听地址、管理界面地址、各代理端点路径、配置文件路径与脱敏后的密钥信息生产模式下若未设置有效的PROXY_ACCESS_KEY仍为默认占位值会直接拒绝启动。仓库结构官方文档给出了顶层目录结构结合仓库实际内容整理如下ccx/ ├── backend-go/ # Go 后端 │ ├── main.go # 路由与服务启动单端口统一入口 │ └── internal/ │ ├── config/ # 配置加载、校验与热重载.config/config.json │ ├── handlers/ # HTTP 处理器代理 管理 各协议子包 │ ├── providers/ # 上游适配Claude / OpenAI / Gemini 等 │ ├── converters/ # Responses 与其他协议的转换器 │ ├── scheduler/ # 多渠道调度核心 │ ├── session/ # 会话与 Trace 亲和性 │ ├── metrics/ # 指标、日志、熔断、持久化 │ ├── middleware/ # 认证、CORS、压缩、日志 │ └── ... # autopilot / ratelimit / healthcheck 等扩展子系统 ├── frontend/ # Vue 3 Vuetify 管理界面 └── .config/ # 运行时配置与持久化数据config.json、metrics.db 等值得说明的是backend-go/main.go 中resolveRuntimePaths展示了.config目录的完整职责除默认配置文件config.json外还包含metrics.db指标持久化、thinking_cache.dbClaude thinking 缓存、conversation_state.json对话状态、scheduled_recovery_state.json定时恢复检查点、autopilot.db健康中心画像库以及presets/远程预置缓存。所有这些路径都可通过命令行参数--config、--statedir、--logdir、--backupdir重定向其中--logdir none可禁用日志文件写入适合 systemd/journald 环境。渠道类型与路由面CCX 内建六类渠道每类渠道拥有独立的调度、指标和日志空间。官方文档的对照表如下渠道类型代理入口管理入口说明Messages/v1/messages/api/messages/channels/*Claude Messages 语义Chat/v1/chat/completions/api/chat/channels/*OpenAI Chat CompletionsResponses/v1/responses、/v1/responses/compact/api/responses/channels/*Codex/OpenAI ResponsesGemini/v1beta/models/*/api/gemini/channels/*Gemini 原生协议Images/v1/images/generations、/v1/images/edits、/v1/images/variations/api/images/channels/*OpenAI ImagesVectors/v1/embeddings/api/vectors/channels/*OpenAI Embeddings大多数代理入口都支持/:routePrefix/...变体用于为渠道配置附加自定义前缀——这在 backend-go/main.go 的代理端点注册中逐一体现POST /v1/messages与POST /:routePrefix/v1/messages成对注册/v1/responses、/v1/responses/compact、/v1/chat/completions、/v1beta/models/*modelAction、/v1/images/*、/v1/embeddings均同理。此外还有两个值得注意的额外代理面GET /v1/responsesResponses 协议的 WebSocket 端点支持 Codex 原生response.createover WebSocketPOST /v1/alpha/*restCodex 记忆层数据面history/notes 透传粘 Responses 渠道池。管理面方面/api组下每类渠道都有完整的管理 API 集渠道 CRUDGET/POST /{type}/channels、PUT/DELETE /{type}/channels/:id、Key 增删与排序/keys/:apiKey/top|bottom、黑名单恢复与 Key 挂起/恢复restore、suspend、resume、渠道排序reorder、状态切换PATCH .../status、促销期promotion、指标与历史metrics、metrics/history、渠道日志logs、pingping、ping/:id、能力测试capability-test与兼容性诊断compat-diagnose等。调度器层面还有GET /{type}/channels/scheduler/stats与POST /{type}/channels/scheduler/diagnose用于观测与诊断选路结果。核心请求流官方文档给出了端到端请求流Client - Auth Middleware - Route Handler - Channel Scheduler - Provider / Converter - Upstream API - Metrics / Channel Logs - Client Response分阶段说明中间件完成认证、CORS、压缩和请求日志处理。backend-go/internal/middleware 目录下对应auth.go、cors.go、gzip.go、logger.go四个实现文件。各协议 handler解析请求并选择对应渠道类型。internal/handlers/下按协议拆分为messages/、chat/、responses/、gemini/、images/、vectors/、alpha/、channels/、logicalchannels/等子包与六类渠道一一对应。调度器根据渠道状态、优先级、促销期、Trace 亲和性和熔断状态选择上游。核心实现在 backend-go/internal/scheduler/channel_scheduler.go其中ChannelKind定义了六类渠道常量messages / responses / gemini / chat / images / vectors。Provider负责将请求转换成上游协议并处理流式/非流式响应。指标和渠道日志记录请求生命周期再返回统一响应。从 backend-go/main.go 的初始化顺序可以还原调度器的装配细节channelScheduler : scheduler.NewChannelScheduler(...)一次性注入配置管理器、六个 MetricsManager、Trace 亲和管理器与 URL 管理器随后再通过SetRateLimitManager、SetCandidateFilterProviderAutopilot SmartRouter 过滤、SetQuotaManager、SetModelSupportResolverProvider、SetContextWindowResolverProvider、SetOverflowCandidateProvider、SetConversationComponents等方法逐步挂载扩展能力。可以看到调度器是一个高度可组合的核心枢纽上下文路由、模型支持解析、溢出重定向都通过注入回调的方式参与选路。核心模块职责internal/config/维护.config/config.json支持热重载与配置备份。在 backend-go/main.go 中cfgManager.RegisterOnConfigChange(...)被大量使用配置变更时会同步刷新 credential-masker 的渠道 key 前缀、thinking 缓存 TTL、调度器调优参数、熔断器参数、限速配置、配额同步等体现配置热重载驱动运行态更新的设计提供各渠道配置读写能力。ContextRoutingConfig见 backend-go/internal/config/config.go等结构体定义了运行时路由相关配置的 JSON 形态。internal/handlers/承载 Messages、Chat、Responses、Gemini、Images、Vectors 代理与管理接口处理模型查询、能力测试、日志查询、状态切换等管理请求。六类渠道各自的管理路由都在 backend-go/main.go 的/api组中成组注册结构高度对称。internal/providers/封装上游 API 的请求构造与响应处理屏蔽 Claude、OpenAI、Gemini、Responses 等上游差异。internal/converters/主要服务于 Responses 场景负责 Responses 与其他协议之间的结构转换目录下包含responses_converter.go、claude_to_responses.go、gemini_to_responses.go、responses_to_chat.go、responses_to_gemini.go等实现以及配套的 think 标签、reasoning 归一化、工具转换等能力。internal/scheduler/多渠道选路核心管理优先级、促销期、Trace 亲和性、故障转移与恢复。backend-go/internal/scheduler/ 下除channel_scheduler.go外还有select.go选路实现、recovery.go定时恢复、selection_trace.go选路追踪等文件。internal/session/为 Responses API 提供previous_response_id驱动的会话跟踪。在 backend-go/main.go 中会话管理器以24 小时过期、最多 100 条消息、最多 100k tokens的参数初始化并注入 Responses handler维护 Trace 亲和性所需的会话级信息TraceAffinityManager。internal/metrics/记录渠道指标、历史统计和请求日志支持独立的熔断状态、持久化和自动恢复调度。六个MetricsManager各自独立创建每个可绑定同一 SQLite 持久化存储metrics.db并按渠道类型messages/responses/gemini/chat/images/vectors打标熔断器参数窗口、失败阈值、连续失败阈值、流式超时等由配置热重载统一更新。调度与高可用每类渠道有自己的MetricsManager与日志存储避免不同协议互相污染健康状态——这是隔离思想的直接体现Messages 渠道的故障不会让 Responses 渠道被误判为不健康。调度时会综合考虑渠道配置状态active/suspended/disabled促销期Promotion优先级PriorityTrace 亲和性熔断与可用 key 状态模型过滤规则上下文窗口与最大输出能力实际选路顺序为基础可用性过滤 模型过滤 路由前缀过滤 上下文能力过滤 手动排序 Promotion 渠道 Trace 亲和 普通 priority 顺序。官方文档特别强调了两个反直觉但重要的行为Trace 亲和会让位给更高优先级且健康的候选渠道因此普通置顶 / reorder 会把低优先级亲和流量迁移到置顶渠道Promotion 是临时强制优先会在首次选择时绕过健康检查尝试促销渠道。失败场景下会执行故障转移并结合熔断状态和定时恢复逻辑控制重试范围。backend-go/main.go 中实现了一套 UTC 定时恢复调度启动时先补跑到期恢复RunDueRecoveries并检测错过的 UTC 恢复槽位MissedScheduledRecoveryTimeUTC错过则立即补跑之后按NextScheduledRecoveryTimeUTC定时执行RunScheduledRecoveries同时以 1 分钟 ticker 作为兜底检查恢复进度通过scheduled_recovery_state.json持久化。恢复对象包括拉黑 Key、Key, 模型组合以及被整体停用的渠道。上下文路由上下文路由用于解决同一渠道组内不同实际模型上下文窗口不一致的问题。CCX 在调度前估算当前请求需要的上下文与输出预算并结合下游 agent 请求模型的内置 profile 得到最小上下文窗口要求再按渠道ModelMapping后的实际模型能力做资格过滤。该步骤只过滤不可用渠道不改变用户在驾驶舱中设置的渠道顺序。能力来源优先级下游 agentModelProfiles CCX 内置 agent 模型 profile 渠道 modelCapabilities 全局 upstreamModelCapabilities CCX 内置模型能力库 渠道 defaultCapability unknown 策略关键行为modelCapabilities的 key 匹配ModelMapping后的实际模型名支持与supportedModels相同的通配符形式如vendor-1m-*下游 agent profile 只提供最小窗口要求如果本次请求估算更大则以本次请求需求为准未知能力模型默认只允许承载不超过contextRouting.unknownSafeWindowTokens的请求默认200000 tokens渠道设置allowUnknownContexttrue后未知能力模型也可承载大上下文请求显式输出上限超过实际模型maxOutputTokens时会过滤该渠道X-Channel指定渠道仍必须满足上下文与输出能力不会静默切换到其他渠道Trace 亲和性按上下文桶隔离避免 1M 请求选中的渠道污染小上下文请求Responsescompaction_trigger会跳过原始请求窗口校验但仍校验显式输出上限以保证本地 compact 流程有机会执行。上下文路由的配置结构在 backend-go/internal/config/config.go 中有直接对应ContextRoutingConfig包含Enabled布尔开关、DefaultOutputReserveTokens默认输出保留预算与UnknownSafeWindowTokens未知能力模型安全窗口三个字段均为可选字段omitempty。官方文档给出的配置示例{ contextRouting: { enabled: true, defaultOutputReserveTokens: 8192, unknownSafeWindowTokens: 200000 }, upstreamModelCapabilities: { vendor-1m-*: { contextWindowTokens: 1000000, maxOutputTokens: 128000 } }, upstream: [ { name: claude-1m, modelMapping: { sonnet: claude-sonnet-4-6 }, modelCapabilities: { claude-sonnet-4-6: { contextWindowTokens: 1000000, maxOutputTokens: 64000 } }, defaultCapability: { contextWindowTokens: 200000, maxOutputTokens: 64000 } } ] }字段语义补充说明defaultOutputReserveTokens调度估算时为输出预留的 token 预算示例 8192用于把输入窗口需求 输出预算合计后与模型上下文窗口比较unknownSafeWindowTokens对能力未知模型的保守窗口上限默认 200000upstreamModelCapabilities全局模型能力声明key 支持通配符vendor-1m-*优先于内置能力库upstream.modelCapabilities渠道级能力声明key 必须是modelMapping之后的实际模型名优先级高于全局声明upstream.defaultCapability渠道兜底能力声明在无任何能力来源命中时使用。在运行时backend-go/main.go 通过SetContextWindowResolverProvider把上下文窗口解析接入调度器不再只信注册表声明而是合成学习证据成功实证放宽棘轮 / models API 声明 / 实测 400 收紧渠道渐进扩容200K→272K→372K→1M由此自动跟进。这是上下文路由在运行期的深化静态配置之外还叠加了渠道兼容缓存config.SharedChannelCompatCache的实测学习结果。可观测性CCX 提供三类核心可观测信息渠道指标请求量、成功率、失败率、延迟全局统计与按模型统计历史数据/api/{type}/channels/metrics/history、/api/{type}/global/stats/history、/api/{type}/models/stats/history渠道日志每个渠道保留最近请求日志GET /api/{type}/channels/:id/logs记录status、statusCode、requestSource、interfaceType、baseUrl、keyMask等字段Images 请求额外记录operation运行时状态熔断状态GET /settings/circuit-breaker、PUT /settings/circuit-breaker可运行时查看与修改黑名单 key 恢复/api/{type}/channels/:id/keys/restore、restore-model等管理端点Promotion / Resume 等管理动作promotion、resume端点从 backend-go/main.go 可以看到指标系统默认使用内存模式当环境配置启用指标持久化MetricsPersistenceEnabled时六个 MetricsManager 会共享同一个 SQLite 存储metrics.db并支持RetentionDays保留期配置。值得注意的是渠道保活验证healthcheck依赖指标持久化持久化不可用时保活验证不会启动相关管理端点返回 503。健康检查失败会同时触发两件事——按渠道类型喂对应 MetricsManager 的熔断RecordFailure并写入渠道日志requestSourcehealthcheck鉴权失败则通过BlacklistKeyWithRecoverAt拉黑 Key 并登记自动恢复时间。Images 日志operationImages 请求会在渠道日志中记录具体端点类型generationseditsvariations该字段仅对 Images 渠道有语义其余协议为空。构建与版本根目录 VERSION 是唯一版本源backend-go/Makefile 在构建时读取../VERSIONVERSION?$(shell cat ../VERSION 2/dev/null || echo v0.0.0-dev)并支持环境变量覆盖版本、构建时间和 Git 提交通过-ldflags注入 backend-go/version.goLDFLAGS-X main.Version$(VERSION) -X main.BuildTime$(BUILD_TIME) -X main.GitCommit$(GIT_COMMIT)前端构建产物嵌入到backend-go/frontend/distmake copy-frontend将../frontend/dist复制进来随后//go:embed all:frontend/dist编译进二进制。构建命令要点来自 backend-go/Makefilemake buildCGO_ENABLED0 go build -ldflags$(LDFLAGS) -s -w -o ../dist/ccx-go .产出静态可执行文件make dev自动安装并使用 Air 实现热重载开发make test/make test-cover运行测试与覆盖率报告前端需先构建cd frontend bun run build见 Makefile 中copy-frontend的提示。ccx version或ccx --version可打印版本、构建时间与 Git 提交unknown占位表示未通过 ldflags 注入。扩展点添加新上游能力在 backend-go/internal/providers 中扩展或新增上游适配实现必要时在 backend-go/internal/converters 中补充协议转换尤其 Responses 场景为对应渠道类型补齐 handlerbackend-go/internal/handlers 下新增或扩展协议子包、管理接口和前端配置入口将指标、日志和模型过滤纳入统一链路——参考 backend-go/main.go 中六类渠道的对称装配模式独立的 MetricsManager、独立的 ChannelLogStore、独立的/api/{type}/channels路由组以及NewChannelScheduler中的注入点。调整调度策略修改 backend-go/internal/scheduler核心选路在channel_scheduler.go与select.go如涉及健康状态或恢复机制同时检查 backend-go/internal/metrics熔断状态、黑名单恢复、定时恢复逻辑。扩展管理界面修改 frontend/src/components 与 frontend/src/services/api.ts如新增图标或 Vuetify 组件需同步更新前端插件注册。相关文档入口说明README.md后端专项backend-go/README.md仓库中该文件位于 backend-go/README.md开发流程docs/en/guide/development.md环境变量docs/en/guide/environment.md发布流程docs/en/guide/release.md注官方架构文档中相关文档一节所列development.md、environment.md、release.md在仓库中的实际位置为 docs/en/guide/ 目录下的英文指南中文版对应 docs/guide/development.md、docs/guide/environment.md、docs/guide/release.md。赞分享API网关LLM 网关后端【免费下载链接】ccxClaude / Codex / Gemini API Proxy - CCX项目地址https://gitcode.com/gh_mirrors/cc/ccx点击查看免费下载相关推荐Nix 包管理器 nix copy 全解析跨 Store 复制闭包与二进制缓存分发实战Nix 包管理器 nix copy 全解析跨 Store 复制闭包与二进制缓存分发实战 nix copy 是 Nix 纯函数式包管理器中用于在两个 Nix sAPI网关LLM 网关后端CCX 隐私架构解析自托管 AI API 代理网关的数据边界与本地化存储设计CCX 隐私架构解析自托管 AI API 代理网关的数据边界与本地化存储设计 本文基于 docs/en/guide/privacy.md https://liAPI网关LLM 网关后端OmniRoute 架构深度解析本地 AI 路由网关的统一 /v1 端点、多 Provider 调度与韧性设计OmniRoute 架构深度解析本地 AI 路由网关的统一 /v1 端点、多 Provider 调度与韧性设计 本文以 docs/i18n/de/docs/a后端API网关LLM 网关人工智能大模型MCP 服务桌面应用上一篇ComfyUI 节点工作流怎么用从0到跑通第一个图生视频的5个步骤下一篇Digital 教程画出你的第一块数字逻辑电路并仿真它创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考