命令行工具 CLI 使用指南

命令行工具（lean）是用来部署云引擎应用和进行其他管理操作的客户端工具。

安装

macOS

推荐通过 Homebrew 安装：

brew update && brew install lean-cli

点击展开 Homebrew 安装常见问题

Windows

Windows 用户可以在 GitHub releases 页面根据操作系统版本下载最新的 32 位或 64 位 msi 安装包进行安装，安装成功之后在 Windows 命令提示符（或 PowerShell）下直接输入 lean 命令即可使用。

也可以选择编译好的绿色版 exe 文件，下载后将此文件更名为 lean.exe，并将其路径加入到系统 PATH 环境变量（设置方法）中去。这样使用时在 Windows 命令提示符（或 PowerShell）下，在任意目录下输入 lean 就可以使用命令行工具了。当然也可以将此文件直接放到已经在 PATH 环境变量中声明的任意目录中去，比如 C:\Windows\System32 中。

Linux

基于 Debian 的发行版可以从 GitHub releases 页面下载 deb 包安装。

其他发行版可以从 GitHub releases 页面下载预编译好的二进制文件（如 lean-linux-x64），重命名为 lean 后移动到 $PATH 下的路径，并添加可执行权限（chmod a+x /path/to/lean）。

升级版本

下载最新的文件，重新执行一遍安装流程，即可把旧版本的命令行工具覆盖，升级到最新版。

命令介绍

安装成功之后，直接在 terminal 终端运行 lean help，输出帮助信息：

点击展开 lean help 的输出

可以通过 --version 选项查看命令行工具的版本：

$ lean --version
lean version 1.0.0

简单介绍下主要的子命令：

命令	用途
`login`	登录账号
`switch`	切换关联的云引擎应用和分组
`info`	显示当前应用和分组信息
`up`	启动本地开发调试
`new`	从项目模板创建新项目
`deploy`	部署项目至云引擎
`publish`	将预备环境的版本发布至生产环境
`db`	访问云端的 LeanCache 或 LeanDB
`file`	上传文件至数据存储服务（可以在云服务控制台 > 数据存储 > 文件中查看）
`logs`	显示云引擎日志
`debug`	单独启动云函数调试控制台（不运行应用本身）
`env`	显示或设置当前项目的环境变量

用 lean <command> --help 可以进一步了解每个子命令的用法，例如：

点击展开 lean deploy --help 的输出

登录账号

安装完命令行工具之后，首先第一步需要登录云服务账号。

如要切换到另一账号，重新执行 lean login 即可。

初始化项目

登录完成之后，可以使用 lean new 命令来初始化一个项目，并且关联到已有的云服务应用上。

如果你还没有在控制台创建过应用，请先在控制台创建应用，然后使用 lean new 创建项目：

$ lean new my-engine-app
[?] Please select an app template:
 1) Node.js - Express
 2) Node.js - Koa
 3) Python - Flask
 4) Python - Django
 5) Java - Servlet
 6) Java - Spring Boot
 7) PHP - Slim
 8) .NET Core
 9) Go - Echo
 10) React Web App (via create-react-app)
 11) Vue Web App (via @vue/cli)
 => 1
[?] Please select an app:
 1) my-engine-app
 => 1
[INFO] Downloading templates 7.71 KiB / 7.71 KiB [==================] 100.00% 0s
[INFO] Creating project...
[INFO] Created Node.js - Express project in `my-engine-app`
[INFO] Lean how to use Express at https://expressjs.com

lean new 会使用你提供的名字创建一个目录，我们 cd my-engine-app 然后安装项目依赖：

npm install

pip install -Ur requirements.txt

composer install

mvn package

go mod tidy

关联应用和分组

命令行工具的大部分操作都是针对关联的应用进行的，使用 lean switch 可以将已有的项目关联到云端的应用：

lean switch

如应用中有多个分组，则会需要你选择一个分组。

如需关联项目到其他应用，可以重新运行 lean switch。

另外还可以直接执行 lean switch <其他应用的 ID> 来快速切换关联应用。

使用 lean info 可以查看当前项目关联的应用。

本地运行调试

在项目根目录运行：

lean up

即可开始本地调试，命令行工具会在启动你的应用同时启动一个云函数调试控制台。

在浏览器中打开 http://localhost:3000，进入 web 应用的首页。
在浏览器中打开 http://localhost:3001，进入云引擎云函数和 Hook 函数调试控制台。

如果想变更启动端口号，可以使用 lean up --port <新端口号> 命令来指定。

命令行工具并不负责自动重启或热加载，需要由项目代码本身来实现，我们部分的示例项目提供了自动重启的能力（如 Node.js）。

除了使用命令行工具来启动项目之外，还可以原生地启动项目，比如直接使用 node server.js 或者 python wsgi.py。这样能够将云引擎开发流程更好地集成到开发者惯用的工作流程中，也可以直接和 IDE 集成。但是直接使用命令行工具创建的云引擎项目，默认会依赖一些环境变量，因此需要提前设置好这些环境变量。

使用命令 lean env 可以显示出这些环境变量，手动在当前终端中设置好之后，就可以不依赖命令行工具来启动项目了。另外使用兼容 sh shell 的用户，还可以直接使用 eval $(lean env)，自动设置好所有的环境变量。

启动时还可以给启动命令增加自定义参数，在 lean up 命令后增加两个横线 --，所有在横线后的参数会被传递到实际执行的命令中。比如启动 node 项目时，想增加 --inspect 参数给 node 进程，来启动 node 自带的远程调试功能，只要用 lean up -- --inspect 来启动项目即可。

另外还可以使用 --cmd 来指定启动命令，这样即可使用任意自定义命令来执行项目：lean up --cmd=my-custom-command。

有些情况下，我们需要让 IDE 来运行项目，或者需要调试在虚拟机／远程机器上的项目的云函数，这时可以单独运行云函数调试功能，而不在本地运行项目本身：

$ lean debug --remote=http://remote-url-or-ip-address:remote-port --app-id=xxxxxx

更多关于云引擎开发的内容，请参考云引擎服务总览。

部署

从 1.0 开始，lean deploy 必须提供一个参数明确指定部署的目标（如不指定需交互式地选择）：

命令	体验版	标准版
`lean deploy --prod`	部署生产环境	部署生产环境
`lean deploy --staging`	不支持	部署预备环境
`lean publish`	不支持	将预备环境版本发布到生产环境

从本地代码部署

当开发和本地测试云引擎项目通过后，你可以直接将本地源码推送到云引擎平台运行：

lean deploy --prod

这个命令会将本地源码部署到线上的生产环境，覆盖之前的部署（无论是从本地仓库部署、Git 部署还是在线定义）。

部署过程会实时打印进度：

$ lean deploy --prod
[INFO] lean (v1.0.0) running on darwin/arm64
[INFO] Current app: my-engine-app (xxxxxxxxxxxxxxxxxxxxxxxx), group: web, region: cn-n1
[INFO] Deploying new verison to production
[INFO] Node.js runtime detected
[INFO] Uploading file 6.40 KiB / 6.40 KiB [=========================] 100.00% 0s
[REMOTE] 开始构建 20220328-114036
[REMOTE] 正在下载应用代码 ...
[REMOTE] 正在解压缩应用代码 ...
[REMOTE] 运行环境: nodejs
[REMOTE] 正在下载和安装依赖项 ...
[REMOTE] 存储镜像到仓库（0B）...
[REMOTE] 镜像构建完成：20220328-114036
[REMOTE] 开始部署 20181207-115634 到 web1
[REMOTE] 正在创建新实例 ...
[REMOTE] 正在启动新实例 ...
[REMOTE] [Python] 使用 Python 3.7.1, Python SDK 2.1.8
[REMOTE] 实例启动成功：{"version": "2.1.8", "runtime": "cpython-3.7.1"}
[REMOTE] 云函数和 Hook 信息已更新
[REMOTE] 部署完成：1 个实例部署成功

默认部署备注为「从命令行工具构建」，显示在 云服务控制台 > 云引擎 > 管理部署 > 云引擎分组 > 日志 中。你可以通过 -m 选项来自定义部署的备注信息：

lean deploy --prod -m 'fix #42'

部署之后需要绑定一个云引擎自定义域名，然后就可以通过 curl 命令来测试你的云引擎代码，或者通过浏览器访问相应的网址。

点击展开如何在部署时忽略部分文件（.leanignore）

使用预备环境

云引擎向标准版实例的用户提供了一个额外的预备环境，预备环境则提供了和生产环境几乎相同的环境、访问相同的数据，可以绑定单独的域名供开发者进行测试。在开发过程中，你可以先将改动部署到预备环境，使用线上数据测试通过后再发布到生产环境。

部署至预备环境：

lean deploy --staging

将预备环境的版本发布到生产环境：

$ lean publish
[INFO] Current CLI tool version:  0.21.0
[INFO] Retrieving app info ...
[INFO] Deploying AwesomeApp(xxxxxx) to region: cn group: web production
[REMOTE] 开始部署 20181207-115634 到 web1
[REMOTE] 正在创建新实例 ...
[REMOTE] 正在启动新实例 ...
[REMOTE] 实例启动成功：{"version": "2.1.8", "runtime": "cpython-3.7.1"}
[REMOTE] 正在更新云函数信息 ...
[REMOTE] 部署完成：1 个实例部署成功

相比于直接部署生产环境，lean publish 可以保证将完全相同的版本（包括所有依赖和构建产物）发布到生产环境，最大限度避免不一致的情况。

使用预览环境

云引擎可以自动将 Pull request 部署到预览环境，每个预览环境有单独的域名，允许你在接近生产的环境中测试通过后再合并 PR。

预览环境目前只支持在 CI 中使用命令行工具部署。

使用命令 lean preview deploy 来部署预览环境，在 GitLab CI 和 GitHub Actions 中会自动读取 PR 号、分支名等信息，若使用其他 CI 或在本地部署，需要手动指定。

我们提供了 GitLab CI 和 GitHub Actions 的模版：

点击展开 GitLab CI (.gitlab-ci.yml) 模版

点击展开 GitHub Actions 模版

首先在 GitHub 点击 Settings > Secrets and variables > Actions 创建一个 secret，添加你的 ACCESS_TOKEN。

然后在 GitHub 点击 Actions > set up a workflow yourself 创建两个 Workflow 文件，注意修改 env 中的设置：

# .github/workflows/preview-env-deploy.yml

name: Deploy Preview Environment

on:
  pull_request:
    types: [opened, synchronize]

env:
  REGION: MY_REGION # set this to your LeanCloud region, e.g. cn-n1
  APP_ID: MY_APP_ID # set this to your App ID on LeanCloud
  GROUP: MY_GROUP   # set this to your group, e.g. web

jobs:
  deploy-preview-environment:
    runs-on: ubuntu-latest
    environment:
      name: preview/${{ github.head_ref }}
      url: ${{ env.PREVIEW_URL }}
    steps:
      - uses: actions/checkout@v3

      - name: Install lean-cli
        run: |
          sudo curl -L -o /bin/lean https://github.com/leancloud/lean-cli/releases/download/v1.2.3/lean-linux-x64
          sudo chmod +x /bin/lean

      - name: Deploy
        run: |
          lean login --region ${{ env.REGION }} --token ${{ secrets.ACCESS_TOKEN }}
          lean switch --region ${{ env.REGION }} --group ${{ env.GROUP }} ${{ env.APP_ID }}
          PREVIEW_URL=$(lean preview deploy)
          echo "PREVIEW_URL=$PREVIEW_URL" >> $GITHUB_ENV

# .github/workflows/preview-env-delete.yml

name: Delete Preview Environment

on:
  pull_request:
    types: [closed]

env:
  REGION: MY_REGION # set this to your LeanCloud region, e.g. cn-n1
  APP_ID: MY_APP_ID # set this to your App ID on LeanCloud
  GROUP: MY_GROUP   # set this to your group, e.g. web

jobs:
  delete-preview-environment:
    runs-on: ubuntu-latest
    permissions:
      deployments: write
    steps:
      - name: Install lean-cli
        run: |
          sudo curl -L -o /bin/lean https://github.com/leancloud/lean-cli/releases/download/v1.2.3/lean-linux-x64
          sudo chmod +x /bin/lean

      - name: Delete
        run: |
          lean login --region ${{ env.REGION }} --token ${{ secrets.ACCESS_TOKEN }}
          lean switch --region ${{ env.REGION }} --group ${{ env.GROUP }} ${{ env.APP_ID }}
          lean preview delete

      - uses: strumwolf/delete-deployment-environment@v2
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          environment: preview/${{ github.head_ref }}
          onlyDeactivateDeployments: true

触发 Git 部署

如果代码保存在某个 Git 仓库上，例如 GitHub，并且在控制台已经正确设置了 git repo 地址以及 deploy key，你也可以请求云引擎从 Git 仓库获取源码并自动部署。这个操作可以在云引擎的部署菜单里完成，也可以在本地执行：

lean deploy --prod -g

-g 选项要求从 Git 仓库部署，Git 仓库地址必须已经在云引擎菜单中保存。
默认部署使用 master 分支的最新代码，你可以通过 -r <revision> 来指定部署特定的 commit 或者 branch。
设置 git repo 地址以及 deploy key 的方法可以参考云引擎平台功能 § Git 部署。

查看日志

使用 logs 命令可以查询云引擎的最新日志：

$ lean logs
      2019-11-20 17:17:12  Deploying 20191120-171431 to web1
      2019-11-20 17:17:12  Creating new instance ...
      2019-11-20 17:17:22  Starting new instance ...
web1  2019-11-20 17:17:22
web1  2019-11-20 17:17:22  > node-js-getting-started@1.0.0 start /home/leanengine/app
web1  2019-11-20 17:17:22  > node server.js
web1  2019-11-20 17:17:22
web1  2019-11-20 17:17:23  Node app is running on port: 3000
      2019-11-20 17:17:23  Instance started: {"runtime":"nodejs-v12.13.1","version":"3.4.0"}
      2019-11-20 17:17:23  Cloud functions and hooks metadata updated
      2019-11-20 17:17:23  Deploy finished: 1 instances deployed

默认返回最新的 30 条，最新的在最下面。

可以加上 -f 选项来自动滚动更新日志，类似 tail -f 命令的效果：

lean logs -f

新的云引擎日志产生后，都会被自动填充到屏幕下方。

点击展开 lean logs 的更多用法（时间筛选等）

连接到云端的 LeanDB

使用命令行工具 CLI 提供的 lean db shell 可以打开一个连接到云端 LeanDB 的交互式 shell，用于执行查询：

$ lean db shell mysqldb
Welcome to the MySQL monitor.
Your MySQL connection id is 3450564
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql> use test
Database changed
mysql> insert into users set name = 'leancloud';
Query OK, 1 row affected (0.04 sec)
mysql> select * from users;
+------+-----------+
| id   | name      |
+------+-----------+
|    1 | zhenzhen  |
|    2 | leancloud |
+------+-----------+
2 rows in set (0.06 sec)

使用 lean db proxy 可以将云端 LeanDB 导出到本地的一个端口，供本地的程序或图形化的数据库客户端连接：

$ lean db proxy myredis
[INFO] Now, you can connect myredis via [redis-cli -h 127.0.0.1 -a hsdt9wIAuKcTZmpg -p 5678]

保持这个终端运行（不要关闭），就可以在本地的 5678 端口访问到云端的 LeanDB 了。你可以使用本地的 GUI 客户端来浏览操作云端的 LeanDB。在使用 lean up 进行开发测试时，也可以使用这个功能连接到云端的 LeanDB，设置环境变量（来自前面 lean db proxy 的输出）：

export REDIS_URL_myredis=redis://default:hsdt9wIAuKcTZmpg@127.0.0.1:5678

备注

lean db 命令访问云端 LeanDB 实例仅用于本地开发和测试，连接会偶尔断开（部分客户端可以自动重连），请不要用于生产环境。

疑难问题

使用命令行工具部署失败怎么办？

部署失败有多种原因，请根据显示的报错信息耐心排查。一般来说，如果你使用命令行工具部署，首先建议你检查命令行工具是否是最新版，如果不是最新版，请先升级到最新版再重试。

命令行工具在本地调试时提示 `Error: listen EADDRINUSE :::3000`，无法访问应用

listen EADDRINUSE :::3000 表示你的程序默认使用的 3000 端口被其他应用占用了，可以按照下面的方法找到并关闭占用 3000 端口的程序：

也可以修改命令行工具默认使用的 3000 端口：

lean -p 3002

如何通过命令行工具上传文件至文件服务？

$ lean file upload public/index.html
Uploads /Users/dennis/programming/avos/new_app/public/index.html successfully at: http://ac-7104en0u.qiniudn.com/f9e13e69-10a2-1742-5e5a-8e71de75b9fc.html

文件上传成功后会自动生成在云端的 URL，即上例中 successfully at: 之后的信息。

上传 images 目录下的所有文件：

lean file upload images/

同一个项目如何批量部署到多个应用的云引擎？

可以通过 lean switch 切换项目所属应用，然后通过 lean deploy --prod 部署。lean switch 支持通过参数以非交互的方式使用：

lean switch --region <REGION> --group <GROUP_NAME> <APP_ID>
lean deploy --prod

上述命令中，<REGION> 代表应用所在区域，目前支持的值为 cn-n1（华北节点）、cn-e1（华东节点）、us-w1（国际版）。 --prod 表示部署到生产环境，如果希望部署到预备环境，换成 lean deploy --staging 即可。基于这两个命令可以自行编写 CI 脚本快速部署至多个应用的云引擎实例。

如何扩展命令行工具的功能？

有时我们需要对某个应用进行特定并且频繁的操作，比如查看应用 _User 表的记录总数，这样可以使用命令行工具的自定义命令来实现。

只要在当前系统的 PATH 环境变量下，或者在项目目录 .leancloud/bin 下存在一个以 lean- 开头的可执行文件，比如 lean-usercount，那么执行 lean usercount，命令行工具就会自动调用这个可执行文件。与直接执行 lean-usercount 不同的是，这个命令可以获取与应用相关的环境变量，方便访问对应的数据。

例如将如下脚本放到当前系统的 PATH 环境变量中（比如 /usr/local/bin）：

#! /bin/env python

import sys

import leancloud

app_id = os.environ['LEANCLOUD_APP_ID']
master_key = os.environ['LEANCLOUD_APP_MASTER_KEY']

leancloud.init(app_id, master_key=master_key)
print(leancloud.User.query.count())

同时赋予这个脚本可执行权限 $ chmod +x /usr/local/bin/lean-usercount，然后执行 lean usercount，就可以看到当前应用对应的 _User 表中记录总数了。

命令行工具的 1.0 版本有哪些主要的变化？

在 2022 年 3 月我们发布了 1.0.0 版本的命令行工具，并在其中按计划进行了一些不兼容的改动：

lean deploy 必须显式指定部署的目标（`--prod` 或 `--staging`），而之前版本则是体验版默认生产环境，标准版默认预备环境。
lean up 默认不再自动拉取线上的环境变量，如果需要的话可以手动添加 `--fetch-env` 参数。
删除了 lean cache 命令，我们建议使用功能更强大的 lean db 来访问 LeanCache 或 LeanDB。

之前使用 `npm` 装过旧版的命令行工具，如何升级到新版？

如果之前使用 npm 安装过旧版本的命令行工具，为了避免与新版本产生冲突，建议使用 npm uninstall -g avoscloud-code leancloud-cli 卸载旧版本命令行工具。或者直接按照 Homebrew 的提示，执行 brew link --overwrite lean-cli 覆盖掉之前的 lean 命令来解决。

安装​

macOS​

Windows​

Linux​

升级版本​

命令介绍​

登录账号​

初始化项目​

关联应用和分组​

本地运行调试​

部署​

从本地代码部署​

使用预备环境​

使用预览环境​

触发 Git 部署​

查看日志​

连接到云端的 LeanDB​

疑难问题​

使用命令行工具部署失败怎么办？​

命令行工具在本地调试时提示 Error: listen EADDRINUSE :::3000，无法访问应用​

如何通过命令行工具上传文件至文件服务？​

同一个项目如何批量部署到多个应用的云引擎？​

如何扩展命令行工具的功能？​

命令行工具的 1.0 版本有哪些主要的变化？​

之前使用 npm 装过旧版的命令行工具，如何升级到新版？​

安装