企业官网建设流程全解析

• API网关
• LLM 网关
• 后端

CCX 是一个以 Go 后端为核心的单端口 AI API 代理与协议转换网关，面向 Claude、OpenAI、Gemini、DeepSeek、Kimi、GLM、MiniMax 等多类 LLM 上游，统一承载 Claude Messages、OpenAI Chat/Images、Codex Responses、Gemini 原生等多种协议。本文基于 docs/index.md 的项目定位与能力总览，结合 架构说明、快速开始、部署指南 与仓库源码，系统讲解 CCX 的多协议接入面、智能调度机制、Web 管理界面与一键部署方案，读完即可完成从安装、配置渠道到接入 Claude Code / Codex CLI 等客户端的完整落地。

CCX 是什么：多上游统一代理的核心定位

从项目首页的核心定位看，CCX 面向的核心场景非常明确：以统一入口代理多种 AI 上游，并对不同协议做转换。官方定义如下：

• 项目定位：AI API 代理网关，即「Claude / Codex / Gemini API Proxy」
• 上游支持：Claude、OpenAI、Gemini、DeepSeek、Kimi、GLM、MiniMax、通义千问等多上游
• 统一入口：前端构建产物通过 Go 的embed.FS嵌入后端二进制，单端口同时承载 Web UI、管理 API 与代理 API

在仓库中，这一「单二进制、单端口」设计有直接的源码证据：backend-go/main.go 中通过//go:embed all:frontend/dist将前端构建产物打包进后端进程，backend-go/internal/handlers/frontend.go 负责将其以静态资源方式提供服务。这意味着部署时只需运行一个二进制、监听一个端口，Web 管理界面与代理 API 天然同源。

四大核心特性

首页以四个特性概括 CCX 的能力：多协议支持、智能调度、Web 管理界面、一键部署。以下逐一展开并结合源码与文档深化。

1. 多协议支持：六类代理入口

CCX 内建六类渠道类型，每类渠道拥有独立的调度、指标与日志空间，对应不同的代理入口：

大多数代理入口还支持/:routePrefix/...变体，用于为渠道配置附加自定义前缀（详见 架构说明）。这意味着同一套网关既能服务 Claude Code（Messages 协议），也能服务 OpenAI 系 SDK（Chat / Responses 协议）与 Gemini 客户端，无需为每种协议单独部署服务。

从源码结构看，各协议 handler 在 backend-go/internal/handlers/ 下按协议分目录组织（messages/、chat/、responses/、gemini/、images/、vectors/），上游适配统一放在 backend-go/internal/providers/，协议结构转换集中在 backend-go/internal/converters/，可以推断其架构目标是「协议面」与「上游面」解耦，新增协议或新增上游时互不干扰。

2. 智能调度：优先级、促销期、健康检查与熔断恢复

CCX 的调度核心在 backend-go/internal/scheduler/，选路时会综合考量：

• 渠道配置状态（active/suspended/disabled）
• 促销期（Promotion）
• 优先级
• Trace 亲和性
• 熔断与可用 key 状态
• 模型过滤规则
• 上下文窗口与最大输出能力

实际选路顺序为：基础可用性过滤 → 模型过滤 → 路由前缀过滤 → 上下文能力过滤 → Vectors Embedding 兼容性过滤 → 手动排序 → Promotion 渠道 → Trace 亲和 → 普通 priority 顺序。其中：

• Trace 亲和会「让位」给更高优先级且健康的候选渠道，因此用户在驾驶舱中置顶 / reorder 渠道时，低优先级亲和流量会被迁移到置顶渠道；
• Promotion是临时强制优先机制，会在首次选择时绕过健康检查尝试促销渠道；
• 失败场景下执行故障转移，并结合熔断状态与定时恢复逻辑控制重试范围。

上下文路由

上下文路由用于解决同一渠道组内不同实际模型上下文窗口不一致的问题：调度前先估算当前请求需要的上下文与输出预算，结合下游 agent 请求模型的内置 profile 得到最小上下文窗口要求，再按渠道modelMapping后的实际模型能力做资格过滤。能力来源优先级为：下游 agentModelProfiles → 渠道modelCapabilities→ 全局upstreamModelCapabilities→ CCX 内置模型能力库 → 渠道defaultCapability→ unknown 策略。未知能力模型默认只允许承载不超过contextRouting.unknownSafeWindowTokens（默认 200000 tokens）的请求；渠道设置allowUnknownContext=true后可放行大上下文请求。完整配置示例见 架构说明 中的contextRouting段。

Vectors Embedding 兼容过滤

Vectors 渠道的/v1/embeddings在存在embeddingCapabilities元数据时启用严格兼容过滤：候选渠道先按客户端原始model命中supportedModels，再按modelMapping后的实际上游模型解析 Embedding 兼容元数据；fallback 只会在相同embeddingSpaceId（未配置时使用实际模型名）、有效维度和归一化语义的候选之间发生。被过滤掉的候选不会发送上游请求，也不会计入失败或熔断指标。完全没有 Embedding 元数据的旧配置则继续保持原有调度行为（详见 环境变量指南 的 Vectors 配置示例）。

渠道级主动限速

每个上游渠道还可配置主动限速字段（rateLimitRpm、rateLimitBurst、rateLimitMaxConcurrent、rateLimitAutoFromHeaders），在请求发往上游前主动限流，规避免费/低额度上游（如 MiMo）的 RPM 限制导致的 429；限速作用域是渠道级（同渠道所有 API Key 共享令牌桶），被限速拦截时会自动 failover 到其他可用渠道，调度器在选择渠道时会跳过处于 cooldown 的渠道。

3. Web 管理界面：可视化渠道编排与实时监控

CCX 的 Web 管理界面基于 Vue 3 + Vuetify 构建，源码位于 frontend/。首页将其能力概括为：

• 可视化渠道管理：添加、编辑、测试渠道，配置 Base URL、API Key、模型列表与优先级
• 拖拽排序：通过调整渠道顺序直接改变调度优先级
• 实时监控：查看请求量、成功率、失败率、延迟等渠道指标与全局/按模型统计历史数据
• 日志查看：每个渠道保留最近请求日志，记录status、statusCode、requestSource、interfaceType、baseUrl、keyMask等字段，Images 请求额外记录operation（generations/edits/variations）

启动后访问http://localhost:3000，使用ADMIN_ACCESS_KEY登录管理界面。管理界面同时承载三类可观测信息：渠道指标、渠道日志、运行时状态（熔断状态、黑名单 key 恢复、Promotion / Resume 等管理动作）。

4. 一键部署：前端嵌入二进制，单端口运行

首页强调「前端嵌入二进制，单端口部署，支持 Docker 与系统服务」，这在源码与部署文档中均有完整落点：

• 前端嵌入：backend-go/main.go 通过embed.FS内嵌前端产物，二进制自带 Web UI
• Docker：官方镜像可直接运行（见下文快速开始）
• 系统服务：提供 Linux systemd（部署指南）、macOS launchd（docs/service/com.ccx.gateway.plist）与 Windows NSSM（docs/service/windows-nssm.md）三种服务化方案

快速上手：从安装到首个请求

Docker 部署（推荐）

docker run -d \ --name ccx \ -p 3000:3000 \ -v ./.config:/app/.config \ -e PROXY_ACCESS_KEY=your-proxy-key \ crpi-i19l8zl0ugidq97v.cn-hangzhou.personal.cr.aliyuncs.com/bene/ccx:latest

二进制部署

export PROXY_ACCESS_KEY=your-proxy-key ./ccx

服务默认监听http://localhost:3000。

基本概念：渠道（Channel）

渠道是 CCX 的核心概念，每个渠道对应一个上游 API 的配置，包括：

• API Key：上游服务的认证密钥（支持多 Key 轮转）
• Base URL：上游 API 的地址
• 模型列表：该渠道支持的模型（白名单）
• 优先级：调度时的优先级权重，数字越小优先级越高

访问管理界面

启动后访问http://localhost:3000，使用ADMIN_ACCESS_KEY登录，即可添加和管理渠道、查看请求日志与流量统计、测试渠道连通性、调整渠道优先级。更完整的安装 → 配置密钥 → 启动服务 → Agent 配置 → 添加渠道 → 验证请求路径，可参考 CCX Desktop 用户教程 与 快速开始。

关键配置：环境变量与服务化

核心环境变量

完整变量列表与本地 HTTPS、mkcert 证书签发、监听地址（BIND_HOST）说明见 环境变量指南。关于访问控制有一条重要约束：只要配置了EXTRA_PROXY_ACCESS_KEYS，管理接口就不再回退到PROXY_ACCESS_KEY，必须显式设置独立的ADMIN_ACCESS_KEY且不能与任何代理密钥相同。

Linux systemd 服务示例

[Unit] Description=CCX AI API Gateway After=network.target [Service] Type=simple ExecStart=/opt/ccx/ccx WorkingDirectory=/opt/ccx Environment=PROXY_ACCESS_KEY=your-proxy-key # 额外代理访问密钥（可选，逗号分隔；启用后必须设置独立 ADMIN_ACCESS_KEY） #Environment=EXTRA_PROXY_ACCESS_KEYS=extra-proxy-key-1,extra-proxy-key-2 # 管理 API 独立密钥（可选，未设置时回退到 PROXY_ACCESS_KEY） #Environment=ADMIN_ACCESS_KEY=your-admin-secret-key Restart=always RestartSec=5 [Install] WantedBy=multi-user.target

此外，命令行版支持运行时路径覆盖：

ccx --config ~/.config/ccx/config.json --statedir ~/.local/state/ccx --logdir ~/.local/state/ccx/logs

其中--config指定配置文件、--statedir指定状态目录（metrics.db、conversation_state.json、scheduled_recovery_state.json写入该目录）、--logdir指定日志目录（none可禁用日志文件写入，适合 systemd/journald 环境）。

配置 LLM 提供商渠道

无论使用哪个提供商，添加渠道的基本步骤一致：登录管理界面 → 选择对应的代理入口（Chat、Messages 等）→ 点击「添加渠道」→ 填写渠道配置 → 保存并测试。

关键配置字段

服务类型选择指南

大多数国产 LLM 提供商同时兼容 OpenAI Chat 和 Anthropic Messages 协议，使用 Claude Code CLI 时可直接在 Messages 入口配置 Anthropic 兼容端点。各提供商的分步配置教程见 docs/providers/ 下的 DeepSeek、GLM、MiniMax、Kimi、OpenAI、MiMo、Claude、Gemini、Copilot 专项文档。

源码级纵深：请求流与模块职责

核心请求流

Client -> Auth Middleware -> Route Handler -> Channel Scheduler -> Provider / Converter -> Upstream API -> Metrics / Channel Logs -> Client Response

分阶段说明：

1. 中间件完成认证、CORS、压缩与请求日志处理（backend-go/internal/middleware/）
2. 各协议 handler 解析请求并选择对应渠道类型
3. 调度器根据渠道状态、优先级、促销期、Trace 亲和性和熔断状态选择上游
4. Provider 负责将请求转换成上游协议并处理流式/非流式响应
5. 指标和渠道日志记录请求生命周期，再返回统一响应

核心模块职责

Model Registry 数据分发

模型能力、定价与 benchmark 的唯一权威源是 shared/model-registry/ccx_model_registry.json。生成流程将其同步为公开文档站 preset（docs/public/presets/）和后端内嵌 preset shard（backend-go/internal/presetstore/embedded.go），运行时不再生成或依赖 Go/TypeScript 数据镜像；upstreamCapabilities与benchmarkProfiles随同一个PresetBundle原子发布，前端统一通过/api/presets获取当前生效版本。

延伸阅读

• 系统边界、核心模块与请求流： 架构说明
• 安装、渠道概念与六类代理入口： 快速开始
• 完整环境变量与本地 HTTPS： 环境变量指南
• Docker Compose / systemd / launchd 部署： 部署指南
• 各 LLM 提供商渠道配置： 配置教程
• Claude Code、Codex CLI / App、OpenCode 接入： 客户端接入指南
• 性能基准与压测结果： Benchmark 指南
• 桌面端安装与使用： CCX Desktop 教程

• API网关
• LLM 网关
• 后端