cf-cli

Cloud Foundry CLI 技能

你是 Cloud Foundry CLI（v8）方面的专家。帮助用户构建正确的 cf 命令、编写清单、自动化部署、管理服务并排查问题。目标是让用户无需不断运行 cf help，就能获得准确、可直接运行的命令。

**重要提示：**v7 和 v6 已不再维护。请始终使用 v8 语法。v8 CLI 基于 CC API v3。

安装

请参阅 V8 Installation Guide 进行安装。可通过软件包管理器（Homebrew、apt、yum、Chocolatey）安装，也可下载二进制文件。

验证：cf version

身份验证与目标设置

cf api

设置 Cloud Foundry 实例的 API 端点。

cf api https://api.example.com
cf api https://api.example.com --skip-ssl-validation   # dev/self-signed certs only
cf api                                                   # show current API

cf login

交互式登录——会提示输入所有未提供的信息：

cf login                                                # fully interactive
cf login -a https://api.example.com                     # set API + login
cf login -a https://api.example.com -u [email protected] # preset username
cf login -a https://api.example.com --sso               # SSO via one-time passcode
cf login -o my-org -s dev                               # target org + space on login

标志	描述
-a	API 端点 URL
-u	用户名
-p	密码（请避免使用——会记录在 shell 历史记录中）
-o	目标组织
-s	目标空间
--sso	使用登录 URL 提供的一次性密码进行 SSO
--sso-passcode <code>	直接提供 SSO 密码
--origin <origin>	指定身份提供商来源
--skip-ssl-validation	跳过 SSL 证书验证

cf auth

用于脚本和 CI/CD 的非交互式身份验证：

cf auth username password
cf auth username password --origin ldap
cf auth --client-credentials                    # uses CF_USERNAME and CF_PASSWORD env vars

cf target

登录后切换组织和空间上下文：

cf target -o my-org -s dev
cf target -s staging                            # switch space only
cf target                                       # show current target

cf logout

cf logout

应用生命周期

cf push（别名：p）

最重要的命令——用于部署应用。

cf push my-app                                           # push from current dir
cf push my-app -p ./build                                # push specific path
cf push my-app -f manifest.yml                           # use specific manifest
cf push my-app -b nodejs_buildpack                       # explicit buildpack
cf push my-app -i 3 -m 512M -k 1G                       # 3 instances, 512MB RAM, 1GB disk
cf push my-app --no-start                                # stage but don't start
cf push my-app --no-route                                # no route (workers/tasks)
cf push my-app --random-route                            # generate random route
cf push my-app --strategy rolling                        # zero-downtime rolling deploy
cf push my-app --docker-image my-registry/my-image:tag   # docker image
cf push -f manifest.yml --var host=my-host               # variable substitution
cf push -f manifest.yml --vars-file vars.yml             # vars from file

重要标志：-b buildpack，-c 命令，-f 清单，-i 实例数，-k 磁盘，-m 内存，-p 路径，-s 堆栈，-t 超时，-u 健康检查类型（port/http/process），-o/--docker-image，--docker-username（通过 CF_DOCKER_PASSWORD 提供密码），--droplet，--endpoint，--no-manifest，--no-route，--no-start，--no-wait，--random-route，--strategy（rolling/null），--task，--var KEY=VALUE，--vars-file PATH。

Push 环境变量：CF_DOCKER_PASSWORD、CF_STAGING_TIMEOUT=15（分钟）、CF_STARTUP_TIMEOUT=5（分钟）。

应用管理

cf apps                          # list all apps in current space
cf app my-app                    # show app details (instances, memory, routes, state)
cf start my-app                  # start a stopped app
cf stop my-app                   # stop a running app
cf restart my-app                # restart (re-containerize, same droplet)
cf restage my-app                # restage (re-build droplet from source)
cf delete my-app                 # delete app (prompts for confirmation)
cf delete my-app -f              # force delete (no confirmation)
cf delete my-app -r              # also delete mapped routes
cf rename my-app new-name        # rename an app
cf scale my-app -i 5             # scale to 5 instances
cf scale my-app -m 1G -k 2G     # change memory and disk
cf scale my-app -i 5 -m 1G      # scale instances and memory together

部署与回滚

cf push my-app --strategy rolling          # zero-downtime rolling deploy
cf cancel-deployment my-app                # cancel an in-progress deployment

日志与事件

cf logs my-app                   # tail live logs
cf logs my-app --recent          # dump recent logs
cf events my-app                 # show recent app events (crashes, scaling, etc.)

SSH

cf ssh my-app                              # SSH into first instance
cf ssh my-app -i 2                         # SSH into instance index 2
cf ssh my-app -c "cat /app/config.yml"     # run a command and exit
cf enable-ssh my-app / cf disable-ssh my-app / cf ssh-enabled my-app

任务

cf run-task my-app --command "rake db:migrate"    # run a one-off task
cf run-task my-app -c "rake db:migrate" -m 512M   # with memory limit
cf tasks my-app                                    # list tasks
cf terminate-task my-app TASK_ID                   # cancel a running task

环境变量

cf env my-app                              # show all env vars (user + system)
cf set-env my-app DATABASE_URL "postgres://..."    # set a var
cf unset-env my-app DATABASE_URL           # remove a var
cf restage my-app                          # restage for changes to take effect

执行 set-env 或 unset-env 后，需要重新暂存或重启应用，变更才会生效。

健康检查

cf get-health-check my-app
cf set-health-check my-app http --endpoint /health
cf set-health-check my-app port
cf set-health-check my-app process

软件包与 Droplet

cf packages my-app / cf create-package my-app      # list / upload packages
cf droplets my-app / cf set-droplet my-app GUID     # list / set active droplet
cf download-droplet my-app / cf stage-package my-app --package-guid GUID

清单

清单（manifest.yml）用于声明应用配置。执行 cf push 时，CF 会自动读取当前目录中的清单。

---
applications:
- name: my-app
  memory: 512M
  disk_quota: 1G
  instances: 2
  buildpacks:
  - nodejs_buildpack
  command: node server.js
  health-check-type: http
  health-check-http-endpoint: /health
  timeout: 120
  stack: cflinuxfs4
  env:
    NODE_ENV: production
    LOG_LEVEL: info
  routes:
  - route: my-app.example.com
  - route: my-app.example.com/api
  services:
  - my-database
  - my-redis
  processes:
  - type: web
    instances: 2
    memory: 512M
  - type: worker
    instances: 1
    memory: 256M
    command: node worker.js
    health-check-type: process
    no-route: true

清单中的变量替换：

# manifest.yml
applications:
- name: ((app-name))
  instances: ((instances))

cf push --var app-name=my-app --var instances=3
# or from a file:
cf push --vars-file production.yml

根据正在运行的应用创建清单：

cf create-app-manifest my-app              # generates manifest.yml from current state
cf create-app-manifest my-app -p ./out     # write to specific directory

服务

Marketplace

cf marketplace                              # list all available services
cf marketplace -e SERVICE_NAME              # show plans for a specific service
cf marketplace -s SERVICE_NAME              # alias for -e

服务实例

cf services                                # list service instances in current space
cf service my-db                           # show details for a service instance

# Create
cf create-service SERVICE PLAN NAME        # create from marketplace
cf create-service postgres standard my-db
cf create-service postgres standard my-db -c '{"storage":"50gb"}'  # with params
cf create-service postgres standard my-db -c config.json           # params from file
cf create-service postgres standard my-db -t "env:prod,team:api"   # with tags

# Update
cf update-service my-db -p premium         # change plan
cf update-service my-db -c '{"key":"val"}' # update params
cf upgrade-service my-db                   # upgrade to latest version

# Delete
cf delete-service my-db
cf delete-service my-db -f                 # no confirmation

cf rename-service my-db new-db-name

绑定与解绑

cf bind-service my-app my-db               # bind service to app
cf bind-service my-app my-db -c '{"role":"admin"}'  # with config
cf unbind-service my-app my-db             # unbind
cf restage my-app                          # restage to pick up new bindings

绑定会将凭据注入 VCAP_SERVICES 环境变量。

服务密钥

服务密钥让你无需将服务绑定到应用，也能获取凭据：

cf create-service-key my-db my-key
cf create-service-key my-db my-key -c '{"permissions":"read-only"}'
cf service-keys my-db                       # list keys
cf service-key my-db my-key                 # show credentials
cf delete-service-key my-db my-key

用户提供的服务

用于 Marketplace 中没有的外部服务：

# Interactive (prompts for each param)
cf create-user-provided-service my-ext -p "host, port, username, password"

# Non-interactive (JSON)
cf cups my-ext -p '{"host":"db.example.com","port":"5432","user":"admin","password":"secret"}'

# Syslog drain
cf cups my-logger -l syslog://logs.example.com:514

# Route service
cf cups my-proxy -r https://proxy.example.com

# Update
cf update-user-provided-service my-ext -p '{"password":"new-secret"}'

cups 是 create-user-provided-service 的别名，uups 是 update-user-provided-service 的别名。

服务共享与路由服务

cf share-service my-db -s other-space [-o other-org]
cf unshare-service my-db -s other-space
cf bind-route-service example.com my-proxy --hostname my-app
cf unbind-route-service example.com my-proxy --hostname my-app

路由与域名

域名

cf domains                                          # list all domains
cf create-private-domain my-org apps.internal        # internal/private domain
cf delete-private-domain apps.internal
cf create-shared-domain shared.example.com           # shared across all orgs
cf delete-shared-domain shared.example.com
cf router-groups                                     # list router groups

路由

cf routes                                            # list all routes in current space
cf route my-app.example.com                          # show route details

cf create-route example.com --hostname my-app        # create route
cf create-route apps.internal --hostname backend      # internal route
cf create-route example.com --hostname my-app --path /api  # with path

cf map-route my-app example.com --hostname my-app    # map route to app
cf unmap-route my-app example.com --hostname my-app  # unmap

cf delete-route example.com --hostname my-app        # delete route
cf delete-orphaned-routes                             # clean up unmapped routes

cf check-route example.com --hostname my-app          # check if route exists

组织与空间

组织

cf orgs                          # list orgs
cf org my-org                    # show org details (spaces, domains, quotas)
cf create-org my-org
cf delete-org my-org
cf rename-org my-org new-org

空间

cf spaces                        # list spaces in current org
cf space dev                     # show space details
cf create-space staging
cf delete-space staging
cf rename-space staging production
cf apply-manifest -f manifest.yml  # apply manifest to current space

空间 SSH

cf allow-space-ssh SPACE / cf disallow-space-ssh SPACE / cf space-ssh-allowed SPACE

用户与角色管理

cf org-users my-org                                              # list org users
cf space-users my-org dev                                        # list space users
# Org roles: OrgManager, BillingManager, OrgAuditor
cf set-org-role [email protected] my-org OrgManager
cf unset-org-role [email protected] my-org OrgManager
# Space roles: SpaceManager, SpaceDeveloper, SpaceAuditor, SpaceSupporter
cf set-space-role [email protected] my-org dev SpaceDeveloper
cf unset-space-role [email protected] my-org dev SpaceDeveloper

管理

Buildpacks： cf buildpacks（列出）、cf create-buildpack NAME PATH POSITION、cf update-buildpack NAME -p PATH、cf delete-buildpack NAME。

网络策略： cf network-policies、cf add-network-policy APP DEST --protocol tcp --port 8080、cf remove-network-policy APP DEST --protocol tcp --port 8080。

安全组： cf security-groups、cf create-security-group NAME rules.json、cf bind-security-group NAME ORG SPACE --lifecycle running、cf bind-running-security-group NAME（全局默认）。

配额： cf org-quotas、cf create-org-quota NAME -m 10G -i 100 -r 50 -s 20、cf set-org-quota ORG QUOTA。空间配额：cf space-quotas、cf create-space-quota NAME -m 5G、cf set-space-quota SPACE QUOTA。

功能标志： cf feature-flags、cf enable-feature-flag FLAG、cf disable-feature-flag FLAG。

高级命令

cf curl

直接调用 API——对自动化和调试非常有用：

cf curl /v3/apps                              # list apps via API
cf curl /v3/apps/APP_GUID                     # get specific app
cf curl /v3/apps -X POST -d '{"name":"my-app","relationships":{"space":{"data":{"guid":"SPACE_GUID"}}}}'
cf curl "/v3/apps?names=my-app"               # query by name

cf config

cf config --trace true                # enable API tracing (like CF_TRACE=true)
cf config --trace /tmp/cf-trace.log   # trace to file
cf config --color false               # disable colored output
cf config --locale en-US              # set locale

cf oauth-token

cf oauth-token                        # print current access token (for scripting)

环境变量

变量	描述
CF_HOME	覆盖 ~/.cf 配置目录的位置
CF_TRACE	设为 true 可启用 API 跟踪，也可指定跟踪日志文件路径
CF_COLOR	设为 false 可禁用彩色输出
CF_DOCKER_PASSWORD	用于 cf push --docker-image 的 Docker 注册表密码
CF_STAGING_TIMEOUT	等待暂存的最长分钟数（默认值：15）
CF_STARTUP_TIMEOUT	等待应用启动的最长分钟数（默认值：5）
CF_DIAL_TIMEOUT	API 连接的最长秒数（默认值：5）

插件

cf plugins                                          # list installed plugins
cf install-plugin PLUGIN                            # install (local path, URL, or repo name)
cf install-plugin -r CF-Community my-plugin         # from registered repo
cf uninstall-plugin my-plugin
cf repo-plugins                                     # list available plugins
cf list-plugin-repos                                # list registered repos
cf add-plugin-repo CF-Community https://plugins.cloudfoundry.org
cf remove-plugin-repo CF-Community

插件代码使用 import "code.cloudfoundry.org/cli/v9/plugin"。

MTA / Multiapps 插件（cf deploy）

CAP 应用和 MTA 项目使用 multiapps CF CLI 插件，以 .mtar 归档的形式部署。该插件提供 cf deploy 命令（与 cf push 不同）。

安装插件和构建工具

运行 mbt build 或 cf deploy 前，请确认两个工具均已就绪。运行以下检查，并在缺少时安装：

# Check and install mbt (MTA Build Tool)
if ! command -v mbt &>/dev/null; then
  echo "mbt not found — installing..."
  npm install -g mbt
else
  echo "mbt $(mbt --version) already installed"
fi

# Check and install the multiapps CF CLI plugin
if ! cf plugins | grep -q multiapps; then
  echo "multiapps plugin not found — installing..."
  cf install-plugin multiapps -f
else
  echo "multiapps plugin already installed"
  cf plugins | grep multiapps
fi

构建并部署 MTA

# Build the .mtar archive from mta.yaml
mbt build

# Deploy the archive to the targeted CF org/space
cf deploy mta_archives/<app>_1.0.0.mtar

# Deploy with verbose output
cf deploy mta_archives/<app>_1.0.0.mtar -e config.mtaext

# Check deploy status
cf mta-ops                          # list ongoing MTA operations
cf mta <mta-id>                     # show MTA status
cf mtas                             # list all deployed MTAs
cf undeploy <mta-id> --delete-services  # remove an MTA + its services

cf deploy 故障排查

错误	原因	修复方法
unknown command 'deploy'	未安装 multiapps 插件	cf install-plugin multiapps
service plan 'extended' not available	AI Core extended 计划未获授权，或组织计划受限	检查 BTP 授权；CAP 与 AI Core 配合使用时需要 extended 计划
MTA ID already exists	上一次部署留下了部分状态	运行 cf undeploy <mta-id>，然后重试
构建失败并出现 npm 错误	mta.yaml 中的 Node 版本不匹配	确保 package.json 中的 engines.node 与 CF buildpack 版本一致

故障排查

常见问题

症状	可能原因	修复方法
FAILED - Not logged in	令牌已过期或尚未通过身份验证	再次运行 cf login
FAILED - No org/space targeted	缺少目标上下文	运行 cf target -o ORG -s SPACE
推送时应用崩溃	启动命令有误或缺少依赖项	检查 cf logs APP --recent 中的错误
暂存失败	buildpack 错误或缺少文件	使用 -b 验证 buildpack，并检查 .cfignore
超出 CF_STAGING_TIMEOUT	应用暂存耗时过长	增大 CF_STAGING_TIMEOUT 或优化构建
SSL 证书错误	使用了自签名证书	使用 --skip-ssl-validation（仅限开发环境），或安装证书
路由已存在	其他应用或空间已拥有该路由	使用 cf routes 查找，或使用 --random-route
服务绑定失败	服务尚未就绪或空间有误	检查 cf service SERVICE 状态

调试步骤

1. 检查日志： cf logs my-app --recent — 始终首先尝试此操作
2. 启用跟踪： CF_TRACE=true cf push my-app — 查看 API 请求/响应
3. 检查事件： cf events my-app — 查看近期崩溃、重新暂存和扩缩容情况
4. 通过 SSH 登录： cf ssh my-app — 检查正在运行的容器
5. 检查环境变量： cf env my-app — 验证 VCAP_SERVICES 和用户环境变量
6. 调试 API： cf curl /v3/apps/GUID/processes — 检查进程级别的详细信息

验证命令是否成功

cf push my-app
echo $?    # 0 = success, non-zero = failure

常见工作流

部署带有 Postgres 服务的 Node.js 应用

cf login -a https://api.example.com --sso
cf target -o my-org -s dev
cf create-service postgres standard my-db
cf push my-app -b nodejs_buildpack
cf bind-service my-app my-db
cf restage my-app

零停机部署

cf push my-app --strategy rolling
# If something goes wrong mid-deploy:
cf cancel-deployment my-app

CI/CD 流水线模式

cf api https://api.example.com
cf auth "$CF_USERNAME" "$CF_PASSWORD"
cf target -o my-org -s production
cf push my-app -f manifest-prod.yml --strategy rolling --no-wait

根据负载进行扩缩容

cf scale my-app -i 10              # scale out to 10 instances
cf scale my-app -m 1G              # increase memory per instance