Quick Start (Chinese Version) - instructure/canvas-lms GitHub Wiki
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
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
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页面。