instructure/canvas-rce-api

Canvas RCE API

Canvas RCE API是一个代理服务，负责转发Canvas富文本编辑器和侧边栏所需的所有API请求。请求通过Canvas生成的JWT进行认证。未来，运行Canvas RCE API服务将是Canvas富文本编辑器完整功能的必要条件。

生产环境运行

Canvas RCE API是Node.js应用，可通过Node.js直接运行或在Docker容器中运行。无论哪种方式，均需通过环境变量正确配置应用，并在应用前部署Web服务器或负载均衡器以终止TLS连接，应用本身不直接处理https请求。

Node.js

应用可通过Node.js直接运行，执行npm start或node app.js即可。设计支持当前Node.js LTS（16.x）版本。运行前需执行npm install --production安装所有生产依赖。

Node.js进程仅运行在单个线程。为充分利用应用服务器的多CPU核心，建议使用Passenger或PM2等工具管理和平衡Node进程负载。

Docker

Docker镜像可在Docker Hub（instructure/canvas-rce-api:latest）或Starlord（starlord.inscloudgate.net/jenkins/canvas-rce-api:latest）获取。容器通过Nginx与Passenger运行应用，监听80端口。Nginx和Passenger的配置环境变量可参考https://github.com/instructure/dockerfiles/blob/master/node-passenger/README.md。

示例

bash
docker run \
  -e ECOSYSTEM_KEY \
  -e ECOSYSTEM_SECRET \
  -e FLICKR_API_KEY \
  -e YOUTUBE_API_KEY \
  -e STATSD_PORT=8125 \
  -e STATSD_HOST=127.0.0.1 \
  instructure/canvas-rce-api

TLS

为确保传输中凭证和 payload 的加密，应使用https。应用不直接支持https请求，需在前端部署TLS终止代理，可通过负载均衡器（如HAProxy或Amazon ELB/ALB）实现，也可在单服务器环境中使用同一服务器上的Apache或nginx。

配置

配置选项通过以下环境变量设置：

• ECOSYSTEM_KEY: 必填 与Canvas共享的加密密钥。
• ECOSYSTEM_SECRET: 必填 与Canvas共享的签名密钥。
• FLICKR_API_KEY: 支持Flickr图片搜索的必填项。
• YOUTUBE_API_KEY: 查询***嵌入内容标题的必填项。
• NODE_ENV: 生产环境必须设置为production。
• PORT: 默认3000。Docker运行时无效，因Node Passenger会通过猴子补丁控制Node进程监听端口。
• STATSD_HOST: 如需使用statsd收集指标，设为statsd服务器主机。
• STATSD_PORT: 如需使用statsd收集指标，设为statsd服务器端口。

Canvas配置

Canvas需配置与JWT加密和签名相同的密钥。若使用Consul管理动态设置，密钥和主机应添加至dynamic_settings.yml示例中的对应路径；也可直接使用dynamic_settings.yml文件替代Consul配置。

dynamic_settings.yml示例

yml
production:
  config:
    canvas:
      canvas:
        encryption-secret: "实际32字节长度的字符串"
        signing-secret: "实际32字节长度的字符串"
      rich-content-service:
        app-host: "canvas-rce-api-host"

开发指南

依赖

开发canvas-rce-api仅需Node.js最新LTS版本（16.x），其他依赖通过npm安装。若不想在本地安装Node.js，可使用附带的docker-compose文件通过Docker运行。

配置

复制示例.env文件，该文件中定义的环境变量将在应用运行时生效。Canvas本地测试环境配置参考前文。

bash
cp .env.example .env

同时，复制docker-compose.override.yml.dev文件：

bash
cp docker-compose.override.yml.dev docker-compose.override.yml

启动服务

bash
npm install
npm run start:dev # 代码变更时自动重启应用

或本地构建Docker镜像：

bash
docker-compose build
docker-compose up

Docker环境要求Canvas将app-host设为rce.docker，而非本地主机地址。

代码格式化

项目使用prettier自动格式化代码。代码将通过pre-commit钩子自动格式化，建议配置编辑器在保存时自动格式化。

代码检查

项目使用eslint检测非样式代码问题。检查错误会导致构建失败，建议配置编辑器显示eslint错误。

测试

所有测试位于顶级test目录，文件命名格式为*.test.js。测试基于mocha和标准assert包编写。可使用Sinon stub依赖，但优先通过依赖注入而非stub共享绑定。

运行所有测试：

bash
yarn test

运行单个测试文件示例：

bash
yarn test:one test/service/api/folders.test.js

发布流程

目前NPM发布为手动流程。

Jenkins的合并后任务会自动将:latest Docker镜像发布至Docker Hub和内部仓库Starlord。

准备发布时，需为发布提交打标签，遵循语义化版本规范（如v1.2.3）：

bash
git tag "v1.2.3"
git push --tags origin

重要：git标签必须包含v前缀，否则合并后Jenkins任务不会发布版本特定的Docker镜像。

许可证

本项目基于MIT许可证发布。