Quick Start (Chinese Version)

Translator: Tianle Yu Contact: tianleyu[at]ucsb.edu
部分内容由Github Copilot协助翻译，可能存在不准确的地方。
根据个人经验添加了部分注释，如有错误请指正。\

本文意在帮助大家在本地快速搭建 Canvas LMS 的开发环境。这个环境缺少一些功能（例如邮件不会发送、延迟任务不会被守护、没有提供合适的应用服务器、没有安装消息总线集成）并且不适合生产使用。

请参阅Production Start指南，以获搭建生产环境系统。

如果你在安装或排疑的过程中需要帮助，最好的方法是加入社区邮件列表或 IRC 频道（请参阅Home页面），并在那里提出具体问题。很可能有其他人已经解决了相同的问题。常见的问题类别是那些由于遵循本指南而不是Production Start指南而产生的问题。如果你确定要继续使用快速入门指南，请继续阅读。

配置

自动配置

如果你使用的系统是 macOS 或 Ubuntu，你可以克隆仓库并运行 docker_dev_setup.sh 脚本，以自动配置一个带有 Docker 的开发环境。建议你至少有 150GB 的硬盘空间、8GB 的内存和四核 CPU 来使用这个脚本。

./script/docker_dev_setup.sh

对于某些系统，你可能需要先运行以下命令：

export DOCKER_BUILDKIT=0
export COMPOSE_DOCKER_CLI_BUILD=0

但是如果问题不是因为 Docker 文件权限问题而导致的，请不要运行这些命令。

doc/docker 目录包含了更详细的关于使用 Docker 进行 Canvas 开发的信息。

手动配置

本教程针对 macOS 和 Linux 等基于 POSIX 的系统。本教程是在 Ubuntu LTS 20.04 Focal 和 macOS 13 Ventura 上编写和测试的。如果你使用的是其他系统，请考虑在运行 Ubuntu 20.04 LTS 的服务器或虚拟机上设置环境。我们将假设你已经这样做了，或者对这些工作部分足够熟悉，可以自行解决。

获取源码

有两种获取Canvas源码的主要方法：git 或 zip/tar 下载。

使用 Git

如果你还没有安装 Git，你可以在 Debian/Ubuntu 上运行以下命令来安装：

sudo apt-get install git

当你的系统上安装了 Git 后，获取 Canvas 的最新源码就像从仓库中check out代码一样简单，如下所示：

mkdir ~/exempt; cd ~/exempt # 因为病毒扫描器配置为忽略这个目录，这样可以提高速度
git clone https://github.com/instructure/canvas-lms.git canvas
cd canvas
git checkout prod

下载Zip/Tar

你也可以下载一个 tarball 或 zip 文件来获取 Canvas 源码。

应用根目录

无论你将代码checkout到哪里，我们都将称之为你的应用根目录。应用根目录是包含 app、config 和 script 等文件夹的文件夹。在本教程中，我们将假设你的应用根目录是 /home/user/canvas。

GitHub Codespaces 设置

如果你在使用 GitHub Codespaces beta, 你可以创建一个 Codespaces，它会自动为你运行 Canvas，而无需在你的计算机上安装任何东西，这对于你无法手动设置的情况非常有用。首先，你需要 fork 这个仓库以便你可以创建一个 Codespaces。完成后，按下仓库上的 "code" 按钮，选择 "Open with Codespaces"，然后创建一个新的 Codespaces。GitHub 将开始为你构建 Codespaces。在第一次运行时，这可能需要一分钟。

Codespaces 创建完成之后，你需要安装依赖项以开始安装 Canvas。这可以通过运行以下命令来完成：

sudo apt-get update
sudo apt-get -y install postgresql-14 zlib1g-dev libldap2-dev libidn11-dev libxml2-dev libsqlite3-dev libpq-dev libyaml-dev libxmlsec1-dev curl build-essential

注意：Codespaces 可能默认使用 Node 17+。你可以运行 nvm install 来使用所需版本的 node 和 npm，以便 compile_assets 脚本能顺利完成而不报错。

完成之后，然后运行以下命令（如果你想，你可以直接将它们粘贴到集成终端中）：

rvm install "ruby-3.1.0"
rvm use 3.1.0
gem install bundler:2.4.19
gem install nokogumbo scrypt sanitize ruby-debug-ide
sudo chown -R codespace:codespace /workspaces/canvas-lms/
sudo chown -R codespace:codespace /usr/local/rvm/rubies/ruby-3.1.0/lib/ruby/gems/3.1.0
bundle _2.4.19_ install
yarn install --pure-lockfile
for config in amazon_s3 delayed_jobs domain file_store outgoing_mail security external_migration dynamic_settings database; \
          do cp -v config/$config.yml.example config/$config.yml; done
sudo chown -R codespace:codespace /usr/local/rvm/rubies/ruby-3.1.0/lib/ruby/gems/3.1.0
bundle _2.4.19_ update
sudo chown -R codespace:codespace /var/run/postgresql/
export PGHOST=localhost
/usr/lib/postgresql/14/bin/initdb ~/postgresql-data/ -E utf8
/usr/lib/postgresql/14/bin/pg_ctl -D ~/postgresql-data/ -l ~/postgresql-data/server.log start
/usr/lib/postgresql/14/bin/createdb canvas_development
bundle exec rails canvas:compile_assets
bundle exec rails db:initial_setup

注意：

如果资源编译失败，你可能遇到了内存限制，此时你可能需要切换到更大的机器类型。
当这些命令完成后，最后一个命令（bundle exec rails db:initial_setup）需要用户输入来设置管理员用户的登录凭据。如果没有提示出现，请确保在设置过程中没有发生错误，导致依赖项或 gem 未安装。

当你完成这些操作后，如果你是通过浏览器使用 Codespaces 而不是通过 VS Code，你需要进行一些小的配置更改。在 GitHub Codespaces 中，转到终端选项卡旁边的“端口”选项卡，并复制自动转发端口的主机（应该看起来像 https://7af34f90-...）。然后，转到 Codespaces 编辑器中的 config/domain.yml。将 development 部分修改为以下内容：

development:
  # Replace this with the domain your GitHub Codespace is accessible at.
  domain: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa-3000.apps.codespaces.githubusercontent.com"

确保它不以 https:// 开头或以 / 结尾。**确保将 5432 替换为 3000。**这指定了你用于 Web 服务器的端口。

接着，保存你对文件的更改并运行 bundle exec rails server 来启动你的 Canvas 实例。如果一切正常，你应该看到 * Listening on http://127.0.0.1:3000 并且可以通过点击“端口”选项卡并点击带有“3000”的端口上的地球图标在浏览器中访问你的实例。你应该可以使用你在脚本中创建的凭据登录并访问所有内容。

实例使用完毕后（避免数据损坏很重要）

Codespaces 会在 30 分钟后自动过期，有时会关闭，这可能会导致数据库在关闭时仍在运行，从而导致数据库损坏。当你准备结束时，请使用以下命令关闭数据库：

export PGHOST=localhost
/usr/lib/postgresql/14/bin/pg_ctl stop -D ~/postgresql-data/

接着，点击左下角的设置图标 > 命令面板，然后输入 "Codespaces: Suspend Current Codespace"。这将结束你的会话并允许你安全地退出。

重新启动实例

你可以使用以下命令重新启动你的 Codespaces 实例：

export PGHOST=localhost
/usr/lib/postgresql/14/bin/pg_ctl start -D ~/postgresql-data/
bundle exec rails server

这应该会重新启动你的Canvas实例，前提是你登陆了 GitHub。你的实例现在已经准备好用于开发和测试！你可能想查看本指南的所有其他部分，里面包含了实用的信息，细致讲解了某些可能需要额外设置的资源。

环境依赖

Canvas 当前需要 Ruby 3.1。不支持 Ruby 3.2+。（译者注：此信息不准确，本人使用3.1时遇到了Gemfile报错，Gemfile要求的最低版本是3.3.1）

外部依赖

Debian/Ubuntu

首先，我们需要安装 Canvas 需要的 Ruby 库和包。在 Debian/Ubuntu 上，你需要安装一些包。根据当前所需的 Ruby 版本以及你的 Debian/Ubuntu 版本是否提供，可能需要额外的步骤来安装 Ruby（例如使用 rbenv 等 Ruby 环境管理器）。

你可以使用我们的 PPA 来安装 Ruby：（译者注：这个 PPA 无法使用，本人使用的是 rvm 安装的 ruby）

sudo apt-get install software-properties-common
sudo add-apt-repository ppa:instructure/ruby
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get install ruby3.1 ruby3.1-dev zlib1g-dev libxml2-dev \
                     libsqlite3-dev postgresql-14 libpq-dev \
                     libxmlsec1-dev libyaml-dev curl build-essential

Node.js 安装:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
NODE_MAJOR=18
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
sudo apt-get update
sudo apt-get install nodejs -y

Yarn 安装:

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt-get update && sudo apt-get install yarn=1.19.1-1

安装完Postgres之后，你需要把你的系统用户名设置成超级用户。你可以通过运行以下命令来完成：

sudo -u postgres createuser $USER
sudo -u postgres psql -c "alter user $USER with superuser" postgres

macOS

对于 macOS，你需要安装 Xcode 的命令行工具，并确保你的 Ruby 版本是 3.1。你可以通过运行以下命令来查看你的 Mac 自带的 Ruby 版本：（译者注：如果你使用了 rvm 或 rbenv 等 Ruby 环境管理器，你可以忽略这一步，本人使用3.1时遇到了Gemfile报错，Gemfile要求的最低版本是3.3.1）

ruby -v

你还需要安装Postgres和xmlsec library。最简单的方法是通过homebrew安装。安装好 homebrew 后，只需运行：

brew install postgresql@14 node@16 xmlsec1 libyaml
npm install -g npm@latest

Ruby Gems

大部分 Canvas 的依赖是 Ruby Gems。Ruby Gems 是 Ruby 特有的包管理系统，与操作系统的包管理系统正交运行（互不干扰）。

Ruby Bundler

Canvas 使用 Bundler 作为 Ruby Gems 的一个额外层来管理版本化的依赖。Bundler 是很棒的！

你可以使用 Ruby Gems 安装 Bundler：

sudo gem install bundler

Canvas 依赖

在你安装 Bundler之后，请导航到 Canvas 应用的根目录，你可以使用 Bundler 安装所有 Canvas 依赖。

cd canvas
bundle install
yarn install --pure-lockfile
# Sometimes you have to run this command twice if there is an error
yarn install --pure-lockfile

已知问题：

unicode gem

如果你在 macOS 上安装 unicode gem 时遇到错误，请使用以下命令安装（参见 https://github.com/blackwinter/unicode/pull/11）：

gem install unicode -- --with-cflags="-Wno-incompatible-function-pointer-types"

thrift gem

如果你在 macOS Mavericks 或 macOS Yosemite 上遇到 thrift gem 错误，请设置以下 bundler 参数，然后再次运行 bundle install（参见 https://issues.apache.org/jira/browse/THRIFT-2219）：

bundle config build.thrift --with-cppflags='-D_FORTIFY_SOURCE=0'

如果你在 El Capitan 上遇到 thrift gem 错误，错误信息类似于以下内容：

compact_protocol.c:431:41: error: shifting a negative signed value is undefined [-Werror,-Wshift-negative-value]

请使用以下命令安装 gem，然后继续运行 bundle install。

gem install thrift -v 0.8.0 -- --with-cppflags=\"-D_FORTIFY_SOURCE=0 -Wno-shift-negative-value\"

这个问题出自于 El Capitan 中的 clang 更新，一些参数现在会导致旧版本的 thrift 在安装时出现问题。

如果你在运行 bundle install 时遇到如下错误:

An error occurred while installing thrift (0.9.3.0), and Bundler cannot continue.
Make sure that `gem install thrift -v '0.9.3.0' --source 'https://rubygems.org/'` succeeds before bundling.

使用以下指令分开安装 thrift gem 然后重新运行 bundle install:

gem install thrift -v '0.9.3.0' -- --with-cppflags="-Wno-compound-token-split-by-macro"

然后如果 bundle install 在查找 idn 库时失败，请运行 brew install libidn

eventmachine gem

如果你在安装 eventmachine gem 时遇到错误，请设置以下 bundler 参数，然后再次运行 bundle install：

bundle config build.eventmachine --with-cppflags=-I/usr/local/opt/openssl/include

数据初始化

Canvas 默认配置

在我们设置数据库中的所有表之前，我们的 Rails 代码依赖于一些小的配置文件，这些文件包含了很好的示例设置，所以我们需要快速设置它们。我们稍后会更详细地讨论它们。从 Canvas 根目录，你可以这样拉取默认配置值：

for config in amazon_s3 delayed_jobs domain file_store outgoing_mail security external_migration; \
          do cp -v config/$config.yml.example config/$config.yml; done

动态设置

这个配置文件对于不想在 Canvas 中运行 consul 集群的用户很有用。只需提供你想让 DynamicSettings 类找到的配置数据，它将在发出对 consul 数据的调用时使用它。数据应该像下面的示例一样，一个与相关数据集的键，以及键/值对的哈希（没有嵌套）：（译者注：这一部分我没有研究过，不是很清楚，所以采用机翻）

cp config/dynamic_settings.yml.example config/dynamic_settings.yml

文件生成

Canvas 需要在正确工作之前构建许多静态文件。你需要运行：

bundle exec rails canvas:compile_assets

请注意，npm 有时会尝试同时打开太多文件而出现问题。如果在运行 npm 时看到 libuv 错误，请尝试增加 ulimit。在 macOS 上，可以将 ulimit -n 4096 添加到 ~/.bash_profile 或 ~/.zsh_profile。

数据库配置

现在我们需要设置数据库配置。我们为快速入门提供了一个示例文件，所以你只需要复制它。你还需要创建两个数据库。根据你的操作系统（例如在 Linux 上），你可能需要使用 postgres 用户来创建数据库，并配置 database.yml 使用特定的用户名连接。有关如何执行此操作的详细信息，请参阅Production Start教程。在 macOS 上，你的本地用户将已经有权限创建数据库，因此不需要特殊配置。（译者注：之前我们已经给当前用户添加了postgres的超级用户权限，所以可以直接使用当前登陆用户操作）

cp config/database.yml.example config/database.yml
createdb canvas_development

注意：当使用 brew 安装 postgres 时，你可能会遇到连接数据库时出现问题，可能会出现以下错误：

createdb canvas_development
createdb: could not connect to database postgres: could not connect to server: No such file or directory
    Is the server running locally and accepting
    connections on Unix domain socket "/var/pgsql_socket/.s.PGSQL.5432"?

如果你遇到创建数据库时的连接错误，请运行以下命令并将其添加到 .bash_profile：

export PGHOST=localhost

添加之后，你可能会遇到以下错误：

createdb canvas_development
createdb: could not connect to database template1: could not connect to server: Connection refused
    Is the server running on host "localhost" (::1) and accepting
    TCP/IP connections on port 5432?
could not connect to server: Connection refused
    Is the server running on host "localhost" (127.0.0.1) and accepting
    TCP/IP connections on port 5432?
could not connect to server: Connection refused
    Is the server running on host "localhost" (fe80::1) and accepting
    TCP/IP connections on port 5432?

此时postgres可能没有在运行，你可以通过以下命令启动postgres：

initdb /usr/local/var/postgres -E utf8
pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log start

数据库填充

当你的数据库配置好之后，我们需要实际填充数据库表和初始数据。你可以通过从应用根目录运行我们的迁移和初始化任务来完成：

bundle exec rails db:initial_setup

测试数据库

如果你想测试你的安装，你还需要创建一个测试数据库：

psql -c 'CREATE USER canvas' -d postgres
psql -c 'ALTER USER canvas CREATEDB CREATEROLE' -d postgres
createdb -U canvas canvas_test
psql -c 'GRANT ALL PRIVILEGES ON DATABASE canvas_test TO canvas' -d canvas_test
psql -c 'GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO canvas' -d canvas_test
psql -c 'GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO canvas' -d canvas_test
env RAILS_ENV=test bundle exec rails db:test:reset
psql -c 'GRANT canvas_readonly_user TO canvas' -d postgres

确保你可以运行一个 spec 文件（完整套件运行时间太长）：

bundle exec rspec spec/models/assignment_spec.rb

如果你遇到关于用户 "canvas" 的 peer authentication failed 错误，请查看这个 gist。

性能调整

安装 redis 将显著提高 Canvas 的性能。有关详细说明，请参阅Production Start#redis。在 macOS 上，使用以下命令：

brew install redis
redis-server /usr/local/etc/redis.conf
echo -e "development:\n  cache_store: redis_cache_store" > config/cache_store.yml
echo -e "development:\n  url:\n  - redis://localhost" > config/redis.yml

在 Ubuntu 上，使用以下命令：

sudo apt-get update
sudo apt-get install redis-server
redis-server
echo -e "development:\n  cache_store: redis_store" > config/cache_store.yml
echo -e "development:\n  url:\n  - redis://localhost" > config/redis.yml

如果你只是想尝试 Canvas，有一些小的配置调整可以让你获得真正的性能提升。你只需要在配置目录中的一个文件中添加三行。如果你打算进行 Canvas 开发，你可能需要跳过这一步或只启用类缓存，因为这些设置将要求你在更改 Ruby 或 ERB 文件时每次重启服务器。

echo -n 'config.cache_classes = true
config.action_controller.perform_caching = true
config.action_view.cache_template_loading = true
' > config/environments/development-local.rb

注意：使用生产环境的配置流程（详见Production Start）将会让你的Canvas跑得更快。

关于邮件

Canvas 通常会尝试发送邮件。使用快速入门指南，邮件将直接发送到运行 rails server 的控制台。如果你想设置实际发送到邮件地址的邮件，请按照Production Start指南。

启动服务

现在你只需要启动 Canvas 服务器！你需要运行 rails server 守护进程：

bundle exec rails server

在同一台计算机上打开浏览器并导航到http://localhost:3000/，使用你在数据库配置过程中设置的用户凭据登录。如果你没有在同一台计算机上运行浏览器：

bundle exec rails server --binding=IPAddress

之后，你可以通过计算机的外部主机名或 IP 地址连接，访问 http://<hostname>:3000/。

第一次登录

第一次登录时，你需要使用你在 rails db:initial_setup 过程中设置的管理员凭据登录。你当时应该在命令行中看到一个提示，要求你输入你的电子邮件和密码。

关于长时间运行的任务

Canvas 在很大程度上依赖于后台作业处理器来执行在 Web 请求期间无法完成的任务。Production Start指南中有关于如何为生产环境设置专用作业处理器的详细信息。要启动后台作业处理器，请运行以下命令：

bundle exec script/delayed_job run

安全的在本地运行 Canvas（https）

安装 puma-dev 并按照设置说明进行设置。在~/.powconfig中，添加export THEADS=1。在 Canvas 的 domain.yml 中，在开发部分下添加 ssl: true。在 session_store.yml 中，在开发部分下添加 secure: true。

在 macOS 上使用 launchctl 设置 puma-dev: launchctl load ~/Library/LaunchAgents/io.puma.dev.plist。你可以通过 tail log/development.log 中的日志来查看服务器日志。你可以通过打开 Keychain Access，将 Puma-dev CA 移动到 System 来接受证书。

问题排查

我们有一个完整的页面，列出了关于排查 Canvas 安装的常见问题。请查看我们的Troubleshooting页面。

生产环境配置

以上说明旨在让你快速了解 Canvas。如果你想真正设置一个生产环境的 Canvas 实例，请阅读Production Start页面。

Are you looking for one of our commercial subscriptions, professional services, support, or our hosted solution? Check out canvaslms.com.