企业官网建设流程全解析

• 后端
• 云原生
• 模型推理服务
• MLOps
• 人工智能

导读

本文基于 Cortex 开源仓库的 docs/start.md 入门指南，系统讲解从零开始的完整上手路径：先在你的 AWS 账户上用cortex cluster up拉起一个生产级 Kubernetes 集群，再通过cortex deploy把容器化的机器学习服务以 Realtime、Async、Batch、Task 四种 API 形态发布出去。读完本文，你将掌握 Cortex CLI 的安装与配置、cluster.yaml的关键参数、环境（Environment）管理机制，以及四类 API 的定义、构建、部署与调用全流程，并能够顺着文末的仓库路径深入阅读源码验证每个环节的实现细节。

一、两条核心路径：集群编排 + API 部署

docs/start.md把整个上手流程浓缩为两个阶段、两条命令：

# 阶段一：在你的 AWS 账户上创建集群 cortex cluster up cluster.yaml # 阶段二：部署可扩展的 API cortex deploy apis.yaml

第一阶段的本质是：Cortex 在 AWS 上以 CloudFormation/EKS 为底座，创建一套包含 Operator、Autoscaler、Proxy、Async Gateway、Prometheus/Grafana 等组件的生产基础设施；第二阶段的本质是：Cortex 把你在 YAML 中声明的 API 规格转化为 Kubernetes 上的工作负载，并接入负载均衡、弹性伸缩、监控与日志链路。整个 CLI 由 cli/main.go 入口启动，命令树定义在 cli/cmd 目录下。

二、第一步：安装并配置 Cortex CLI

2.1 使用安装脚本安装 CLI

docs/start.md推荐通过一行脚本完成安装（脚本本身即仓库根目录的 get-cli.sh）：

bash -c "$(curl -sS <get-cli.sh 的托管地址>/v0.42.1/get-cli.sh)"

从 get-cli.sh 的源码可以看出该脚本的实际行为（以下细节均出自该文件）：

• 平台支持：仅支持 macOS 与 Linux，其他操作系统会直接报错退出（见case "$OSTYPE"分支）；
• 下载方式：优先使用curl，其次使用wget，两者都没有时提示安装其一；
• 默认安装位置：/usr/local/bin/cortex，可通过环境变量CORTEX_INSTALL_PATH覆盖（脚本支持~/前缀展开）；
• 权限处理：当前用户是 root 时直接移动二进制，否则请求sudo密码后移动；
• 交互式增强：如果当前终端是交互式（-t 1），脚本会询问是否将source <(cortex completion bash)或source <(cortex completion zsh)写入 shell 配置文件，用于启用命令补全与cx别名。

因此，更可控的安装方式是先在本地拿到脚本、检查后再执行，也可以直接设置CORTEX_INSTALL_PATH指定安装目录。详细说明见 客户端安装文档。

2.2 通过 pip 安装 CLI 与 Python 客户端

除了独立二进制，Cortex 还提供 Python 客户端（源码位于 python/client/cortex），可以一并安装：

# 安装最新版本 pip install cortex # 安装/升级到指定版本（例如 0.42.1） pip install cortex==0.42.1 # 升级到最新版本 pip install --upgrade cortex

2.3 客户端配置目录

CLI 与 Python 客户端默认在~/.cortex/目录下保存环境配置。若想改用其他目录，在任何cortex命令执行前导出：

export CORTEX_CLI_CONFIG_DIR=/path/to/your/cortex-config

配置目录的读写逻辑可参考 cli/cmd/lib_cli_config.go 与 cli/types/cliconfig/cli_config.go。

三、第二步：创建集群

3.1 前置条件

创建集群前需要准备（详见 集群创建文档）：

1. 本机安装并运行 Docker（cortex cluster up在 cli/cmd/cluster.go 中会先调用docker.GetDockerClient()校验 Docker 可用性，否则直接报错退出）；
2. 若计划使用 GPU 节点组，需先在 AWS Marketplace 订阅 GPU 版 AMI；
3. 创建具有AdministratorAccess的 IAM 用户，并配置好本机的 AWS 凭证（CLI 通过 pkg/lib/aws/credentials.go 解析凭证）；
4. 视所选实例类型，可能需要向 AWS 申请提高 EC2 配额。

3.2 拉起集群

cortex cluster up cluster.yaml

从 cli/cmd/cluster.go 的_clusterUpCmd实现看，这条命令背后的关键流程包括：

1. 校验 Docker 客户端；
2. 解析cluster.yaml得到访问配置（集群名、region），并检查同名环境是否已存在（若存在会提示是否覆盖，也可用--configure-env指定新环境名）；
3. 通过 AWS 客户端检查集群状态（clusterstate.GetClusterStacks），确保目标集群尚不存在；
4. 校验当前 AWS 身份是否具备管理员权限；
5. 创建 S3 bucket（用于配置与工件存储）、CloudWatch 日志组、默认 IAM 策略；
6. 以 Docker 容器方式运行管理镜像执行/root/install.sh（即 manager/install.sh），完成 EKS 集群与全部组件的部署；
7. 等待 Operator 的 NLB 就绪后，自动把环境（Environment）写入 CLI 配置，并设为默认环境。

cortex cluster up支持--configure-env <名称>（缩写-e）与--yes（跳过确认提示）等参数。创建过程中如果实例供应失败，CLI 会结合 EC2 AutoScaling Group 的活动历史给出排障提示，并要求先cortex cluster down清理再重试。

3.3 cluster.yaml：核心配置解析

docs/start.md指向的 集群配置文档 给出了完整的cluster.yaml示例，以下配置项按用途分组说明：

# ===== 集群基本信息 ===== cluster_name: cortex # 集群名称，会作为 AWS 资源命名的组成部分 region: us-east-1 # AWS 区域 availability_zones: # 默认为该区域随机 3 个可用区，如 [us-east-1a, us-east-1b, us-east-1c] # ===== 节点组（Node Group）配置 ===== node_groups: - name: ng-cpu # 节点组名称 instance_type: m5.large # 实例类型 min_instances: 1 # 最小实例数 max_instances: 5 # 最大实例数 priority: 1 # 节点组优先级 [1-100]，值越高优先级越高 instance_volume_size: 50 # 每实例磁盘容量（GB） instance_volume_type: gp3 # 卷类型 [gp2 | gp3 | io1 | st1 | sc1] # instance_volume_iops: 3000 # IOPS（仅 io1/gp3 适用） # instance_volume_throughput: 125 # 吞吐（仅 gp3 适用） spot: false # 是否使用 Spot 实例 - name: ng-gpu # GPU 节点组示例 instance_type: g4dn.xlarge min_instances: 1 max_instances: 5 instance_volume_size: 50 instance_volume_type: gp3 spot: false # ... # ===== 网络与安全 ===== subnet_visibility: public # 实例子网可见性 [public | private] nat_gateway: none # NAT 网关 [none | single | highly_available]（使用 private 子网时必选） api_load_balancer_type: nlb # API 负载均衡类型 [nlb | elb] api_load_balancer_scheme: internet-facing # API 负载均衡方案 [internet-facing | internal] operator_load_balancer_scheme: internet-facing # Operator 负载均衡方案（internal 时需要 VPC Peering 才能连接） api_load_balancer_cidr_white_list: [0.0.0.0/0] # API 访问 CIDR 白名单 operator_load_balancer_cidr_white_list: [0.0.0.0/0] # Operator 访问 CIDR 白名单 vpc_cidr: 192.168.0.0/16 # 集群 VPC 的主 CIDR 段 # ===== 安全与权限 ===== ssl_certificate_arn: # 自定义域名场景下所需的 SSL 证书 ARN iam_policy_arns: ["arn:aws:iam::aws:policy/AmazonS3FullAccess"] # 附加给 API 的 IAM 策略 # ===== 其他 ===== tags: # 附加到 AWS 资源的标签（资源还会自动打上 cortex.dev/cluster-name 标签） prometheus_instance_type: "t3.medium" # Prometheus 实例类型（超过 300 节点/300 Pod 时建议选更大内存实例）

几点补充说明：

• 若要复用现有 VPC，可在配置中列出子网（subnets），但要求subnet_visibility与子网实际可见性一致，且属于面向有经验用户的进阶特性；
• 集群使用到的全部 Docker 镜像都可在cluster.yaml中覆盖（如image_manager、image_operator、image_autoscaler、image_proxy、image_async_gateway、image_dequeuer、image_istio_proxy、image_prometheus等），默认为quay.io/cortexlabs/*:master系列，自托管镜像的具体做法参见 docs/clusters/advanced/self-hosted-images.md；
• 上述配置项的读取与校验逻辑分布在 pkg/types/clusterconfig 目录（如 cluster_config.go、availability_zones.go、network_validations.go）。

3.4 集群生命周期管理

cluster命令族还包含其他子命令（定义见 cli/cmd/cluster.go）：

• cortex cluster info [-c cluster.yaml]：查看集群信息，支持--output json|yaml、--print-config打印当前生效配置、--debug导出集群状态；
• cortex cluster configure cluster.yaml：更新集群配置（增删节点组、调整实例规格等，通过环境变量把变更清单传给管理容器执行）；
• cortex cluster down：销毁集群，默认还会清空 S3 bucket 内容、删除 EBS 卷与日志组；可用--keep-aws-resources保留这些资源；
• cortex cluster export：把所有 API 的配置导出为 YAML 文件；
• cortex cluster health：以表格形式逐项检查 Operator、Prometheus、Autoscaler、Activator、Async Gateway、Grafana、负载均衡等组件的存活状态。

四、环境（Environment）：多集群管理的基础

docs/start.md指向的 环境管理文档 说明了一个关键机制：执行cortex cluster up时，系统会自动创建一个与集群同名的环境，并将其设为默认环境。

常用环境命令：

cortex env list # 列出所有环境 cortex env default <ENV> # 切换默认环境 cortex env rename <OLD> <NEW> # 重命名环境 cortex env delete <ENV> # 删除环境 cortex env configure # 创建/更新一个环境（交互式填写名称与 Operator 端点）

多集群场景下的典型用法（每个集群一个环境，部署时用--env指定目标）：

cortex cluster up cluster1.yaml --configure-env cluster1 cortex cluster up cluster2.yaml --configure-env cluster2 cortex deploy --env cluster1 cortex delete my-api --env cluster1 cortex deploy --env cluster2 cortex delete my-api --env cluster2

如果在cortex cluster up时省略了--configure-env，也可以在集群创建完成后补上环境配置：

cortex cluster info cluster1.yaml --configure-env cluster1 cortex cluster info cluster2.yaml --configure-env cluster2

当你在新机器上安装 CLI 并希望连接已有集群时：先在旧机器上运行cortex env list记下目标环境的名称与 Operator 端点，再在新机器上运行cortex env configure按提示填入即可。环境配置的持久化逻辑参见 cli/cmd/lib_cli_config.go。

五、第三步：构建并部署可扩展的 API

5.1 deploy 命令的行为

cortex deploy apis.yaml

从 cli/cmd/deploy.go 的_deployCmd实现看：

• 不传配置文件时默认读取当前目录下的cortex.yaml，不存在则报错；传参数时校验文件存在性；
• 禁止从 home 目录或根目录直接部署（防止误操作）；
• 支持--env（指定环境）、--force（覆盖进行中的 API 更新）、--yes（跳过提示）、--output（json/pretty）等参数；
• 部署结果按 API 逐个返回成功/失败消息，全部失败时以非零码退出；
• cortex.yaml中可以同时声明多个 API，cortex deploy会一并创建或更新。

apis.yaml（或cortex.yaml）中的每个条目声明一个 API，核心字段包括name、kind（API 类型）与pod（容器配置）。API 的完整配置规范参见 docs/workloads/realtime/configuration.md，其中pod支持port、max_concurrency、max_queue_length、容器列表（image/command/env/compute）、readiness_probe/liveness_probe、pre_stop等；autoscaling支持min_replicas/max_replicas/target_in_flight/window/downscale_stabilization_period等；还有node_groups、update_strategy、networking.endpoint等字段。

5.2 四种 API 类型

Cortex 提供四种工作负载类型，分别覆盖不同的推理/计算模式：

5.3 以 RealtimeAPI 为例的完整部署链路

以下是 docs/workloads/realtime/example.md 给出的端到端流程（仓库 test/apis/realtime/hello-world 下有可直接对照的示例代码与配置）：

① 定义 API（main.py）

from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() class Data(BaseModel): msg: str @app.post("/") def handle_post(data: Data): return data

② 创建 Dockerfile

FROM python:3.8-slim RUN pip install --no-cache-dir fastapi uvicorn COPY main.py / CMD uvicorn --host 0.0.0.0 --port 8080 main:app

③ 本地构建、运行与验证

docker build . -t hello-world docker run -p 8080:8080 hello-world curl -X POST -H "Content-Type: application/json" -d '{"msg": "hello world"}' localhost:8080

④ 推送镜像到 ECR

# 登录 ECR aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <AWS_ACCOUNT_ID>.dkr.ecr.us-east-1.amazonaws.com # 创建仓库、打标签、推送 aws ecr create-repository --repository-name hello-world docker tag hello-world <AWS_ACCOUNT_ID>.dkr.ecr.us-east-1.amazonaws.com/hello-world docker push <AWS_ACCOUNT_ID>.dkr.ecr.us-east-1.amazonaws.com/hello-world

⑤ 编写部署配置并发布

# cortex.yaml - name: hello-world kind: RealtimeAPI pod: containers: - name: api image: <AWS_ACCOUNT_ID>.dkr.ecr.us-east-1.amazonaws.com/hello-world

cortex deploy cortex get --watch # 等待 API 就绪 cortex get hello-world # 获取 API 端点

⑥ 通过负载均衡端点请求

curl -X POST -H "Content-Type: application/json" -d '{"msg": "hello world"}' http://<api_endpoint>/hello-world

5.4 Async、Batch、Task 的差异要点

AsyncAPI：处理器代码与 Realtime 几乎一致（handle_async），但请求会先进入 SQS 队列（相关实现见 pkg/enqueuer/enqueuer.go 与 pkg/dequeuer/dequeuer.go），提交后你需要保存返回的REQUEST_ID，随后用GET请求携带该 ID 查询结果：

curl -X POST -H "Content-Type: application/json" -d '{"msg": "hello world"}' http://<api_endpoint>/hello-world curl http://<api_endpoint>/hello-world/<REQUEST_ID>

BatchAPI：处理器接收一个列表作为输入，并提供on-job-complete钩子；部署配置中需要用command覆盖容器启动命令（保持服务常驻以等待批次调度）。提交任务时通过请求体声明 worker 数量与任务切分方式：

curl -X POST -H "Content-Type: application/json" -d '{"workers": 2, "item_list": {"items": [1,2,3,4], "batch_size": 2}}' http://<api_endpoint>/hello-world cortex logs hello-world <JOB_ID>

TaskAPI：处理器是一次性脚本（直接print输出），部署配置中用command: ["python", "main.py"]执行入口；提交后通过cortex logs hello-world <JOB_ID>查看作业日志。仓库在 test/apis/task/iris-classifier-trainer 提供了训练型 Task 的完整样例。

5.5 其他常用 CLI 操作

• cortex get [API_NAME]：列出/查看 API 状态与端点，支持--watch持续等待就绪；
• cortex delete [API_NAME]：删除已部署的 API；
• cortex logs API_NAME [JOB_ID]：查看 API 或指定作业的日志（日志后端实现见 pkg/operator/operator/logging.go）；
• cortex refresh：刷新集群内运行中的 API（重新拉取镜像等）。

六、从入门到深入：推荐的后续阅读路径

docs/start.md以链接形式给出了完整的进阶地图，这里按依赖顺序整理：

1. 客户端与安装：docs/clients/install.md、docs/clients/cli.md、docs/clients/python.md；
2. 集群配置与运维：docs/clusters/management/create.md、docs/clusters/management/update.md、docs/clusters/management/environments.md、docs/clusters/management/delete.md、docs/clusters/management/auth.md；
3. 网络与安全：docs/clusters/networking/api-gateway.md、docs/clusters/networking/https.md、docs/clusters/networking/custom-domain.md、docs/clusters/networking/vpc-peering.md；
4. 可观测性：docs/clusters/observability/metrics.md、docs/clusters/observability/logging.md、docs/clusters/observability/alerting.md；
5. 四种工作负载：按需精读 realtime、async、batch、task 的主文档及各自目录下的 configuration/autoscaling/containers/statuses 子文档，并结合 test/apis 下的真实样例（如 realtime/hello-world、batch/sum、async/hello-world、task/iris-classifier-trainer）动手实践。

结语

从cortex cluster up到cortex deploy，Cortex 把"在 AWS 上搭建 ML 基础设施"和"把模型容器发布为可伸缩 API"两条路径压缩成了两个命令。本文以 docs/start.md 为骨架，结合 get-cli.sh、cli/cmd/cluster.go、cli/cmd/deploy.go 等源码揭示了这两条命令背后的真实执行链路，并完整保留了cluster.yaml的参数体系与四种 API 的部署细节。无论你是要部署在线推理、异步任务、分布式批处理还是按需训练作业，都可以从这两条命令出发，按上文的进阶路径逐步深入。

• 后端
• 云原生
• 模型推理服务
• MLOps
• 人工智能