跳到主要内容
版本：v3

命令行工具 CLI 使用指南

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

安装​

macOS​

推荐通过 Homebrew 安装：

brew update && brew install lean-cli
点击展开 Homebrew 安装常见问题

如访问 Homebrew 网络不畅，可以 设置 http_proxy 等环境变量来加速访问，或为 Homebrew 配置镜像源（如 TUNA）。

如不希望通过 Homebrew 安装，可以在 GitHub releases 页面 下载二进制文件 tds-macos-arm64（Apple Silicon）或 tds-macos-x64（Intel），重命名为 tds 后移动到 $PATH 下的路径，并添加可执行权限（chmod a+x /path/to/tds）。

Windows​

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

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

Linux​

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

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

升级版本​

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

命令介绍​

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

点击展开 tds help 的输出
NAME:
   tds - Command line tool to manage and deploy Cloud Engine apps

USAGE:
   tds [global options] command [command options] [arguments...]

VERSION:
   1.0.0

COMMANDS:
     login    Log in to TapTap Developer Services
     switch   Change the associated Cloud Engine app
     info     Show information about the associated user and app
     up       Start a development instance locally with debug console
     new      Create a new Cloud Engine project from official examples
     deploy   Deploy the project to Cloud Engine
     publish  Publish the version of staging to production
     db       Access to to Database instances
     file     Manage files ('_File' class in Data Storage)
     logs     Show Cloud Engine logs
     debug    Start the debug console without running the project
     env      Print custom environment variables on Cloud Engine (secret variables not included)
     cql      Enter CQL interactive shell (warn: CQL is deprecated)
     help     Show usages of all subcommands

GLOBAL OPTIONS:
   --version, -v  print the version

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

$ tds --version
tds version 1.0.0

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

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

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

点击展开 tds deploy --help 的输出
NAME:
   tds deploy - Deploy the project to Cloud Engine

USAGE:
   tds deploy [command options] (--prod | --staging) [--no-cache --build-logs --overwrite-functions]

OPTIONS:
   --prod                              Deploy to production environment
   --staging                           Deploy to staging environment
   --build-logs                        Print build logs
   -g                                  Deploy from git repo
   --war                               Deploy .war file for Java project. The first .war file in target/ is used by default
   --no-cache                          Disable buliding cache
   --overwrite-functions               Overwrite cloud functions with the same name in other groups
   --leanignore value                  Rule file for ignored files in deployment (default: ".leanignore")
   --message value, -m value           Comment for this version, only applicable when deploying from local files
   --keep-deploy-file
   --revision value, -r value          Git revision or branch. Only applicable when deploying from Git (default: "master")
   --options --options build-root=app  Send additional deploy options to server, in urlencode format(like --options build-root=app)
   --direct                            Upload project's tarball to remote directly

登录账号​

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

请进入开发者后台，点击左侧「创建游戏」按照需要填写基础信息和基础游戏资料，然后进入对应的游戏，依次进入游戏服务 > 云服务 > 云引擎 > 开启 > 部署项目 > 命令行工具部署，按照指引登录你的云服务账号。

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

初始化项目​

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

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

$ tds 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

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

npm install

关联应用和分组​

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

tds switch

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

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

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

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

本地运行调试​

在项目根目录运行：

tds up

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

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

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

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

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

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

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

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

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

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

部署​

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

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

从本地代码部署​

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

tds deploy --prod

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

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

$ tds 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 选项来自定义部署的备注信息：

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

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

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

部署项目时，如果有一些临时文件或是项目源码管理软件用到的文件，不需要上传到服务器，可以将它们加入到 .leanignore 文件。

.leanignore 文件格式与 Git 使用的 .gitignore 格式基本相同（严格地说，.leanignore 支持的语法为 .gitignore 的子集），每行写一个忽略项，可以是文件或者文件夹。如果项目没有 .leanignore 文件，部署时会根据当前项目所使用的语言创建一个默认的 .leanignore 文件。请确认此文件中的 默认配置 是否与项目需求相符。

使用预备环境​

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

部署至预备环境：

tds deploy --staging

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

$ tds 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 个实例部署成功

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

使用预览环境​

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

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

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

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

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

首先在 GitLab 点击 Settings > CI/CD > Variables > Add variable 添加你的 ACCESS_TOKEN，注意勾选 “Mask variable” 避免出现在日志中。

然后在 GitLab 左侧点击 CI/CD > Editor 新建一个 .gitlab-ci.yml 文件并添加以下内容。注意修改 variables 中的设置。

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

before_script:
  - apt-get update && apt-get install -y curl
  - curl -L -o /bin/tds https://github.com/leancloud/lean-cli/releases/download/v1.2.3/tds-linux-x64
  - chmod +x /bin/tds
  - tds login --region $REGION --token $ACCESS_TOKEN
  - tds switch --region $REGION --group $GROUP $APP_ID

deploy_preview:
  stage: deploy
  script:
    - PREVIEW_URL=$(tds preview deploy)
    - echo "PREVIEW_URL=$PREVIEW_URL" >> deploy.env
  artifacts:
    reports:
      dotenv: deploy.env   
  environment:
    name: preview/$CI_COMMIT_REF_NAME
    url: $PREVIEW_URL
    on_stop: delete_preview
    auto_stop_in: 1 week
  only:
    - merge_request

delete_preview:
  stage: deploy
  script: tds preview delete
  environment:
    name: preview/$CI_COMMIT_REF_NAME
    action: stop
  rules:
    - if: $CI_MERGE_REQUEST_ID
      when: manual
点击展开 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 TDS region, e.g. cn-tds1
  APP_ID: MY_APP_ID # set this to your App ID on TDS
  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/tds https://github.com/leancloud/lean-cli/releases/download/v1.2.3/tds-linux-x64
          sudo chmod +x /bin/tds

      - name: Deploy
        run: |
          tds login --region ${{ env.REGION }} --token ${{ secrets.ACCESS_TOKEN }}
          tds switch --region ${{ env.REGION }} --group ${{ env.GROUP }} ${{ env.APP_ID }}
          PREVIEW_URL=$(tds 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 TDS region, e.g. cn-tds1
  APP_ID: MY_APP_ID # set this to your App ID on TDS
  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/tds https://github.com/leancloud/lean-cli/releases/download/v1.2.3/tds-linux-x64
          sudo chmod +x /bin/tds

      - name: Delete
        run: |
          tds login --region ${{ env.REGION }} --token ${{ secrets.ACCESS_TOKEN }}
          tds switch --region ${{ env.REGION }} --group ${{ env.GROUP }} ${{ env.APP_ID }}
          tds 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 仓库获取源码并自动部署。这个操作可以在云引擎的部署菜单里完成，也可以在本地执行：

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

查看日志​

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

$ tds 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 命令的效果：

tds logs -f

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

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

可以通过 -l 选项设定返回的日志数目，例如返回最近的 100 条：

tds logs -l 100

如果想查询某一段时间的日志，可以指定 --from 和 --to 参数：

tds logs --from=2017-07-01 --to=2017-07-07

单独使用 --from 参数导出从某一天到现在的日志：

tds logs --from=2017-07-01

另外可以配合重定向功能，将一段时间内的 JSON 格式日志导出到文件，再配合本地工具进行查看：

tds logs --from=2017-07-01 --to=2017-07-07 --format=json > leanengine.logs

--from、--to 的时区为本地时区（运行 tds 命令行工具的机器的本地时区）。

连接到云端的 LeanDB​

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

$ tds 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)

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

$ tds 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。在使用 tds up 进行开发测试时，也可以使用这个功能连接到云端的 LeanDB，设置环境变量（来自前面 tds db proxy 的输出）：

export REDIS_URL_myredis=redis://default:hsdt9wIAuKcTZmpg@127.0.0.1:5678
备注
tds db 命令访问云端 LeanDB 实例仅用于本地开发和测试，连接会偶尔断开（部分客户端可以自动重连），请不要用于生产环境。

疑难问题​

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

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

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

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

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

tds -p 3002

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

$ tds 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 目录下的所有文件：

tds file upload images/

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

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

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

上述命令中，<REGION> 代表应用所在区域。 --prod 表示部署到生产环境，如果希望部署到预备环境，换成 tds deploy --staging 即可。 基于这两个命令可以自行编写 CI 脚本快速部署至多个应用的云引擎实例。

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

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

只要在当前系统的 PATH 环境变量下，或者在项目目录 .leancloud/bin 下存在一个以 lean- 开头的可执行文件，比如 lean-usercount，那么执行 tds 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，然后执行 tds usercount，就可以看到当前应用对应的 _User 表中记录总数了。

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

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

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

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

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