本地运行¶

本页介绍了在不使用 Docker 的情况下完全本机安装和运行 ZJUI-Learn 的过程。某些功能（例如外部评分器和工作区）仍然需要 Docker。 ZJUI-Learn 支持在 WSL 2 内的 macOS、Linux 和 Windows 上本机执行。

安装¶

安装先决条件：
- Git
- Node.js 24
- pnpm
- uv（Python版本管理器和包安装程序）
- PostgreSQL 17
- Redis 7 或 Valkey
- Graphviz
- d2
- pg向量

大多数先决条件都可以使用操作系统的包管理器进行安装：

===“Ubuntu（包括WSL2）”

On Ubuntu, use `apt` for the main prerequisites:

```sh
sudo apt update
sudo apt install git gcc g++ make libc6-dev graphviz libgraphviz-dev redis postgresql-common
# Configure Postgres repository
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install postgresql-17 postgresql-17-pgvector
# Optional; needed only for some example questions that use LaTeX
sudo apt install texlive texlive-latex-extra texlive-fonts-extra dvipng
```

Make sure you start Postgres:

```sh
sudo systemctl start postgresql.service
```

> If the command above shows an error like `System has not been booted with systemd as init system` or `Failed to connect to bus`, the command above can be replaced with:
>
> ```sh
> sudo service postgresql start
> ```

Install `uv` using the standalone installer:

```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env  # Add uv to PATH for current shell
```

Node.js 24 is not available in the default Ubuntu repositories -- you can install it through [nvm](https://github.com/nvm-sh/nvm).

```sh
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc # or your shell's equivalent
nvm install 24
```

Install pnpm:

```sh
npm install -g pnpm
```

d2 can be installed through the install script:

```sh
curl -fsSL https://d2lang.com/install.sh | sh -s --
```

The pgvector Postgres extension can be enabled with the following script:

```sh
sudo -u postgres psql postgres -c "CREATE EXTENSION IF NOT EXISTS vector;"
```

===“macOS”

On macOS, ensure you have installed the XCode command line tools:

```sh
xcode-select --install
```

The main prerequisites can be installed with [Homebrew](http://brew.sh/):

```sh
brew install git graphviz postgresql@17 redis uv d2 node pgvector

# Optional; needed only for some example questions that use LaTeX
brew install texlive
```

You may want to start up the `postgresql` server on boot, and add binaries to your path:

```sh
brew services start postgresql@17
brew link postgresql@17
```

Install pnpm:

```sh
npm install -g pnpm
```

克隆最新的代码：

git clone https://github.com/PrairieLearn/PrairieLearn.git
cd ZJUI-Learn

安装Python依赖项（如果需要，这将自动在.venv创建虚拟环境）：

make python-deps

???注意“对于较新版本的 gcc，pygraphviz 出现错误”

For some newer versions of gcc, the `pygraphviz` package may fail to install. If you encounter this error, you can try this command:

```sh
CFLAGS="-Wno-error=incompatible-pointer-types" make python-deps
```

This error should only happen the first time you install pygraphviz. For following calls to `make python-deps`, you should not need to set the `CFLAGS` environment variable.

安装所有依赖项并编译本地包：
```
make deps
make e2e-deps
```
上面的命令会安装所有内容。或者，您可以单独运行每个步骤：
```
pnpm install
make build
make python-deps
make e2e-deps
```

确保 postgres 数据库用户存在并且是超级用户（如果用户已存在，则可能会出现错误）：

sudo -u postgres createdb postgres
sudo -u postgres psql postgres -c "CREATE USER postgres;"
sudo -u postgres psql postgres -c "ALTER USER postgres WITH SUPERUSER;"

确保您的本地 postgres 安装允许本地连接绕过密码身份验证。首先使用以下命令找到身份验证配置文件：
```
sudo -u postgres psql postgres -c "SHOW hba_file;"
```
上面的命令将列出名为 pg_hba.conf 或等效名称的文件的路径。作为 root 或 postgres 用户，编辑上面命令列出的文件，以便使用 trust 方法设置与本地主机连接相对应的行（不要更改其他行）。如果最后两行已经表示“信任”，则无需修改。这通常显示为：
```
# TYPE  DATABASE        USER            ADDRESS                 METHOD
...
# IPv4 local connections:
host    all             all             127.0.0.1/32            trust
# IPv6 local connections:
host    all             all             ::1/128                 trust
```
更改上述文件后，您可能需要重新启动 PostgreSQL 服务器。

配置¶

如果您有自己的ZJUI-Learn 课程存储库，则需要使用本地课程存储库的路径创建文件 ZJUI-Learn/config.json。如果您需要支持浏览器内文件编辑器或文件上传，则应设置 filesRoot。如果您需要工作区支持，则应提供保存临时文件的目录路径。这是一个示例配置：

config.json

{
  "courseDirs": ["/Users/mwest/git/pl-tam212", "exampleCourse"],
  "filesRoot": "../filesRoot",
  "workspaceHostHomeDirRoot": "/tmp/workspace",
  "workspaceHomeDirRoot": "/tmp/workspace"
}

有关 config.json 的更多信息可以在服务器配置文档中找到。

发展¶

有关开发工作流程的更多信息可以在开发快速入门文档中找到。