---
title: 本地服务器
description: 管理本地 Twenty Docker 服务器 — 启动、停止、升级、并行测试实例，以及手动设置 SDK。
icon: server
---

## 管理本地服务器

使用 `yarn twenty docker:*` 控制本地的 Twenty 容器：

| 命令                                     | 作用                        |
| -------------------------------------- | ------------------------- |
| `yarn twenty docker:start`             | 启动服务器（按需拉取镜像）             |
| `yarn twenty docker:start 2.2.0`       | 启动指定的服务器版本                |
| `yarn twenty docker:start --port 3030` | 在自定义端口启动                  |
| `yarn twenty docker:stop`              | 停止服务器（保留数据）               |
| `yarn twenty docker:status`            | 显示 URL、版本和登录凭据            |
| `yarn twenty docker:logs`              | 流式输出服务器日志                 |
| `yarn twenty docker:reset`             | 清空数据并全新开始                 |
| `yarn twenty docker:upgrade`           | 拉取最新的 `twenty-app-dev` 镜像 |
| `yarn twenty docker:upgrade 2.2.0`     | 升级到指定版本                   |

数据在重启后会保留，存储于两个 Docker 卷中（`twenty-app-dev-data` 用于 PostgreSQL，`twenty-app-dev-storage` 用于文件）。 使用 `reset` 清空所有内容。

## 固定服务器版本

当未传入版本时，`docker:start` 会根据你的应用在 `package.json` 中的 `engines.twenty` 范围解析版本 —— 这与在安装你的应用时服务器用于校验的范围相同。 它会启动满足该范围的最新已发布 `twenty-app-dev` 镜像，当该字段缺失或没有已发布版本匹配时，则回退到 `latest`：

```json filename="package.json"
{
  "engines": {
    "twenty": ">=2.2.0"
  }
}
```

显式传入一个版本以在单次运行中覆盖该范围：`yarn twenty docker:start 2.3.0`。 如果已有容器使用的是不同版本，`docker:start` 会就地升级它（在保留你的数据卷的同时重新创建容器）。

## 升级服务器镜像

`yarn twenty docker:upgrade` 将拉取最新镜像、比较摘要，并且仅在确有变更时才重新创建容器。 数据卷将被保留——只会替换容器。 如果已拉取新镜像且容器正在运行，升级会自动启动一个新容器；之后运行 `yarn twenty docker:start` 以等待其变为健康状态。

```bash filename="Terminal"
yarn twenty docker:upgrade            # Latest
yarn twenty docker:upgrade 2.2.0      # Specific version
```

使用 `yarn twenty docker:status` 验证正在运行的版本（它会显示写入容器的 `APP_VERSION`）。

## 运行并行测试实例

向任意 `docker:*` 命令传递 `--test` 以管理第二个、完全隔离的实例——这有助于在不影响主开发数据的情况下进行集成测试或试验：

| 命令                                  | 作用                  |
| ----------------------------------- | ------------------- |
| `yarn twenty docker:start --test`   | 启动测试实例 (默认端口为 2021) |
| `yarn twenty docker:stop --test`    | 停止它                 |
| `yarn twenty docker:status --test`  | 显示其状态               |
| `yarn twenty docker:logs --test`    | 流式输出其日志             |
| `yarn twenty docker:reset --test`   | 清空其数据               |
| `yarn twenty docker:upgrade --test` | 升级其镜像               |

测试实例有其自己的容器（`twenty-app-dev-test`）、卷（`twenty-app-dev-test-data`、`twenty-app-dev-test-storage`）和配置——它可与你的主实例并行运行且不会发生冲突。 将 `--test` 与 `--port` 组合使用以覆盖 2021 端口。

## 手动设置（不使用脚手架）

如果你要将 SDK 添加到现有项目中，可跳过脚手架：

```bash filename="Terminal"
yarn add twenty-sdk twenty-client-sdk
```

在 `package.json` 中添加该脚本：

```json filename="package.json"
{
  "scripts": {
    "twenty": "twenty"
  }
}
```

现在你可以运行 `yarn twenty dev`、`yarn twenty docker:start`，以及其他命令。

<Note>
不要全局安装 `twenty-sdk` —— 在每个项目中固定其版本，使每个应用都使用各自的版本。
</Note>