flightcontrol-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flightcontrol Configuration

Flightcontrol 配置管理

Manage Flightcontrol deployment configurations, usually via

flightcontrol.json

flightcontrol.cue

管理Flightcontrol部署配置，通常通过

flightcontrol.json

或

flightcontrol.cue

文件进行。

When to Apply

适用场景

Use this skill when:

Creating or updating
```
flightcontrol.json
```
or
```
flightcontrol.cue
```
Adding, editing, or removing services (web, worker, database, etc.)
Configuring environments (production, staging, preview)
Setting up build, deploy, or CI runner settings
Managing environment variables and cross-service references
Troubleshooting deployment configuration issues

在以下场景中使用该技能：

创建或更新
```
flightcontrol.json
```
或
```
flightcontrol.cue
```
文件
添加、编辑或删除服务（Web、Worker、数据库等）
配置环境（生产、预发布、预览）
设置构建、部署或CI运行器参数
管理环境变量和跨服务引用
排查部署配置问题

Canonical Schema and Docs

标准Schema与文档

The hosted JSON schema is the source of truth for all properties, defaults, and validation rules.

Schema:

https://app.flightcontrol.dev/schema.json

Docs:
```
https://www.flightcontrol.dev/docs
```

Always include the schema in config files for editor validation and autocompletion:

json

{
  "$schema": "https://app.flightcontrol.dev/schema.json",
  "environments": []
}

托管的JSON Schema是所有属性、默认值和验证规则的权威来源。

Schema:

https://app.flightcontrol.dev/schema.json

文档:
```
https://www.flightcontrol.dev/docs
```

请始终在配置文件中引入该Schema，以获得编辑器验证和自动补全功能：

json

{
  "$schema": "https://app.flightcontrol.dev/schema.json",
  "environments": []
}

Minimal Structure

最小结构

json

{
  "$schema": "https://app.flightcontrol.dev/schema.json",
  "envVariables": {},
  "environments": [
    {
      "id": "production",
      "name": "Production",
      "region": "us-west-2",
      "source": { "branch": "main" },
      "services": []
    }
  ]
}

json

{
  "$schema": "https://app.flightcontrol.dev/schema.json",
  "envVariables": {},
  "environments": [
    {
      "id": "production",
      "name": "Production",
      "region": "us-west-2",
      "source": { "branch": "main" },
      "services": []
    }
  ]
}

Core Concepts

核心概念

Root:
```
envVariables
```
apply to every environment and service.

Environment:

id

name

region

source

services

, optional

envVariables

, optional

vpc

Service:

id

name

type

, optional

envVariables

, optional

dependsOn

, optional

watchPaths

根级别：
```
envVariables
```
会应用于所有环境和服务

环境：包含

id

、

name

、

region

、

source

、

services

，可选

envVariables

和

vpc

服务：包含

id

、

name

、

type

，可选

envVariables

、

dependsOn

、

watchPaths

Service Type Quick Guide

服务类型快速指南

```
web
```
: public HTTP service with load balancing and CDN.
```
web-private
```
: internal HTTP service in the VPC.
```
worker
```
: background processes, no HTTP port.
```
scheduler
```
: cron-based jobs.
```
static
```
: static site hosted on S3 + CloudFront.
```
rds
```
: managed Postgres/MySQL/MariaDB database.
```
elasticache
```
: managed Redis or Valkey cache.
```
lambda-function
```
: Lambda with Docker image or zip build.
```
network-server
```
: TCP/UDP/gRPC via Network Load Balancer.
```
s3
```
: managed S3 bucket.

```
web
```
: 带负载均衡和CDN的公开HTTP服务
```
web-private
```
: VPC内的内部HTTP服务
```
worker
```
: 后台进程，无HTTP端口
```
scheduler
```
: 基于Cron的定时任务
```
static
```
: 托管在S3 + CloudFront上的静态站点
```
rds
```
: 托管式Postgres/MySQL/MariaDB数据库
```
elasticache
```
: 托管式Redis或Valkey缓存
```
lambda-function
```
: 基于Docker镜像或Zip包构建的Lambda函数
```
network-server
```
: 通过网络负载均衡器提供TCP/UDP/gRPC服务
```
s3
```
: 托管式S3存储桶

Example Snippets

示例代码片段

Web Service

Web服务

json

{
  "id": "api",
  "name": "API Server",
  "type": "web",
  "buildType": "nixpacks",
  "cpu": 0.5,
  "memory": 1,
  "port": 3000,
  "minInstances": 1,
  "maxInstances": 3
}

json

{
  "id": "api",
  "name": "API Server",
  "type": "web",
  "buildType": "nixpacks",
  "cpu": 0.5,
  "memory": 1,
  "port": 3000,
  "minInstances": 1,
  "maxInstances": 3
}

Worker Service

Worker服务

json

{
  "id": "worker",
  "name": "Background Worker",
  "type": "worker",
  "buildType": "nixpacks",
  "cpu": 0.5,
  "memory": 1,
  "startCommand": "npm run worker"
}

json

{
  "id": "worker",
  "name": "Background Worker",
  "type": "worker",
  "buildType": "nixpacks",
  "cpu": 0.5,
  "memory": 1,
  "startCommand": "npm run worker"
}

Scheduler Service

定时任务服务

json

{
  "id": "cron",
  "name": "Scheduled Tasks",
  "type": "scheduler",
  "buildType": "nixpacks",
  "cpu": 0.5,
  "memory": 1,
  "jobs": {
    "daily-report": {
      "schedule": "0 0 * * *",
      "startCommand": ["node", "scripts/daily-report.js"]
    }
  }
}

json

{
  "id": "cron",
  "name": "Scheduled Tasks",
  "type": "scheduler",
  "buildType": "nixpacks",
  "cpu": 0.5,
  "memory": 1,
  "jobs": {
    "daily-report": {
      "schedule": "0 0 * * *",
      "startCommand": ["node", "scripts/daily-report.js"]
    }
  }
}

Static Site

静态站点

json

{
  "id": "frontend",
  "name": "Frontend",
  "type": "static",
  "buildType": "nixpacks",
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "singlePageApp": true
}

json

{
  "id": "frontend",
  "name": "Frontend",
  "type": "static",
  "buildType": "nixpacks",
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "singlePageApp": true
}

RDS Database

RDS数据库

json

{
  "id": "db",
  "name": "Database",
  "type": "rds",
  "engine": "postgres",
  "engineVersion": "16",
  "instanceSize": "db.t4g.micro",
  "storage": 20,
  "private": true
}

json

{
  "id": "db",
  "name": "Database",
  "type": "rds",
  "engine": "postgres",
  "engineVersion": "16",
  "instanceSize": "db.t4g.micro",
  "storage": 20,
  "private": true
}

ElastiCache

ElastiCache缓存

json

{
  "id": "redis",
  "name": "Redis Cache",
  "type": "elasticache",
  "engine": "redis",
  "engineVersion": "7.1",
  "instanceSize": "cache.t4g.micro"
}

json

{
  "id": "redis",
  "name": "Redis Cache",
  "type": "elasticache",
  "engine": "redis",
  "engineVersion": "7.1",
  "instanceSize": "cache.t4g.micro"
}

Lambda Function (Image)

Lambda函数（镜像版）

json

{
  "id": "lambda-api",
  "name": "Lambda API",
  "type": "lambda-function",
  "buildType": "docker",
  "dockerfilePath": "./Dockerfile.lambda",
  "lambda": {
    "packageType": "image",
    "memory": 512,
    "timeoutSecs": 30
  }
}

json

{
  "id": "lambda-api",
  "name": "Lambda API",
  "type": "lambda-function",
  "buildType": "docker",
  "dockerfilePath": "./Dockerfile.lambda",
  "lambda": {
    "packageType": "image",
    "memory": 512,
    "timeoutSecs": 30
  }
}

Network Server

网络服务

json

{
  "id": "grpc-api",
  "name": "gRPC API",
  "type": "network-server",
  "buildType": "docker",
  "cpu": 1,
  "memory": 2,
  "ports": [
    {
      "port": 50051,
      "protocol": "grpc",
      "healthCheck": {}
    }
  ]
}

json

{
  "id": "grpc-api",
  "name": "gRPC API",
  "type": "network-server",
  "buildType": "docker",
  "cpu": 1,
  "memory": 2,
  "ports": [
    {
      "port": 50051,
      "protocol": "grpc",
      "healthCheck": {}
    }
  ]
}

S3 Bucket

S3存储桶

json

{
  "id": "uploads",
  "name": "User Uploads",
  "type": "s3",
  "bucketNameBase": "myapp-uploads"
}

json

{
  "id": "uploads",
  "name": "User Uploads",
  "type": "s3",
  "bucketNameBase": "myapp-uploads"
}

Environment Variables

环境变量

Environment variables can be set at three levels: project, environment, service. Lower levels override higher.

环境变量可以在三个级别设置：项目级、环境级、服务级。低级别配置会覆盖高级别。

Static Values

静态值

json

"envVariables": {
  "NODE_ENV": "production",
  "DEBUG": false
}

json

"envVariables": {
  "NODE_ENV": "production",
  "DEBUG": false
}

From Service

从服务引用

json

"DATABASE_URL": {
  "fromService": {
    "id": "db",
    "value": "dbConnectionString"
  }
}

json

"DATABASE_URL": {
  "fromService": {
    "id": "db",
    "value": "dbConnectionString"
  }
}

From Parameter Store or Secrets Manager

从参数存储或Secrets Manager引用

json

"STRIPE_SECRET_KEY": {
  "fromParameterStore": "myapp/stripe/secret_key"
}

json

"DB_PASSWORD": {
  "fromSecretsManager": "arn:aws:secretsmanager:us-west-2:123456789:secret:myapp/db-password"
}

json

"STRIPE_SECRET_KEY": {
  "fromParameterStore": "myapp/stripe/secret_key"
}

json

"DB_PASSWORD": {
  "fromSecretsManager": "arn:aws:secretsmanager:us-west-2:123456789:secret:myapp/db-password"
}

Preview Environments

预览环境

json

{
  "id": "preview",
  "name": "Preview",
  "region": "us-west-2",
  "source": {
    "pr": true,
    "trigger": "push",
    "filter": {
      "toBranches": ["main"],
      "fromBranches": ["feature/**"]
    }
  },
  "services": []
}

json

{
  "id": "preview",
  "name": "Preview",
  "region": "us-west-2",
  "source": {
    "pr": true,
    "trigger": "push",
    "filter": {
      "toBranches": ["main"],
      "fromBranches": ["feature/**"]
    }
  },
  "services": []
}

Build & Deploy Commands

构建与部署命令

When buildType is nixpacks

当buildType为nixpacks时

All build, deploy, and start commands are single string

所有构建、部署和启动命令均为单个字符串

When buildType is Dockerfile

当buildType为Dockerfile时

The pre and post deploy and start commands will be passed to the docker image as CMD at runtime
The CMD value is passed to the ENTRYPOINT value
If ENTRYPOINT not defined, the commands need to be an array like
```
["/bin/sh", "-c", "pnpm start"]
```

部署前后命令和启动命令会作为CMD传递给Docker镜像在运行时执行
CMD值会传递给ENTRYPOINT值
如果未定义ENTRYPOINT，命令需要以数组形式传递，例如
```
["/bin/sh", "-c", "pnpm start"]
```

Validation

配置验证

After every change to a Flightcontrol config file, validate it using:

bash

npx flightcontrol-validate <config-file>

每次修改Flightcontrol配置文件后，请使用以下命令验证：

bash

npx flightcontrol-validate <config-file>

Exit Codes

退出码

```
0
```
= valid config
```
1
```
= validation errors (fix before proceeding)
```
2
```
= file not found or parse error

```
0
```
= 配置有效
```
1
```
= 验证错误（修复后再继续）
```
2
```
= 文件未找到或解析错误

Example Output

示例输出

Success:

json

{ "valid": true, "file": "flightcontrol.json" }

Validation errors:

json

{
  "valid": false,
  "file": "flightcontrol.json",
  "errors": {
    "environments": [
      {
        "services": [
          {
            "memory": "Invalid input: expected number, received string"
          }
        ]
      }
    ]
  }
}

成功：

json

{ "valid": true, "file": "flightcontrol.json" }

验证错误：

json

{
  "valid": false,
  "file": "flightcontrol.json",
  "errors": {
    "environments": [
      {
        "services": [
          {
            "memory": "Invalid input: expected number, received string"
          }
        ]
      }
    ]
  }
}

AI Guidance

AI指导建议

Always validate with
```
npx flightcontrol-validate <file>
```
after each config edit. Fix any errors and re-validate before proceeding. Only show validation output to the user when there are errors.
Always keep
```
$schema
```
and prefer the hosted schema for exact fields and defaults.
Changing existing
```
id
```
values will create a new entity. The old one will be orphaned and can be deleted from the dashboard.
Validate
```
fromService.id
```
references against existing service IDs.
Ensure region consistency for VPC, Parameter Store, and Secrets Manager.

务必验证：每次编辑配置文件后，使用
```
npx flightcontrol-validate <file>
```
命令验证。修复所有错误后再继续。仅当存在错误时才向用户展示验证输出。
请始终保留
```
$schema
```
引用，优先使用托管的Schema以获取准确的字段和默认值。
修改已有的
```
id
```
值会创建新的实体。旧实体将成为孤立资源，可在控制台中删除。
验证
```
fromService.id
```
引用是否指向已存在的服务ID。
确保VPC、参数存储和Secrets Manager的区域一致性。

flightcontrol-config

Original

Translation

Flightcontrol Configuration

Flightcontrol 配置管理

When to Apply

适用场景

Canonical Schema and Docs

标准Schema与文档

Minimal Structure

最小结构

Core Concepts

核心概念

Service Type Quick Guide

服务类型快速指南

Example Snippets

示例代码片段

Web Service

Web服务

Worker Service

Worker服务

Scheduler Service

定时任务服务

Static Site

静态站点

RDS Database

RDS数据库

ElastiCache

ElastiCache缓存

Lambda Function (Image)

Lambda函数（镜像版）

Network Server

网络服务

S3 Bucket

S3存储桶

Environment Variables

环境变量

Static Values

静态值

From Service

从服务引用

From Parameter Store or Secrets Manager

从参数存储或Secrets Manager引用

Preview Environments

预览环境

Build & Deploy Commands

构建与部署命令

When buildType is nixpacks

当buildType为nixpacks时

When buildType is Dockerfile

当buildType为Dockerfile时

Validation

配置验证

Exit Codes

退出码

Example Output

示例输出

AI Guidance

AI指导建议

References

参考资料