跳到主要内容

云引擎 .NET 运行环境

info

这篇文档是针对 .NET 运行环境的深入介绍,如希望快速地开始使用云引擎,请查看 快速开始部署云引擎应用

所有 .NET 项目都必须在根目录包含一个 app.sln 文件才会被云引擎正确识别,通常一个 .NET 项目的结构如下:

├── web
| ├── StartUp.cs
| ├── Program.cs
| ├── web.csproj
| └── wwwroot
| ├── css
| ├── lib
| └── js
├── app.sln
└── global.json

如果你希望创建一个新的项目,推荐从我们的 .NET 示例项目 开始。

启动命令

在完成构建后,云引擎会通过 dotnet release/web.dll 来启动应用。

.NET 版本

目前云引擎仅提供 .NET 2.1.500 版本。

安装依赖和构建

云引擎会在云端使用 dotnet restore app.sln 来安装依赖;使用 dotnet publish -o release -c Release 来进行构建。

自定义构建过程

除了特定语言默认的构建过程外,云引擎还提供了一种通用的自定义构建过程的能力,这些选项可以在 leanengine.yaml 中设置。

run 覆盖运行命令

leanengine.yaml
run: $(npm bin)/serve -c static.json -l ${LEANCLOUD_APP_PORT}

支持 Shell 语法(如引用环境变量等)。

install 覆盖依赖安装命令

覆盖默认的依赖安装命令(如 npm install),或在安装依赖前后运行自定义命令。

leanengine.yaml
install: npm

多数 runtime 有默认的依赖安装命令,可以用 {use: 'default'} 来引用默认的命令:

leanengine.yaml
install:
- { use: "default" }
- npm run install-additional

依赖安装步骤默认只会将依赖清单(如 package.json 等文件)加入构建目录,如需其他文件可以用 require 来引入:

leanengine.yaml
install:
- require:
- frontend/package.json
- frontend/package-lock.json
- cd frontend && npm ci

build 覆盖构建命令

leanengine.yaml
build: npm run build

在构建阶段全部代码文件都已经被加入了构建目录。

支持用数组来表示多条命令,支持 Shell 语法:

leanengine.yaml
build:
- echo 'building'
- NODE_ENV=production $(npm bin)/webpack

少数 runtime 有默认的构建命令,可以用 {use: 'default'} 来引用默认的命令。

构建日志

默认情况下构建过程中产生的日志不会显示到控制台,只有构建失败时,最后一个步骤的日志才会被显示在控制台上。

如需打印完整的构建日志以便调试,可以在部署时勾选「打印构建日志」或命令行工具添加参数 --options 'printBuildLogs=true'

系统级依赖

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

leanengine.yaml
systemDependencies:
- imagemagick

目前支持的选项包括:

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

注意添加系统依赖将会显著增加部署耗时,因此请不要添加未用到的依赖。

健康检查

云引擎目前主要为 Web 应用优化,应用在启动后需要在环境变量 LEANCLOUD_APP_PORT 中指定的端口上提供 HTTP 服务,注意需要监听在 0.0.0.0 地址(所有接口)上,而不是一些框架默认的 127.0.0.1

在应用部署时,云引擎的管理程序会每隔一秒去检查应用是否启动成功,如果超过启动时间限制(默认 30 秒)仍未启动成功,即认为启动失败,部署会中止。在之后的运行过程中,也会有定期的健康检查来确保应用正常运行,如果健康检查失败,云引擎管理程序会自动重启你的应用。

健康检查会通过 HTTP 检查应用的首页(/),如果返回 HTTP 2xx 的响应,就视作成功。

点击展开健康检查与云引擎 SDK 的关联

云引擎还会尝试检查由 SDK 处理的 /__engine/1/ping,如果 SDK 接入正确,便不再要求首页(/)返回 HTTP 2xx。

如果 云服务控制台 > 云引擎 > 你的分组 > 设置 > 云函数模式 设置为「开启」或 leanengine.yamlfunctionsMode 设置为 strict,云引擎会检查 SDK 是否被正确地接入,否则会视作启动失败。

点击展开自定义启动时长(startupTimeout

启动时间限制默认为 30 秒,可设置范围为 15–120 秒,如需延长或缩短,可以在 leanengine.yaml 文件中设置:

leanengine.yaml
startupTimeout: 60

云端环境

绑定自定义域名

云引擎需要设置域名才能访问。在 云服务控制台 > 云引擎 > 你的分组 > 设置 > 访问域名 处可以绑定域名。

如果你绑定的域名以 stg- 开头(如 stg-api.example.com),会自动关联到预备环境。

负载均衡和加速节点

所有对云引擎的 HTTP 或 HTTPS 请求都会经过负载均衡,负载均衡组件会处理 HTTPS 加密、重定向到 HTTPS、对响应进行压缩等一般性工作,因此云引擎上的程序不需要自己实现这些功能。同时负载均衡带来的一些限制,在云引擎程序内进行修改也无法越过,如:

  • /.well-known/acme-challenge/ 开头的路径被用于自动管理证书,不会转发到云引擎程序。
  • 请求头(URL 和 header)每行最大 8K,总计最大 64K。
  • 请求体积(上传文件体积)最大 100M。
  • 连接或等待响应的超时时间为 60 秒。

获取客户端 IP 等信息

云引擎的负载均衡会在 HTTP header 中传递一些有关原始请求的信息:

  • X-Real-IP: 请求的来源 IP。
  • X-Forwarded-Proto: 请求的来源协议(httphttps)。
  • Forwarded: RFC 7239 规定的用于传递代理信息的头,包含 IP 和 协议。
caution

在使用加速节点的情况下,以上的 HTTP header 中给出的实际上是加速节点的信息,而非原始请求信息。

在使用加速节点的情况下,还会有这些 HTTP header:

  • X-Forwarded-For: 逗号隔开的多个 IP,其中第一个是原始请求 IP。
caution

以上 HTTP 头中给出的信息并不可靠,云引擎无法确认其真实性,存在被伪造的可能。

info

中国大陆节点的云引擎应用会默认启用加速节点,如果确实需要准确的原始请求 IP,可以开通独立 IP 来绕过加速节点,更多关于加速节点与独立 IP 的区别见 域名绑定指南 § 云引擎域名

重定向到 HTTPS

在绑定云引擎自定义域名时,可以选择「强制 HTTPS」,勾选后负载均衡组件会将 HTTP 的请求重定向到 HTTPS 的同一路径。

caution

在使用加速节点的情况下,「强制 HTTPS」选项无法正确工作,仍需 在项目代码层面实现重定向

加速节点缓存

如果你将自定义域名解析到加速节点(也包括云引擎的共享域名),那么加速节点会对请求进行缓存,加速节点会有一些默认的缓存规则。

默认会缓存的情况:

  • 响应头中有 Last-Modified(通常是静态资源,其中 HTML 最多缓存 60 秒)。

不会缓存的情况:

  • 出错的响应(非 2xx)。
  • 非幂等请求(如 POST)。
  • 响应头中没有 Last-Modified(通常是动态接口)。

默认的缓存时长取决于文件类型和 Last-Modified(越不常修改的文件缓存越久),你可以通过自行设置 Cache-Control 来覆盖默认的行为,边缘节点会尽可能遵守其中的要求,比如:

  • 设置 Cache-Control: no-cache 来避免响应被缓存。
  • 设置 Cache-Control: max-age=3600 来设置缓存时长(一小时)。
info

如果希望完全避免被缓存机制影响,可以开通独立 IP 来绕过加速节点,更多关于加速节点与独立 IP 的区别见 域名绑定指南 § 云引擎域名

环境变量

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

变量名说明
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访问存储服务时使用的地址。该值会因为所在数据中心等原因导致不一样,所以使用 REST API 请求存储服务或其他云服务时请使用此环境变量的值。
LEANCLOUD_APP_GROUP云引擎实例所在的组。当使用云引擎组管理功能时,该值为组的名称。
LEANCLOUD_REGION云引擎服务所在区域,值为 CNUS,分别表示国内版和国际版。
LEANCLOUD_VERSION_TAG云引擎实例部署的版本号。

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

日志

note

关于如何在控制台上查看日志,以及访问日志等更多内容,请看 云引擎平台功能 § 查看日志

云引擎会收集应用打印到标准输出(stdout)和标准错误输出(stderr)的日志:

note

日志单行最大 4096 个字符,多余部分会被丢弃;日志收集速率最大 600 行每分钟,多余的部分会也被丢弃。

时区

云引擎使用北京时间(东八区)。

文件系统

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

caution

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

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

出入口 IP 地址

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

info

中国大陆节点的云引擎应用会默认启用加速节点,取决于底层的供应商,入口 IP 将会非常频繁地变动。如果确实需要固定入口 IP,可以开通独立 IP。

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

如需保持入口 IP 不变,建议为云引擎绑定独立 IP。