> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-clara.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# 本地设置
> 本指南适用于希望在本地运行 Twenty 的贡献者或好奇的开发人员。
## 先决条件
在安装和使用 Twenty 之前，请确保在您的计算机上安装以下内容：
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* [Node v24.5.0](https://nodejs.org/en/download)
* [yarn v4](https://yarnpkg.com/getting-started/install)
* [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md)
`npm` 无法使用，您应该改用 `yarn`。 Yarn 现在与 Node.js 一起提供，因此您不需要单独安装它。
如果您尚未执行此操作，只需运行 `corepack enable` 即可启用 Yarn。
1. 安装 WSL
以管理员身份打开 PowerShell 并运行：
```powershell theme={null}
wsl --install
```
现在您应该看到一个提示，要求您重启计算机。 如果没有，请手动重启。
重启后，将打开一个 PowerShell 窗口并安装 Ubuntu。 这可能需要一些时间。
您将看到一个提示，要求为您的 Ubuntu 安装创建用户名和密码。
2. 安装和配置 git
```bash theme={null}
sudo apt-get install git
git config --global user.name "Your Name"
git config --global user.email "youremail@domain.com"
```
3. 安装 nvm、node.js 和 yarn
使用 `nvm` 安装正确的 `node` 版本。 `.nvmrc` 确保所有贡献者使用相同的版本。
```bash theme={null}
sudo apt-get install curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
```
关闭并重新打开您的终端以使用 nvm。 然后运行以下命令。
```bash theme={null}
nvm install # installs recommended node version
nvm use # use recommended node version
corepack enable
```
***
## 步骤 1：Git 克隆
在您的终端中，运行以下命令。
如果您尚未设置 SSH 密钥，您可以在 [这里](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh) 学习如何设置。
```bash theme={null}
git clone git@github.com:twentyhq/twenty.git
```
```bash theme={null}
git clone https://github.com/twentyhq/twenty.git
```
## 步骤 2：定位到项目根目录
```bash theme={null}
cd twenty
```
您应该从项目的根目录运行以下步骤中的所有命令。
## 步骤 3：设置 PostgreSQL 数据库
\*\*选项 1（首选）：\*\*要在本地预配您的数据库：
使用以下链接在 Linux 机器上安装 PostgreSQL：[PostgreSQL 安装](https://www.postgresql.org/download/linux/)
```bash theme={null}
psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
```
注意：您可能需要在命令 `psql` 前添加 `sudo -u postgres` 以避免权限错误。
\*\*选项 2：\*\*如果您已安装 docker：
```bash theme={null}
make -C packages/twenty-docker postgres-on-docker
```
\*\*选项 1（推荐）：\*\*通过 `brew` 在本地设置数据库：
```bash theme={null}
brew install postgresql@16
export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"
brew services start postgresql@16
psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
```
您可以通过执行以下操作来验证 PostgreSQL 服务器是否正在运行：
```bash theme={null}
brew services list
```
在 macOS 上通过 Homebrew 安装时
安装程序可能不会默认创建 `postgres` 用户。 相反，它会创建一个与您的 macOS 用户名（例如，“john”）匹配的 PostgreSQL 角色。
按照以下步骤检查并在必要时创建 `postgres` 用户：
```bash theme={null}
# Connect to PostgreSQL
psql postgres
or
psql -U $(whoami) -d postgres
```
在 psql 提示符（postgres=#）下，运行：
```bash theme={null}
# List existing PostgreSQL roles
\du
```
您将看到类似于以下的输出：
```bash theme={null}
Role name | Attributes | Member of
-----------+-------------+-----------
john | Superuser | {}
```
如果您没有看到 `postgres` 角色列出，请继续下一步。
手动创建 `postgres` 角色：
```bash theme={null}
CREATE ROLE postgres WITH SUPERUSER LOGIN;
```
这将创建一个具备登录权限名为 `postgres` 的超级用户角色。
```bash theme={null}
角色名 | 属性 | 成员
-----------+-------------+-----------
postgres | 超级用户 | {}
john | 超级用户 | {}
```
\*\*选项 2：\*\*如果您已安装 docker：
```bash theme={null}
make -C packages/twenty-docker postgres-on-docker
```
以下所有步骤应在 WSL 终端（在您的虚拟机内）中运行
\*\*选项 1：\*\*要在本地预配您的 PostgreSQL：
使用以下链接在 Linux 虚拟机上安装 PostgreSQL：[PostgreSQL 安装](https://www.postgresql.org/download/linux/)
```bash theme={null}
psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
```
注意：您可能需要在命令 `psql` 前添加 `sudo -u postgres` 以避免权限错误。
\*\*选项 2：\*\*如果您已安装 docker：
在 WSL 上运行 Docker 增加了额外的复杂性。
仅在您对涉及的额外步骤感到舒适时使用此选项，包括开启 [Docker Desktop WSL2](https://docs.docker.com/desktop/wsl)。
```bash theme={null}
make -C packages/twenty-docker postgres-on-docker
```
您现在可以通过 `localhost:5432` 访问数据库。
如果您使用了上面的 Docker 选项，默认凭据为用户 `postgres`、密码 `postgres`。 对于原生 PostgreSQL 安装，请使用在您的机器上已配置的凭据和角色。
## 步骤 4：设置 Redis 数据库（缓存）
Twenty 需要 Redis 缓存来提供最佳性能。
\*\*选项 1：\*\*在本地供应您的 Redis：
使用以下链接在 Linux 机器上安装 Redis：[Redis 安装](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/install-redis-on-linux/)
\*\*选项 2：\*\*如果您已安装 docker：
```bash theme={null}
make -C packages/twenty-docker redis-on-docker
```
\*\*选项 1（推荐）：\*\*通过 `brew` 在本地设置 Redis：
```bash theme={null}
brew install redis
```
启动您的 Redis 服务器：
```bash theme={null}
brew services start redis
```
\*\*选项 2：\*\*如果您已安装 docker：
```bash theme={null}
make -C packages/twenty-docker redis-on-docker
```
\*\*选项 1：\*\*在本地供应您的 Redis：
使用以下链接在 Linux 虚拟机上安装 Redis：[Redis 安装](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/install-redis-on-linux/)
\*\*选项 2：\*\*如果您已安装 docker：
```bash theme={null}
make -C packages/twenty-docker redis-on-docker
```
如果您需要客户端 GUI，我们推荐 [Redis Insight](https://redis.io/insight/)（提供免费版本）。
## 步骤 5：设置环境变量
使用环境变量或 `.env` 文件配置您的项目。 更多信息请参见 [此处](/l/zh/developers/self-host/capabilities/setup).
复制 `/front` 和 `/server` 目录中的 `.env.example` 文件：
```bash theme={null}
cp ./packages/twenty-front/.env.example ./packages/twenty-front/.env
cp ./packages/twenty-server/.env.example ./packages/twenty-server/.env
```
**多工作区模式：** 默认情况下，Twenty 以单工作区模式运行，在此模式下只能创建一个工作区。 要启用多工作区支持（对于测试基于子域的功能很有用），请在服务器的 `.env` 文件中设置 `IS_MULTIWORKSPACE_ENABLED=true`。 详见 [多工作区模式](/l/zh/developers/self-host/capabilities/setup#multi-workspace-mode)。
## 步骤 6：安装依赖项
要构建 Twenty 服务器并向你的数据库预置一些数据，请运行以下命令：
```bash theme={null}
yarn
```
注意 `npm` 或 `pnpm` 将不起作用
## 步骤 7：运行项目
根据您的 Linux 发行版，Redis 服务器可能会自动启动。
如果没有，请查看您的发行版的 [Redis 安装指南](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/)。
Redis 应该已经在运行中。 如果没有，运行：
```bash theme={null}
brew services start redis
```
根据您的 Linux 发行版，Redis 服务器可能会自动启动。
如果没有，请查看您的发行版的 [Redis 安装指南](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/)。
使用以下命令设置您的数据库：
```bash theme={null}
npx nx database:reset twenty-server
```
启动服务器、工作程序和前端服务：
```bash theme={null}
npx nx start twenty-server
npx nx worker twenty-server
npx nx start twenty-front
```
或者，您可以一次启动所有服务：
```bash theme={null}
npx nx start
```
## 步骤 8：使用 Twenty
**前端**
Twenty 的前端将在 [http://localhost:3001](http://localhost:3001) 运行。
您可以使用默认的演示帐号登录：`tim@apple.dev` （密码：`tim@apple.dev`）
**后端**
* Twenty 的服务器将在 [http://localhost:3000](http://localhost:3000) 启动并运行
* 可在 [http://localhost:3000/graphql](http://localhost:3000/graphql) 访问 GraphQL API
* 可通过 [http://localhost:3000/rest](http://localhost:3000/rest) 访问 REST API
## 故障排除
如果您遇到任何问题，请检查[故障排除](/l/zh/developers/self-host/capabilities/troubleshooting)以获取解决方案。