企业官网建设流程全解析

• 云原生
• 后端
• 微服务

nuctl create是 Nuclio 官方命令行工具 nuctl 中负责“创建资源”的命令组，它统一管理三类核心资源的创建：项目（project）、API 网关（apigateway）和函数事件（functionevent）。本文以 nuctl_create.md 为骨架，结合仓库源码与集成测试，完整讲解每个子命令的用法、全部参数、执行流程与底层实现，读完即可在 Kubernetes（kube）或本地（local）平台上熟练使用 nuctl 创建和编排 Nuclio 资源。

nuctl create 命令组概览

nuctl create是 nuctl 的一个命令组（cobra 命令树中的父命令），本身不直接执行任何创建动作，而是将请求分发给三个子命令。在其命令定义中可以看到完整的子命令注册逻辑：

// pkg/nuctl/command/create.go cmd := &cobra.Command{ Use: "create", Aliases: []string{"cre"}, Short: "Create resources", } createProjectCommand := newCreateProjectCommandeer(ctx, commandeer).cmd createFunctionEventCommand := newCreateFunctionEventCommandeer(ctx, commandeer).cmd createAPIGatewayCommand := newCreateAPIGatewayCommandeer(ctx, commandeer).cmd cmd.AddCommand( createProjectCommand, createFunctionEventCommand, createAPIGatewayCommand, )

create命令自身只暴露一个选项：

-h, --help help for create

三个子命令及对应的短别名（来自源码 create.go 的Aliases字段）如下：

三个子命令均要求恰好一个位置参数作为资源名称：源码中通过if len(args) != 1校验，否则返回 “requires an identifier” 之类的错误。例如创建项目缺少名称时会报Project create requires an identifier。

公共选项：所有 nuctl 子命令继承的参数

以下选项由 nuctl 根命令定义（见 nuctl.go 中的PersistentFlags），对nuctl create及其全部子命令都生效：

--concurrency int Max number of parallel patches. The default value is equal to the number of CPUs. (default 4) -k, --kubeconfig string Path to a Kubernetes configuration file (admin.conf) --mask-sensitive-fields Enable sensitive fields masking -n, --namespace string Namespace --platform string Platform identifier - "kube", "local", or "auto" (default "auto") -v, --verbose Verbose output

参数含义与底层行为说明：

• --platform：选择目标平台，取值kube、local或auto，默认auto。源码中默认值来自环境变量NUCTL_PLATFORM（未设置时回退到auto，见 nuctl.go 中的common.GetEnvOrDefaultString("NUCTL_PLATFORM", common.AutoPlatformName)）。auto模式由factory.CreatePlatform根据环境自动解析出具体平台实现；平台常量定义在 consts.go（AutoPlatformName = "auto"、KubePlatformName = "kube"、LocalPlatformName = "local"）。
• -n, --namespace：指定资源所在命名空间。若未显式传入，根命令的resolveDefaultNamespace()会按平台解析：kube 平台读取 kubeconfig 当前上下文的命名空间，local 平台回退到nuclio。也可通过环境变量NUCTL_NAMESPACE预设默认值。
• -k, --kubeconfig：指向 Kubernetes 配置文件（如admin.conf）的路径，仅在 kube 平台下有意义。
• --concurrency：并行补丁（patch）的最大数量，默认等于 CPU 核数（源码中为runtime.NumCPU()，文档生成时按默认机器显示为 4）。
• --mask-sensitive-fields：启用敏感字段脱敏。开启后根命令会调用platformConfiguration.EnableSensitiveFieldMasking()，在输出或导出资源时对密码等敏感信息打码。这一点在 API 网关的集成测试中体现得很直接：创建 basicAuth 网关后执行get，测试断言输出中不包含密码明文（见 apigagteway_test.go）。
• -v, --verbose：输出调试级日志（DebugLevel），默认仅输出 Info 级别。

nuctl create project：创建项目

项目是 Nuclio 资源（函数、API 网关、函数事件）的逻辑归属容器。相关 CLI 文档见 nuctl_create_project.md。

用法与参数

nuctl create project name [flags]

典型用法：

# 创建一个带描述和所有者的项目 nuctl create project my-project --description "Data processing project" --owner "data-team" # 使用短别名 nuctl create proj my-project

源码实现与执行流程

创建项目由createProjectCommandeer实现（create.go），关键步骤：

1. 将位置参数写入ProjectConfig.Meta.Name，将根命令解析出的命名空间写入Meta.Namespace；
2. 把--description、--owner分别写入ProjectConfig.Spec.Description和ProjectConfig.Spec.Owner；
3. 调用平台抽象接口platform.CreateProject(ctx, &platform.CreateProjectOptions{ProjectConfig: ...})；
4. 成功后打印Project created日志（含名称与命名空间）。

对应的数据结构定义在 types.go：ProjectMeta包含Name、Namespace、Labels、Annotations等字段；ProjectSpec包含Description、Owner以及DefaultFunctionNodeSelector（默认函数节点选择器，CLI 未直接暴露，可通过配置或导入方式设置）。CreateProject是 platform.go 中Platform接口声明的核心方法之一，kube 与 local 平台各自提供实现，这也是 nuctl 一套命令同时支撑两种部署形态的原因。

集成测试（project_test.go）演示了项目创建与后续管理：创建时传入description，随后用nuctl get project校验；测试还验证了项目内含函数时无法直接删除、级联删除（DeleteProjectStrategyCascading）与受限删除（DeleteProjectStrategyRestricted）两种策略的行为差异，说明项目与函数之间存在强关联约束。

nuctl create functionevent：创建函数事件

函数事件（Function Event）本质上是函数调用的预置模板：把触发参数、请求体等绑定为一个具名资源，之后可反复用它触发函数。相关 CLI 文档见 nuctl_create_functionevent.md。

用法与参数

nuctl create functionevent name [flags]

典型用法：

# 为函数 my-func 创建一个名为 my-event 的函数事件 nuctl create functionevent my-event \ --function my-func \ --display-name "My Event" \ --trigger-kind http \ --body '{"key": "value"}'

源码实现与执行流程

createFunctionEventCommandeer（create.go）的执行逻辑：

1. 校验位置参数数量，并强制要求--function非空（否则报Function event must belong to a function）；
2. 将名称写入FunctionEventConfig.Meta.Name、命名空间写入Meta.Namespace，并自动打上标签nuclio.io/function-name（标签键常量见 consts.go），从而把事件与函数关联起来；
3. 将--attrs的 JSON 内容解码到Spec.Attributes；
4. 调用platform.CreateFunctionEvent(ctx, &platform.CreateFunctionEventOptions{...})。

FunctionEventSpec结构（types.go）包含DisplayName、TriggerName、TriggerKind、Body、Attributes五个字段，与 CLI 参数一一对应。注意FunctionEventTriggerKind定义了http作为默认触发类型（DefaultFunctionEventTriggerKind = FunctionEventTriggerKindHTTP），因此不指定--trigger-kind时事件默认按 HTTP 触发器语义处理。

集成测试（project_test.go 中的createFunctionEvent）验证了事件创建后可通过nuctl get functionevent --function <func>按函数过滤查询，并校验display-name与nuclio.io/function-name标签是否正确写入。

nuctl create apigateway：创建 API 网关

API 网关把 Nuclio 函数暴露为对外 HTTP 端点，支持主机名、路径、认证与金丝雀（canary）灰度流量。相关 CLI 文档见 nuctl_create_apigateway.md。

用法与参数

nuctl create apigateway name [flags]

典型用法：

# 无认证网关，把函数 my-func 暴露到 my.example.com nuctl create apigateway my-gateway \ --project my-project \ --host my.example.com \ --path /api \ --function my-func # basicAuth 认证 + 金丝雀灰度：25% 流量打到 canary-func nuctl create apigateway my-gateway \ --project my-project \ --host my.example.com \ --path /api \ --function my-func \ --authentication-mode basicAuth \ --basic-auth-username admin \ --basic-auth-password s3cret \ --canary-function canary-func \ --canary-percentage 25

源码实现与执行流程

createAPIGatewayCommandeer（create.go）的执行逻辑较为复杂，要点如下：

1. 参数装配：把--host、--description、--path写入APIGatewaySpec对应字段；--project非空时写入标签nuclio.io/project-name。
2. 认证模式：未指定--authentication-mode时默认为none（auth.AuthenticationModeNone）；指定basicAuth时强制要求同时提供用户名和密码，否则报Basic auth username and password must be specified，并组装APIGatewayAuthenticationSpec.BasicAuth。认证模式枚举定义在 auth/types.go：none、basicAuth、accessKey、oauth2、iguazio、api、browser，CLI 帮助文本列出的是none、basicAuth、accessKey、iguazio四个常用值。
3. 主函数校验：--function为空直接报A primary function must be specified。
4. upstream 组装：主函数被构造成APIGatewayUpstreamSpec{Kind: nucliofunction, NuclioFunction: {Name: ...}}，可附加--labels指定的自定义标签；若指定了--canary-function则必须给出--canary-percentage（否则报Canary function percentage must be specified），金丝雀 upstream 额外携带Percentage分流比例。
5. 状态标记：创建前把Status.State置为waitingForProvisioning（APIGatewayStateWaitingForProvisioning，见 types.go 中的状态枚举），表示资源已提交、等待平台完成实际部署。
6. 调用platform.CreateAPIGateway(ctx, &platform.CreateAPIGatewayOptions{...})。

APIGatewaySpec结构（types.go）包含Host、Name、Description、Path、AuthenticationMode、Authentication、Upstreams字段；APIGatewayUpstreamSpec还支持Port、RewriteTarget、ExtraAnnotations等高级配置，可通过--attrs传入完整 JSON 实现超出 CLI 参数的细粒度控制（--attrs的优先级最高，源码注释明确 “overrides all the rest”）。

API 网关的集成测试验证

apigagteway_test.go 提供了创建、查询、删除的完整端到端验证，值得关注的行为包括：

• 敏感字段脱敏：创建 basicAuth 网关后执行get -o yaml，测试断言输出中不出现basic-password明文（密码被存入 Secret）；
• 路径校验：传入包含空格的非法path时，创建会失败并报Failed to validate and enrich an API gateway；
• 保留名称保护：使用dashboard等保留名创建网关会被拒绝（Resource name is reserved）；
• 按函数过滤：nuctl get apigateway --function-name <func>只返回与该函数绑定的网关。

这些用例都通过suite.ExecuteNuctl驱动真实 nuctl 命令执行，可作为自测时的行为参考。

底层调用链：从 CLI 到平台抽象

无论创建哪种资源，nuctl create的执行路径都遵循同一套架构模式（见 nuctl.go）：

1. 子命令RunE先调用rootCommandeer.initialize(true)：初始化日志、加载平台配置（platformconfig.NewPlatformConfig）、解析命名空间，并让factory.CreatePlatform按--platform值创建对应的platform.Platform实现；
2. 命令层把 CLI 参数组装成对应的*Config结构（ProjectConfig/FunctionEventConfig/APIGatewayConfig，定义于 types.go）；
3. 调用 platform.go 中Platform接口声明的CreateProject/CreateFunctionEvent/CreateAPIGateway方法；
4. 平台实现（kube 平台负责落库 CRD、local 平台负责本地状态管理）完成实际资源创建。

这种“命令层 — 平台接口 — 平台实现”的三层设计，使同一套nuctl create语法在 kube 集群与本地 Docker 环境下行为一致，是 Nuclio CLI 的核心架构特征。

相关参考

• 本命令组文档：nuctl_create.md
• 子命令文档：nuctl_create_project.md、nuctl_create_functionevent.md、nuctl_create_apigateway.md
• nuctl 根命令与公共参数：nuctl.md
• 命令实现源码：pkg/nuctl/command/create.go、pkg/nuctl/command/nuctl.go
• 资源类型定义：pkg/platform/types.go
• 平台接口：pkg/platform/platform.go
• 认证模式定义：pkg/auth/types.go
• 集成测试：pkg/nuctl/test/project_test.go、pkg/nuctl/test/apigagteway_test.go

补充说明：本文档目录（docs/reference/nuctl/cli/）下的各命令 Markdown 文件由 nuctl 根命令的CreateMarkdown方法通过 cobra 文档生成器自动产出（见 nuctl.go 中的doc.GenMarkdownTree），因此所有参数文本与源码中的 flag 定义严格同步，可放心以此为准进行日常使用与排障。

• 云原生
• 后端
• 微服务