> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装

> 开始使用 VillageSQL Server。

运行一个 VillageSQL Server 实例，连接到它，并试用扩展系统。

## 步骤 1：安装 VillageSQL

### 选项 A：Docker（推荐）

在容器中运行 VillageSQL，无需进行主机端安装：

```bash theme={null}
docker run -d --name vsql -e MYSQL_ROOT_PASSWORD=<your-password> -p 3306:3306 villagesql/server:mysql-9.7_latest
```

### 选项 B：Shell 脚本

使用官方安装脚本直接在您的机器上安装 VillageSQL。它会下载并配置适用于您平台的服务器二进制文件。

```bash theme={null}
curl -fsSL https://install.villagesql.com | bash
```

脚本会询问安装哪个代码库以及用哪种方式安装。源码构建还会询问安装哪个版本。在第一个问题中选择 **MySQL 9.7**，即可获得本文档描述的服务器。

如果没有终端来回答这些问题（CI 任务、Dockerfile、AI 智能体），请用环境变量传入答案，并设置在管道的 `bash` 一侧：

```bash theme={null}
curl -fsSL https://install.villagesql.com | \
  VSQL_CODEBASE=mysql-9.7 INSTALL_METHOD=prebuilt bash
```

`VSQL_CODEBASE` 接受 `mysql-8.4`、`percona-8.4` 或 `mysql-9.7`。Percona 构建仅跟踪 MySQL 8.4。`INSTALL_METHOD` 接受 `docker`、`prebuilt` 或 `source`。源码构建还需要 `VSQL_VERSION=stable|nightly|latest`；Docker 和预编译安装始终使用稳定版本。

在运行脚本之前检查脚本：`curl -fsSL https://install.villagesql.com | less`

### 选项 C：从源代码构建

对于开发或自定义构建，请按照[从源代码克隆和构建指南](https://villagesql.com/docs/zh/9.7/stable/source.md)进行操作，以从最新代码进行编译。

### Shell 脚本设置了哪些内容

Shell 脚本（选项 B）会将服务器安装到 `~/.villagesql/` 下，并在端口 3306 上启动它；如果您在脚本的安装方式问题中选择 Docker，它会改为启动一个名为 `vsql` 的容器。重要的位置如下：

| 路径 | 内容说明 |
| - | - |
| `~/.villagesql/credentials.txt` | 生成的 root 密码，以及可直接运行的启动、停止和连接命令（仅您本人可读） |
| `~/.villagesql/data/` | 数据库数据目录 |
| `~/.villagesql/mysql.sock` | 服务器套接字 |
| `~/.villagesql/mysql.log` | 服务器错误日志 |

如果 `~/.local/bin` 存在且可写，该脚本还会添加快捷命令：`villagesql`（客户端）、`villagesql-server`（服务器）和 `villagesql-admin`（管理工具）。

Docker（选项 A）和手动源代码构建不会创建 `~/.villagesql/` — Docker 将其数据保存在挂载于容器内 `/var/lib/mysql` 的 Docker 卷中。

## 步骤 2：连接到服务器

**Docker（选项 A）。** 使用任何 MySQL 客户端进行连接，并输入您通过 `MYSQL_ROOT_PASSWORD` 设置的 root 密码。请使用 `-h 127.0.0.1`，而不是默认的 `localhost`：`localhost` 会让客户端去查找 Unix 套接字，而当服务器在 Docker 中运行时该套接字不可访问。

```bash theme={null}
mysql -h 127.0.0.1 -P 3306 -u root -p
```

如果您的机器上没有 MySQL 客户端，请使用容器内的客户端：

```bash theme={null}
docker exec -it vsql mysql -u root -p
```

**Shell 脚本（选项 B）。** 脚本会安装自己的 MySQL 客户端，但不会将其加入您的 `PATH`。请运行脚本保存在 `~/.villagesql/credentials.txt` 中的 `Connect` 命令。root 密码也在同一个文件中。对于预编译安装，该命令如下所示：

```bash theme={null}
~/.villagesql/prebuilt/bin/mysql -u root -p --socket="$HOME/.villagesql/mysql.sock"
```

对于源码构建，客户端则位于 `~/.villagesql/build/bin/` 中。如果您在脚本的安装方式问题中选择了 Docker，脚本会把密码打印在屏幕上，而不会保存 `credentials.txt`；请按照选项 A 的方式连接。

## 步骤 3：安装您的第一个扩展

`INSTALL EXTENSION <name>` 会在服务器的 VEB 目录中查找 `<name>.veb` — 运行 `SHOW VARIABLES LIKE 'veb_dir';` 可以查看该目录的位置。

如果您使用 Docker（选项 A）或 shell 脚本（选项 B）安装，`veb_dir` 中已经有一批 `.veb` 文件——无需下载或复制。那里预置了两类扩展：

* 扩展，例如 `vsql_uuid`（UUID 类型和生成器），以及[捆绑扩展列表](https://github.com/villagesql/villagesql-server/blob/main/villagesql/dev_server/bundled_extensions.txt)中的其他扩展。
* `vsql_complex` 和 `vsql_simple`，是本文档其他章节中使用的参考扩展（参见 [C++ 扩展示例](https://villagesql.com/docs/zh/sdk/cpp/examples.md)），用于演示扩展框架的工作原理。

如果您从源代码构建了 VillageSQL（选项 C），`vsql_complex` 和 `vsql_simple` 也已经在 `veb_dir` 中——`make install` 会无条件构建它们。但 `vsql_uuid` 及其他扩展不会：它们位于各自独立的代码仓库中，需要单独构建和安装。如果您使用的是选项 C，请先克隆并构建 [vsql-uuid](https://github.com/villagesql/vsql-uuid) 再继续，或者跳到后面改用 `vsql_complex`——参见[安装扩展](https://villagesql.com/docs/zh/extensions/install.md)。

安装 `vsql_uuid` 扩展，以添加原生 UUID 生成功能和 `UUID` 列类型：

```sql theme={null}
INSTALL EXTENSION vsql_uuid;
```

验证安装：

```sql theme={null}
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```

您应该能看到 `vsql_uuid` 出现在列表中。

有关更多详细信息，请参阅[安装扩展](https://villagesql.com/docs/zh/extensions/install.md)。

## 步骤 4：使用扩展数据类型

现在扩展已激活，您可以在表中像使用原生类型一样使用 `UUID` 类型，它配有针对每个标准版本的生成器 — `UUID_V1()`、`UUID_V1MC()`、`UUID_V3()`、`UUID_V4()`、`UUID_V5()`、`UUID_V6()` 和 `UUID_V7()`（没有 `UUID_V2()`）— 以及用于检查已存储值的函数。下面的示例使用 v7，其值携带内嵌的时间戳，当生成时间相隔超过一毫秒时会按创建时间排序；在同一毫秒内生成的值按随机位排序，而不是按调用顺序排序：这提供了一个适合顺序排列的键，无需手工编写 `BINARY(16)` 生成逻辑。

```sql theme={null}
-- Create a database and use it
CREATE DATABASE demo;
USE demo;

-- Create a table with a UUID primary key
CREATE TABLE events (
    id UUID PRIMARY KEY,
    label VARCHAR(50)
);

-- Insert rows with generated v7 UUIDs. Each UUID_V7() embeds a millisecond
-- timestamp, so rows inserted in the same statement can land in the same
-- millisecond and tie-break on their random bits instead of insertion
-- order — insert separately, with a gap, to see the ordering clearly.
INSERT INTO events VALUES (UUID_V7(), 'signup');
SELECT SLEEP(0.01);
INSERT INTO events VALUES (UUID_V7(), 'login');
SELECT SLEEP(0.01);
INSERT INTO events VALUES (UUID_V7(), 'purchase');

-- v7 keys sort in creation order
SELECT id, label FROM events ORDER BY id;

-- Introspect the stored UUIDs
SELECT
    label,
    UUID_VERSION(id) AS version,
    UUID_TIMESTAMP(id) AS created_at
FROM events
ORDER BY id;
```

要卸载扩展，请先删除所有使用其类型的对象：

```sql theme={null}
DROP DATABASE demo;
UNINSTALL EXTENSION vsql_uuid;
```

## 停止和重启服务器

您可以通过控制服务器的容器（Docker）或其后台进程（Shell 安装）来停止和启动服务器 — 数据库会随之启动和关闭。

* **Docker（选项 A）：** `docker stop vsql` 停止服务器；`docker start vsql` 将其重新启动。
* **Shell 脚本（选项 B）：** 适用于您的安装的启动、停止和连接命令（已经填好数据目录、套接字和端口）位于 `~/.villagesql/credentials.txt` 中。如果您在脚本的安装方式问题中选择了 Docker，请使用上面的 Docker 命令。

## 后续步骤

现在您已经运行了 VillageSQL 并验证了扩展系统，可以进一步探索：

> [card] [管理扩展](https://villagesql.com/docs/zh/extensions/managing.md)
>
> 了解如何安装和管理其他扩展。

> [card] [创建扩展](https://villagesql.com/docs/zh/extensions/build/create.md)
>
> 了解如何为 VillageSQL 构建您自己的扩展。

> [card] [升级指南](https://villagesql.com/docs/en/guides/upgrade.md)
>
> 从先前版本升级或从 MySQL 迁移。

## 故障排除

### 服务器无法启动

常见问题：

* 端口 3306 已经被占用：停止另一个服务器，或在设置 `PORT=<port>` 的情况下运行安装程序。使用 Docker 时，请更改 `-p` 的主机侧端口。
* 权限：确保文件可读/可执行


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.