编辑文档 更新于

网站托管开发指南 · Node.js

网站托管是云引擎的一个子模块，允许你用 Node.js 开发一个 Web 程序，提供云函数和 Hook，还可以提供静态文件的托管和自定义的路由、绑定你自己的域名。你可以用它为你的移动应用提供一个介绍和下载页、开发一个管理员控制台或完整的网站，或者运行一些必须在服务器端运行的自定义逻辑。

如果你还不知道如何创建云引擎项目，本地调试并部署到云端，可以先阅读一下 云引擎快速入门。其他相关文档包括：

这篇文档以 Node.js 为例，但云引擎还支持其他多种语言，你可以选择自己熟悉的技术栈进行开发：

从示例项目开始

我们为云引擎支持的各种语言准备了示例项目，建议从示例项目着手开始开发。

要理解如何从示例项目开始开发云引擎项目，本地调试，部署到云端，请先阅读 云引擎快速入门。

项目骨架

以示例项目为例，在根目录我们看到有一个 package.json 文件，注意：所有 Node.js 的项目必须包含package.json 才会正确地被云引擎识别为 Node.js 项目。

package.json

Node.js 的 package.json 中可以指定 很多选项，它通常看起来是这样：

{
    "name": "node-js-getting-started",
    "scripts": {
        "start": "node server.js"
    },
    "engines": {
        "node": "8.x"
    },
    "dependencies": {
        "express": "4.12.3",
        "leanengine": "^3.0.2",
        "leancloud-storage": "^3.3.1"
    }
}

其中云引擎会尊重的选项包括：

  • scripts.start 启动项目时使用的命令；默认为 node server.js，如果你希望为 Node.js 附加启动选项（如 --es_staging）或使用其他的文件作为入口点，可以修改该选项。
  • scripts.postinstall 会在项目构建结束时运行一次；可以将构建命令（如 gulp build）写在这里。注意，云引擎默认不会安装 devDependencies。所以如果构建命令需要 devDependencies，请参见下面的配置说明。
  • engines.node 指定所需的 Node.js 版本；出于兼容性考虑默认版本仍为比较旧的 0.12，因此建议大家自行指定一个更高的版本，建议使用 12.x 版本进行开发，你也可以设置为 * 表示总是使用最新版本的 Node.js。
  • dependencies 项目所依赖的包；云引擎会在部署时用 npm install --production 为你安装这里列出的所有依赖。
  • devDependencies 项目开发时所依赖的包；云引擎 不会 安装这里的依赖。 如果需要安装 devDependencies，需要在项目的 leanengine.yaml 中指定 installDevDependencies: true。

建议你参考我们的 项目模板 来编写自己的 package.json。

我们也对 package-lock.json 和 yarn.lock 提供了支持：

  • 如果你的应用目录中含有 package-lock.json，那么会根据 lock 中的描述进行安装（需要 Node.js 8.0 以上）。
  • 如果你的应用目录中含有 yarn.lock，那么会使用 yarn install 代替 npm install 来安装依赖（需要 Node.js 4.8 以上）。
  • 如果你的应用目录中同时包含 package-lock.json 和 yarn.lock，云引擎会使用 yarn install。换言之，yarn.lock 优先。

注意 yarn.lock 中包含了下载依赖的 URL，因此如果你生成 lock 文件时使用了 npmjs.org 的源，那么在 LeanCloud 国内版的部署可能会变慢；反之如果生成时使用了 npm.taobao.org 的源，那么在 LeanCloud 国际版的部署可能会变慢。如果不希望使用 yarn.lock，请将它们加入 .gitignore（Git 部署时）或 .leanengineignore（命令行工具部署时）。

接入 Web 框架

细心的开发者已经发现在示例项目中的 package.json 中引用了一个流行的 Node Web 框架 Express。

Node.js SDK 为 Express 和 Koa 提供了集成支持。

如果你已经有了现成的项目使用的是这两个框架，只需通过下面的方式加载 Node.js SDK 提供的中间件到当前项目中即可：

npm install --save leanengine leancloud-storage

引用和配置的代码如下：

Express

var express = require('express');
var AV = require('leanengine');

AV.init({
  appId: process.env.LEANCLOUD_APP_ID || '{{appid}}',
  appKey: process.env.LEANCLOUD_APP_KEY || '{{appkey}}',
  masterKey: process.env.LEANCLOUD_APP_MASTER_KEY || '{{masterkey}}'
});

var app = express();
app.use(AV.express());
app.listen(process.env.LEANCLOUD_APP_PORT);

其中，AV.express 接受一个可选参数 options，options 是一个对象，目前支持以下两个可选属性：

  • onError：全局错误处理函数，云函数（包括 Hook 函数）抛出异常时会调用该函数。该函数的使用场景包括统一发送错误报告。
  • ignoreInvalidSessionToken：布尔值，为真时忽略客户端发来的错误的 sessionToken（X-LC-session 头），为假时抛出 401 错误 {"code": 211, "error": "Verify sessionToken failed, maybe login expired: ..."}。客户端 SDK 发送请求时会统一发送 X-LC-session 头（其中指定了 sessionToken），sessionToken 可能因种种原因失效，而云函数在很多情况下并不关心 sessionToken。因此，云引擎提供了 ignoreInvalidSessionToken 这个选项，设为真时忽略 sessionToken 错误。反之，如果该选项设为假，客户端收到相应报错时，需要重新登录。

你可以使用 Express 的路由定义功能来提供自定义的 HTTP API：

app.get('/', function (req, res) {
  res.render('index', { title: 'Hello World' });
});

app.get('/time', function (req, res) {
  res.json({
    time: new Date()
  });
});

app.get('/todos', function (req, res) {
  new AV.Query('Todo').find().then(function (todos) {
    res.json(todos);
  }).catch(function (err) {
    res.status(500).json({
      error: err.message
    });
  });
});

更多最佳实践请参考我们的 项目模板 和 云引擎项目示例。

Koa

var koa = require('koa');
var AV = require('leanengine');

AV.init({
  appId: process.env.LEANCLOUD_APP_ID || '{{appid}}',
  appKey: process.env.LEANCLOUD_APP_KEY || '{{appkey}}',
  masterKey: process.env.LEANCLOUD_APP_MASTER_KEY || '{{masterkey}}'
});

var app = koa();
app.use(AV.koa());
app.listen(process.env.LEANCLOUD_APP_PORT);

AV.koa 同样接受可选参数 options，关于 options 对象的具体说明，请参考上节。

你可以使用 Koa 来渲染页面、提供自定义的 HTTP API：

app.use(function* (next) {
  if (this.url === '/todos') {
    return new AV.Query('Todo').find().then(todos => {
      this.body = todos;
    });
  } else {
    yield next;
  }
});

使用 Koa 时建议按照前面 package.json 一节将 Node.js 的版本设置为 4.x 以上。

其他 Web 框架

你也可以使用其他的 Web 框架进行开发，但你需要自行去实现 健康监测 中提到的逻辑。下面是一个使用 Node.js 内建的 http 实现的最简示例，可供参考：

require('http').createServer(function (req, res) {
  if (req.url == '/') {
    res.statusCode = 200;
    res.end();
  } else {
    res.statusCode = 404;
    res.end();
  }
}).listen(process.env.LEANCLOUD_APP_PORT);

你需要将 Web 服务监听在 0.0.0.0 上（Node.js 和 Express 的默认行为）而不是 127.0.0.1。

请参考 在云引擎中使用其他 Node 框架 这篇指南。

路由超时设置

因为 Node.js 的异步调用容易因运行时错误或编码疏忽中断，为了减少在这种情况下对服务器内存的占用，也为了客户端能够更早地收到错误提示，所以需要添加这个设置，一旦发生超时，服务端会返回一个 HTTP 错误码给客户端。

使用 Express 框架实现自定义路由的时候，请求默认的超时时间为 15 秒，该值可以在 app.js 中进行调整：

// 设置默认超时时间
app.use(timeout('15s'));

使用数据存储服务

数据存储服务 是 LeanCloud 提供的结构化数据存储服务，在网站开发中如果遇到需要存储一些持久化数据的时候，可以使用存储服务来保存数据，例如用户的邮箱、头像等。

云引擎中的 Node.js SDK（leanengine）提供了服务器端需要的云函数和 Hook 相关支持，同时需要 JavaScript SDK（leancloud-storage）作为 peer dependency 一同安装，在升级 Node.js SDK 时也请记得升级 JavaScript SDK：

npm install --save leanengine leancloud-storage

Node.js SDK 的 API 文档 和 更新日志 都在 GitHub 上。

// leanengine 和 leancloud-storage 导出的是相同的对象
var AV = require('leanengine');

AV.init({
  appId: process.env.LEANCLOUD_APP_ID || '{{appid}}',
  appKey: process.env.LEANCLOUD_APP_KEY || '{{appkey}}',
  masterKey: process.env.LEANCLOUD_APP_MASTER_KEY || '{{masterkey}}'
});

// 你可以使用 useMasterKey 在云引擎中开启 masterKey 权限，将会跳过 ACL 和其他权限限制

// 使用 JavaScript 的 API 查询云存储中的数据
new AV.Query('Todo').find().then(function (todos) {
  console.log(todos);
}).catch(function (err) {
  console.log(err);
});

如果需要单独在某些操作中关闭全局的 masterKey 权限，请参考 云函数 · Master Key 和超级权限。

Node SDK 的历史版本：

  • 0.x：最初的版本，对 Node.js 4.x 及以上版本兼容不佳，建议用户参考 升级到云引擎 Node.js SDK 1.0 来更新。
  • 1.x：彻底废弃了全局的 currentUser，依赖的 JavaScript 也升级到了 1.x 分支，支持了 Koa 和 Node.js 4.x 及以上版本。
  • 2.x：提供了对 Promise 风格的云函数、Hook 写法的支持，移除了一些被弃用的特性（AV.Cloud.httpRequest），不再支持 Backbone 风格的回调函数。
  • 3.x：推荐使用 的版本，指定 JavaScript SDK 为 peer dependency（允许自定义 JS SDK 的版本），升级 JS SDK 到 3.x。

在示例项目中的 routes/todo.js 中可以看见如下代码：

var router = require('express').Router();
var AV = require('leanengine');

// …

// 新增 Todo 项目
router.post('/', function (req, res, next) {
  var content = req.body.content;
  var todo = new Todo();
  todo.set('content', content);
  todo.save().then(function (todo) {
    res.redirect('/todos');
  }).catch(next);
});

这里演示的就是向数据存储服务存储一个 Todo 对象。更多用法请参考 数据存储开发指南 · JavaScript。

健康监测

你的应用在启动时，云引擎的管理程序会每秒去检查你的应用是否启动成功，如果 30 秒 仍未启动成功，即认为启动失败；在之后应用正常运行的过程中，也会有定期的「健康监测」，以确保你的应用正常运行，如果健康监测失败，云引擎管理程序会自动重启你的应用。

健康检查的 URL 包括你的应用首页（/）和 Node.js SDK 负责处理的 /__engine/1/ping，只要 两者之一 返回了 HTTP 200 的响应，就视作成功。因此请确保你的程序使用了 Node.js SDK，或你的应用 首页能够正常地返回 HTTP 200 响应。除此之外，为了支持云引擎的云函数和 Hook 功能，管理程序会使用 /1.1/functions/_ops/metadatas 这个 URL 和 Node.js SDK 交互，请确保将这个 URL 交给 Node.js SDK 处理，或 返回一个 HTTP 404 表示不使用云函数和 Hook 相关的功能。

关于如何加载 Node.js 数据存储 SDK，见前一小节 使用数据存储服务。

用户状态管理

在服务器端管理

如果你的页面主要是由服务器端渲染（例如使用 EJS、Pug），在前端不需要使用 JavaScript SDK 进行数据操作，那么建议你使用我们提供的一个 CookieSession 中间件，在 Cookie 中维护用户状态：

app.use(AV.Cloud.CookieSession({ secret: 'my secret', maxAge: 3600000, fetchUser: true }));

Koa 需要添加一个 framework: 'koa' 的参数：

app.use(AV.Cloud.CookieSession({ framework: 'koa', secret: 'my secret', maxAge: 3600000, fetchUser: true }));

使用 CookieSession 的同时需要添加 CSRF Token 来防御 CSRF 攻击。

你需要传入一个 secret 用于签名 Cookie（必须提供），这个中间件会将 AV.User 的登录状态信息记录到 Cookie 中，用户下次访问时自动检查用户是否已经登录，如果已经登录，可以通过 req.currentUser 获取当前登录用户。

AV.Cloud.CookieSession 支持的选项包括：

  • fetchUser：是否自动 fetch 当前登录的 AV.User 对象。默认为 false。如果设置为 true，每个 HTTP 请求都将发起一次 LeanCloud API 调用来 fetch 用户对象。如果设置为 false，默认只可以访问 req.currentUser 的 id（_User 表记录的 objectId）和 sessionToken 属性，你可以在需要时再手动 fetch 整个用户。
  • name：Cookie 的名字，默认为 avos.sess。
  • maxAge：Cookie 的过期时间。单位为毫秒。

在 Node SDK 1.x 之后我们不再允许通过 AV.User.current() 获取登录用户的信息（详见 升级到云引擎 Node.js SDK 1.0），而是需要你：

  • 在云引擎方法中，通过 request.currentUser 获取用户信息。
  • 在网站托管中，通过 request.currentUser 获取用户信息。
  • 在后续的方法调用显式传递 user 对象。

你可以这样简单地实现一个具有登录功能的站点：

// 处理登录请求（可能来自登录界面中的表单）
app.post('/login', function (req, res) {
  AV.User.logIn(req.body.username, req.body.password).then(function (user) {
    res.saveCurrentUser(user); // 保存当前用户到 Cookie
    res.redirect('/profile'); // 跳转到个人资料页面
  }, function (error) {
    // 登录失败，跳转到登录页面
    res.redirect('/login');
  });
})

// 查看个人资料
app.get('/profile', function (req, res) {
  // 判断用户是否已经登录
  if (req.currentUser) {
    // 如果已经登录，发送当前登录用户信息
    res.send(req.currentUser);
  } else {
    // 如果没有登录，跳转到登录页面
    res.redirect('/login');
  }
});

// 登出账号
app.get('/logout', function (req, res) {
  req.currentUser.logOut();
  res.clearCurrentUser(); // 从 Cookie 中删除用户
  res.redirect('/profile');
});

在浏览器端维护

如果你的页面主要是由浏览器端渲染（例如使用 Vue、React、Angular），主要在前端使用 JavaScript SDK 进行数据操作，那么建议在前端使用 AV.User.login 登录，以前端的登录状态为准。

当后端需要以当前用户的身份完成某些工作时，前端通过 user.getSessionToken() 获取 sessionToken，然后通过 HTTP Header 等方式将 sessionToken 发送给后端。

例如在前端：

AV.User.login(user, pass).then(user => {
  return fetch('/profile', {
    headers: {
      'X-LC-Session': user.getSessionToken()
    }
  });
});

同时在服务器端：

app.get('/profile', function (req, res) {
  // 根据 sessionToken 查询当前用户
  AV.User.become(req.headers['x-lc-session']).then(user => {
    res.send(user);
  }).catch(err => {
    res.send({ error: err.message });
  });
});

app.post('/todos', function (req, res) {
  var todo = new Todo();
  // 进行数据操作时指定 sessionToken
  todo.save(req.body, { sessionToken: req.headers['x-lc-session'] }).then(() => {
    res.send(todo);
  }).catch(err => {
    res.send({ error: err.message });
  });
});

实现常见的网站功能

发送 HTTP 请求

你可以使用 superagent 等第三方模块来完成 HTTP 请求。

安装 superagent：

npm install superagent --save

代码示例：

const superagent = require('superagent');

// 假定以下网址会返回包含当前日期时间的 JSON 数据
//
//    {"__type":"Date","iso":"2020-12-11T07:58:23.087Z"}

const url = "https://api.example.com/1.1/date";

superagent.get(url)
    .then((resp) => console.log(resp.body.iso))
    .catch(console.error);
// 打印日志：2020-12-11T07:58:23.087Z

获取客户端 IP

如果你想获取客户端的 IP，可以直接从用户请求的 HTTP 头的 x-real-ip 字段获取，示例代码如下：

app.get('/', function (req, res) {
  var ipAddress = req.headers['x-real-ip'] || req.headers['x-forwarded-for'] || req.connection.remoteAddress;
  console.log(ipAddress);
  res.send(ipAddress);
});

注意，国内节点的云引擎应用，如果启用了边缘节点加速功能，那么由于边缘节点的限制，无法获取客户端 IP。

文件上传

托管在 LeanEngine 的网站项目可以直接使用内置的 LeanCloud Node.js SDK 的 API 文件相关的接口直接处理文件的上传。

假设前端 HTML 代码如下：

<form enctype="multipart/form-data" method="post" action="/upload">
  <input type="file" name="iconImage">
  <input type="submit" name="submit" value="submit">
</form>

然后配置应用使用 multiparty 中间件：

var multiparty = require('multiparty');

接下来定义文件上传的处理函数，构建一个 Form 对象，并将 req 作为参数进行解析，会将请求中的文件保存到临时文件目录，并构造 files 对象：

var fs = require('fs');
app.post('/upload', function (req, res) {
  var form = new multiparty.Form();
  form.parse(req, function (err, fields, files) {
    var iconFile = files.iconImage[0];
    if (iconFile.size !== 0) {
      fs.readFile(iconFile.path, function (err, data) {
        if (err) {
          return res.send('读取文件失败。');
        }
        var theFile = new AV.File(iconFile.originalFilename, data);
        theFile.save().then(function (theFile) {
          res.send('上传成功！');
        }).catch(console.error);
      });
    } else {
      res.send('请选择一个文件。');
    }
  });
});

Session

如果你需要将一些属性保存在 session 中，可以增加通用的 cookie-session 组件，详情可以参考 expressjs/cookie-session。该组件和 AV.Cloud.CookieSession 组件可以并存。

Express 框架的 express.session.MemoryStore 在云引擎中是无法正常工作的，因为云引擎是多主机、多进程运行，因此内存型 session 是无法共享的，建议用 expressjs/cookie-session 中间件。

CSRF Token

如果你的云引擎应用使用 Cookie 作为鉴权方式的话（例如使用 SDK 的 CookieSession中间件），那么就有受到 CSRF 攻击的风险，将会允许其他站点伪造带有正确 Cookie 的恶意请求。

业界通常使用 CSRF Token 来防御 CSRF 攻击，你需要传递给客户端一个随机字符串（即 CSRF Token，可通过 Cookie 传递），客户端在每个有副作用的请求中都要将 CSRF 包含在请求正文或 Header 中，服务器端需要校验这个 CSRF Token 是否正确。

Express 中可以使用 csurf 这个库来实现 CSRF Token。

LeanCache

LeanCache 是 LeanCloud 为大流量站点提供的一项缓存服务。

要使用 LeanCache，首先将 redis 依赖添加到 package.json 中：

"dependencies": {
  // …
  "redis": "2.2.x",
  // …
}

然后可以使用下列代码获取 Redis 连接：

var client = require('redis').createClient(process.env['REDIS_URL_<Instance Name>']);
// 建议增加 client 的 on error 事件处理，否则可能因为网络波动或 redis server 主从切换等原因造成短暂不可用导致应用进程退出。
client.on('error', function (err) {
  return console.error('redis err: %s', err);
});

关于 LeanCache 的更多使用方法请看 LeanCache 使用指南。

重定向到 HTTPS

为了安全性，我们可能会为网站加上 HTTPS 加密传输。我们的 LeanEngine 支持网站托管，同样会有这样的需求。因此我们在 LeanEngine 中提供了一个 middleware 来强制网站通过 HTTPS 访问，你只要这样：

Express：

app.enable('trust proxy');
app.use(AV.Cloud.HttpsRedirect());

Koa：

app.proxy = true;
app.use(AV.Cloud.HttpsRedirect({ framework: 'koa' }));

部署并发布到生产环境之后，访问你的 LeanEngine 网站都会强制通过 HTTPS 访问。

部署与发布

命令行部署

在你的项目根目录运行：

lean deploy

使用命令行工具可以非常方便地部署、发布应用，查看应用状态，查看日志，甚至支持多应用部署。具体使用请参考 命令行工具指南。

依赖缓存

云引擎实现了一个缓存机制来加快构建的速度，所谓构建就是指你的应用在云引擎上安装依赖的过程，在每次构建时，如果依赖没有新增或者删减，那么就直接使用上次安装的依赖，只将新的应用代码替换上去。

例如 Node.js 项目连续两次部署，package.json 并没有修改，那么就会直接使用已经缓存的依赖。

依赖缓存也会因为很多原因失效，因此不保证每次构建都可以利用上缓存。

如果你遇到了与依赖安装有关的问题，可以在控制台部署时勾选「下载最新依赖」，或通过命令行工具部署时添加 --no-cache 选项。

lean deploy --no-cache

Git 部署

除此之外，还可以使用 git 仓库部署。你需要将项目提交到一个 git 仓库，我们并不提供源码的版本管理功能，而是借助于 git 这个优秀的分布式版本管理工具。我们推荐你使用 GitHub、Coding 或者 码云 这样第三方的源码托管网站，也可以使用你自己搭建的 git 仓库（比如 GitLab）。

你需要先在这些平台上创建一个项目（如果已有代码，请不需要选择「Initialize this repository with a README」），在网站的个人设置中填写本地机器的 SSH 公钥（以 GitHub 为例，在 Settings > SSH and GPG keys 中点击 New SSH key），然后在项目目录执行：

git remote add origin git@github.com:<username>/<repoName>.git
git push -u origin master

然后到云引擎的设置界面填写你的 Git 仓库地址，如果是公开仓库建议填写 HTTPS 地址，例如 https://github.com/<username>/<repoName>.git。

如果是私有仓库需要填写 SSH 地址（git@github.com:<username>/<repoName>.git），还需要你将云引擎分配给你的公钥填写到第三方托管平台的 Deploy keys 中，以 GitHub 为例，在项目的 Settings > Deploy keys 中点击 Add deploy key。

设置好之后，今后需要部署代码时就可以在云引擎的部署界面直接点击「部署」了，默认会部署 master 分支的代码，你也可以在部署时填写分支、标签或具体的 Commit。 如果仓库使用了 submodule，云引擎也会自动拉取 submodule。

如果希望 push 到项目的 Git 仓库的特定分支后自动触发云引擎部署，可以在应用的 控制台 > 云引擎 > 部署 > git 部署 > 自动部署 查看 deploy token 和 webhook 地址。 控制台显示的 deploy token 可以用来构造 HTTP 请求触发部署。 在控制台填写项目仓库的分支名称，并选择云引擎的运行环境后，控制台会生成相应的 webhook 地址。 该地址收到任意 POST 请求后，会部署指定分支的代码到指定的运行环境。

例如，在 GitHub 代码仓库的 Settings > Webhooks > Payload URL 填写生成的 webhook 后（其他选项均使用默认值，不用修改），下次 push 到项目仓库的 任意 分支，云引擎会自动根据 指定 分支更新代码，重新部署。之所以 push 到任意分支都会触发重新部署，是因为 GitHub 的 webhook 触发事件设置粒度较粗，不能指定仅在 push 到特定分支时触发 webhook。另一方面，云引擎也没有适配具体的托管平台，不会根据 GitHub 提交的 POST 内容中的分支信息决定是否重新部署。 不过，你可以使用 GitHub Action 更精细地控制部署时机，具体可以参考控制台显示的示例。

预备环境和生产环境

默认情况，云引擎只有一个「生产环境」。在生产环境中有一个「体验实例」来运行应用。

当生产环境的体验实例升级到「标准实例」后会有一个额外的「预备环境」。两个环境所访问的都是同样的数据，你可以用预备环境测试你的云引擎代码，每次修改先部署到预备环境，测试通过后再发布到生产环境；如果你希望有一个独立数据源的测试环境，建议单独创建一个应用。

在云引擎托管的网站需要绑定域名才能访问。 以 stg- 开头的域名会自动绑定到预备环境。

如果访问云引擎遇到「Application not Found」的错误，通常是因为对应的环境还没有部署代码。例如应用可能没有预备环境，或应用尚未发布代码到生产环境

有些时候你可能需要知道当前云引擎运行在什么环境（开发环境、预备环境或生产环境），从而做不同的处理：

var NODE_ENV = process.env.NODE_ENV || 'development';
if (NODE_ENV === 'development') {
  // 当前环境为「开发环境」，是由命令行工具启动的
} else if (NODE_ENV === 'production') {
  // 当前环境为「生产环境」，是线上正式运行的环境
} else {
  // 当前环境为「预备环境」
}

NODE_ENV 是系统保留变量，在生产环境下为 'production'，预备环境下为 'staging'，开发者无法自行赋值。

你还可以在 SDK 中指定客户端将请求所发往的环境：

[AVCloud setProductionMode:YES]; // 生产环境（默认）

[AVCloud setProductionMode:NO]; // 预备环境

// 默认为生产环境

// 预备环境
do {
    let environment: LCApplication.Environment = [.cloudEngineDevelopment]
    let configuration = LCApplication.Configuration(environment: environment)
    try LCApplication.default.set(
        id: {{appid}},
        key: {{appkey}},
        // 请将 xxx.example.com 替换为你的应用绑定的自定义 API 域名
        serverURL: "https://xxx.example.com",
        configuration: configuration)
} catch {
    print(error)
}

AV.setProduction(true); // 生产环境（默认）

AV.setProduction(false); // 预备环境

leancloud.use_production(True) # 生产环境（默认）

leancloud.use_production(False) # 预备环境
# 需要在 SDK 初始化语句 `leancloud.init` 之前调用

LeanClient::useProduction(true); // 生产环境（默认）

LeanClient::useProduction(false); // 预备环境

AVCloud.setProductionMode(true); // 生产环境（默认）

AVCloud.setProductionMode(false); // 预备环境

云端环境

系统级依赖

在云引擎的线上环境中，你可以通过 leanengine.yaml 文件的 systemDependencies 部分来自定义系统级依赖：

systemDependencies:
  - imagemagick

目前支持的选项包括：

  • ffmpeg 一个音视频处理工具库。
  • imagemagick 一个图片处理工具库。
  • fonts-wqy 文泉驿点阵宋体、文泉驿微米黑，通常和 phantomjs 或 chrome-headless 配合来显示中文。
  • fonts-noto 思源黑体（体积较大）。
  • phantomjs 一个无 UI 的 WebKit 浏览器（该项目已停止维护）。
  • chrome-headless 一个无 UI 的 Chrome 浏览器（体积很大，会显著增加部署耗时，运行时也会消耗大量 CPU 和内存；如果使用 puppeter 的话，需要给 puppeteer.launch 传递这些参数：{executablePath: '/usr/bin/google-chrome', args: ['--no-sandbox', '--disable-setuid-sandbox']}；暂不支持 Java）。
  • node-canvas 安装 node-canvas 所需要的系统级依赖（你仍需要安装 node-canvas）。
  • python-talib 金融市场数据分析库。

注意添加系统依赖将会拖慢部署速度，因此请不要添加未用到的依赖。

环境变量

云引擎平台默认提供下列环境变量供应用使用：

变量名 说明
LEANCLOUD_APP_ID 当前应用的 App ID。
LEANCLOUD_APP_KEY 当前应用的 App Key。
LEANCLOUD_APP_MASTER_KEY 当前应用的 Master Key。
LEANCLOUD_APP_ENV 当前的应用环境：
  • 开发环境没有该环境变量，或值为 development（一般指本地开发）。
  • 预备环境值为 stage。
  • 生产环境值为 production。
LEANCLOUD_APP_PORT 当前应用开放给外网的端口，只有监听此端口，用户才可以访问到你的服务。
LEANCLOUD_API_SERVER 访问存储服务时使用的地址（类似于 https://api.leancloud.cn）。该值会因为所在数据中心等原因导致不一样，所以使用 REST API 请求存储服务或 LeanCloud 其他服务时请使用此环境变量的值。在云引擎中 不要 直接使用 https://api.leancloud.cn。
LEANCLOUD_APP_GROUP 云引擎实例所在的组。当使用云引擎 组管理 功能时，该值为组的名称。
LEANCLOUD_REGION 云引擎服务所在区域，值为 CN 或 US，分别表示国内版和国际版。
LEANCLOUD_VERSION_TAG 云引擎实例部署的版本号

旧版云引擎使用的以 LC_ 开头的环境变量（如 LC_APP_ID）已经被弃用。为了保证代码兼容性，LC_ 变量在一段时间内依然有效，但未来可能会完全失效。为了避免报错，建议使用 LEANCLOUD_ 变量来替换。

你也可以在 控制台 > 云引擎 > 设置 > 自定义环境变量 页面中添加自定义的环境变量。其中名字必须是字母、数字、下划线且以字母开头，值必须是字符串，修改环境变量后会在下一次部署时生效。

按照一般的实践，可以将一些配置项存储在环境变量中，这样可以在不修改代码的情况下，修改环境变量并重新部署，来改变程序的行为；或者可以将一些第三方服务的 Secret Key 存储在环境变量中，避免这些密钥直接出现在代码中。

// 在云引擎 Node.js 环境中使用自定义的环境变量
var MY_CUSTOM_VARIABLE = process.env.MY_CUSTOM_VARIABLE;
console.log(MY_CUSTOM_VARIABLE);

云引擎运行环境默认提供的环境变量（以及 Node.js 环境变量 NODE_ENV）无法被自定义环境变量覆盖（覆盖无效）。

默认情况下，应用在运行阶段才能够读取到内置环境变量和自定义环境变量。 如果希望在安装依赖或编译阶段就能读取到这些环境变量，需要在 leanengine.yaml 里设置：

exposeEnvironmentsOnBuild: true

负载均衡和边缘节点

在云引擎上，用户的请求会先经过负载均衡组件，然后到达你的应用。 负载均衡组件会处理 HTTPS 加密、对响应进行压缩等一般性工作，因此你不必在你的应用中添加 HTTPS 或 gzip 相关的功能。 也因为 HTTPS 加密是在负载均衡层面处理的，所以通常部署在云引擎上的 web 框架获取的请求 URL 总是使用 HTTP 协议，建议通过 X-Forwarded-Proto HTTP 头来判断原请求是通过 HTTP 还是 HTTPS 访问的。

负载均衡同时限制了请求不能超过 100 MB（包括直接上传文件到云引擎）、请求处理不得超过 60 秒，WebSocket 60 秒无数据会被断开连接。

国内节点未绑定独立 IP 的云引擎默认为纯静态站点优化。请求会先经过边缘节点，再视缓存命中情况回源到负载均衡组件，最后到达你的应用。 边缘节点额外限制了请求不能超过 60 MB、请求处理不得超过 10 秒，另外边缘节点不支持 WebSocket 请求和 HTTP PATCH 方法，也不支持获取客户端 IP。 因此，如果您在国内节点云引擎托管动态网站，我们建议您绑定独立 IP，使用独立入口，不经过边缘节点，自然也就没有上述限制。

文件系统

你可以向 /home/leanengine 或 /tmp 目录写入临时文件，最多不能超过 1 GB。

云引擎每次部署都会产生一个新的容器，即使不部署系统偶尔也会进行一些自动调度，这意味着你 不能将本地文件系统当作持久的存储，只能用作临时存储。

如果你写入的文件体积较大，建议在使用后自动删除他们，否则如果占用磁盘空间超过 1 GB，继续写入文件可能会收到类似 Disk quota exceeded 的错误，这种情况下你可以重新部署一下，这样文件就会被清空了。

日志

在 控制台 > 云引擎 > 日志 中可以查看云引擎的部署和运行日志，还可以通过日志级别进行筛选。

你还可以 通过命令行工具来导出 最近七天的日志到本地文件，方便进行进一步的分析和统计。

应用的日志可以直接输出到「标准输出」或者「标准错误」，这些信息会分别对应日志的 info 和 error 级别，比如下列代码会在 info 级别输出 'Hello!'：

console.log('Hello!'); // info
console.error('An error occurred!'); // error

日志单行最大 4096 个字符，多余部分会被丢弃；日志输出频率大于 600 行/分钟，多余的部分会被丢弃。

你可以通过设置一个 DEBUG=leancloud:request 的环境变量来打印由 LeanCloud SDK 发出的网络请求。在本地调试时你可以通过这样的命令启动程序：

env DEBUG=leancloud:request lean up

当有对 LeanCloud 的调用时，你可以看到类似这样的日志：

leancloud:request request(0) +0ms GET https://API_BASE_URL/1.1/classes/Todo?&where=%7B%7D&order=-createdAt { where: '{}', order: '-createdAt' }
leancloud:request response(0) +220ms 200 {"results":[{"content":"1","createdAt":"2016-08-09T06:18:13.028Z","updatedAt":"2016-08-09T06:18:13.028Z","objectId":"57a975a55bbb5000643fb690"}]}

我们不建议在线上生产环境开启这个日志，否则将会打印大量的日志。如有必要，可以指定 DEBUG=leancloud:request:error，只打印出错的网络请求。

云引擎的访问日志（Access Log）可在 控制台 > 云引擎 > 访问日志 中导出，通过控制台下载经过打包的日志。

时区

在云引擎的中国区系统默认使用北京时间（Asia/Shanghai），美国区默认使用 UTC 时间。

需要注意 JavaScript 中 Date 类型的不同方法，一部分会返回 UTC 时间、一部分会返回当地时间（在中国区是北京时间）：

函数 时区 结果
toISOString UTC 时间 2015-04-09T03:35:09.678Z
toJSON（JSON 序列化时） UTC 时间 2015-04-09T03:35:09.678Z
toUTCString UTC 时间 Thu, 09 Apr 2015 03:35:09 GMT
getHours UTC 时间 3
toString（console.log 打印时） 当地时间 Thu Apr 09 2015 03:35:09 GMT+0000 (UTC)
toLocaleString 当地时间 Thu Apr 09 2015 03:35:09 GMT+0000 (UTC)

同时在构造 Date 对象时也要注意传递给 Date 一个带时区（无论是 UTC 还是本地时区，例如要使用 2011-10-10T14:48:00.000Z 而不是 2011-10-10T14:48:00）的对象，否则 Date 将 不知道以什么样的方式来理解这个时间。

出入口 IP 地址

如果开发者希望在第三方服务平台（如微信开放平台）上配置 IP 白名单而需要获取云引擎的入口或出口 IP 地址，请进入 控制台 > 云引擎 > 设置 > 出入口 IP 来自助查询。

我们会尽可能减少出入口 IP 的变化频率，但 IP 突然变换的可能性仍然存在。因此在遇到与出入口 IP 相关的问题，我们建议先进入控制台来核实一下 IP 列表是否有变化。

备案与自定义域名

根据法律法规和有关部门的要求，使用云引擎网站托管服务需要 绑定自有域名。

{{allComment[version]}} ×
  • 暂无评论
  • {{comment.author}}
    {{ comment.createdAt | date: 'yyyy-MM-dd HH:mm:ss '}}
    {{comment.content}}
您需要 后才能评论