Docker 安装

这些说明假定你已经安装了 Docker，能够通过命令行来安装容器，并熟悉容器的基本操作。

使用 GitHub Container Registry

使用预构建镜像是通过 Docker 运行 SillyTavern 最快、最简单的方式。你可以从 GitHub Container Registry 拉取最新镜像。

Docker Compose（推荐）

从 GitHub 仓库下载 docker-compose.yml 文件，并在该文件所在目录下运行以下命令。这会从 GitHub Container Registry 拉取最新的 release 镜像并启动容器，同时自动创建必要的卷。

docker compose up

你可以编辑该文件并进行额外的自定义以满足需求：

默认端口为 8000，你可以通过修改 ports 部分来更改。
如果你想使用开发分支而非稳定版（release），可将 image 标签改为 staging。
如果你想通过环境变量调整服务器配置，请查看环境变量页面。

Docker CLI（高级）

要让 SillyTavern 正常运行，你需要两个必需的目录映射和一个端口映射。在命令中，请在以下位置替换为你所选的值：

容器变量

卷映射（Volume Mappings）

CONFIG_PATH - 在宿主机上存储 SillyTavern 配置文件的目录
DATA_PATH - 在宿主机上存储 SillyTavern 用户数据（包括角色）的目录
PLUGINS_PATH -（可选）在宿主机上存储 SillyTavern 服务器插件的目录
EXTENSIONS_PATH -（可选）在宿主机上存储全局 UI 扩展的目录

端口映射

PUBLIC_PORT - 对外暴露流量的端口。此项为必填，因为你需要从容器虚拟机外部访问该实例。在未单独配置安全服务的情况下，请勿将其直接暴露到互联网。

其他设置

SILLYTAVERN_VERSION - 在 GitHub Packages 页面上你会看到已打标签的镜像版本列表。镜像标签 "latest" 会使你保持与当前 release 同步。你还可以使用 "staging"，它指向相应分支的每日构建（nightly）镜像。

运行容器

打开你的命令行
在你想存储配置和数据文件的文件夹中运行以下命令：

SILLYTAVERN_VERSION="latest"
PUBLIC_PORT="8000"
CONFIG_PATH="./config"
DATA_PATH="./data"
PLUGINS_PATH="./plugins"
EXTENSIONS_PATH="./extensions"

docker run \
  --name="sillytavern" \
  -p "$PUBLIC_PORT:8000/tcp" \
  -v "$CONFIG_PATH:/home/node/app/config:rw" \
  -v "$DATA_PATH:/home/node/app/data:rw" \
  -v "$EXTENSIONS_PATH:/home/node/app/public/scripts/extensions/third-party:rw" \
  -v "$PLUGINS_PATH:/home/node/app/plugins:rw" \
  ghcr.io/sillytavern/sillytavern:"$SILLYTAVERN_VERSION"

默认情况下，容器会在前台运行。如果你想让它在后台运行，请在 docker run 命令中添加 -d 标志。

构建 Docker 镜像

以下部分假定你已将 SillyTavern 安装在非 root（非管理员）文件夹中。如果你将 SillyTavern 安装在了 root 文件夹中，则可能需要使用管理员权限 [sudo、doas、命令提示符（管理员）] 来运行其中某些命令。

如果你想自行构建 Docker 镜像，可以按以下步骤操作。这在你想自定义镜像或将其用于开发目的时很有用。

Linux

按照此处的 Docker 安装指南安装 Docker。

不要安装 Docker Desktop。
按照 Docker 安装后指南中 Manage Docker as a non-root user（以非 root 用户身份管理 Docker）部分的步骤操作。
使用你的包管理器安装 Git。
- Debian（Ubuntu/Pop! OS 等）
```
sudo apt install git
```
- Arch Linux（Manjaro/EndeavourOS 等）
```
sudo pacman -S git
```
- Fedora、Red Hat Enterprise Linux (RHEL) 等
```
sudo dnf install git
```

克隆 SillyTavern 仓库。

Release（稳定分支）

git clone https://github.com/SillyTavern/SillyTavern && cd SillyTavern/docker

Staging（开发分支）

git clone https://github.com/SillyTavern/SillyTavern -b staging && cd SillyTavern/docker

在 Docker 文件夹中运行以下命令以执行 docker compose。
```
docker compose up -d
```
打开新的浏览器并访问 http://localhost:8000。你应该会在几秒钟后看到 SillyTavern 加载完成。

Windows

关于 Windows 上的 Docker

在 Windows 上使用 Docker 非常复杂。你不仅需要在“启用或关闭 Windows 功能”中启用“适用于 Linux 的 Windows 子系统”，还需要为系统配置虚拟化（Intel VT-d/AMD SVM），而该配置因 PC 制造商（或主板制造商）而异。有时，某些系统上根本没有这个选项。

强烈建议你按照我们的 Windows 指南来安装 SillyTavern。本节只是关于在 Windows 上如何完成的粗略思路。

按照此处的 Docker 安装指南安装 Docker Desktop。
安装 Git for Windows。

克隆 SillyTavern 仓库。

Release（稳定分支）

git clone https://github.com/SillyTavern/SillyTavern && cd SillyTavern/docker

Staging（开发分支）

git clone https://github.com/SillyTavern/SillyTavern -b staging && cd SillyTavern/docker

在 Docker 文件夹中运行以下命令以执行 docker compose。
```
docker compose up -d
```
打开新的浏览器并访问 http://localhost:8000。你应该会在几秒钟后看到 SillyTavern 加载完成。

macOS

虽然 macOS 与 Linux 类似，但它没有 Docker Engine。你需要像 Windows 那样安装 Docker Desktop。你还需要安装 Homebrew，以便在 Mac 上安装 Git。本节只是关于在 macOS 上如何完成的粗略思路。

按照此处的 Docker 安装指南安装 Docker Desktop。
使用 Homebrew 安装 git。
```
brew install git
```

克隆 SillyTavern 仓库。

Release（稳定分支）

git clone https://github.com/SillyTavern/SillyTavern && cd SillyTavern/docker

Staging（开发分支）

git clone https://github.com/SillyTavern/SillyTavern -b staging && cd SillyTavern/docker

在 Docker 文件夹中运行以下命令以执行 docker compose。
```
docker compose up -d
```
打开新的浏览器并访问 http://localhost:8000。你应该会在几秒钟后看到 SillyTavern 加载完成。

配置 SillyTavern

SillyTavern 的配置文件 (config.yaml) 将位于 config 文件夹中。配置该配置文件与在非 Docker 环境下配置并无不同，但你需要使用管理员权限运行 nano 或代码编辑器才能保存更改。

别忘了重启 SillyTavern 的 Docker 容器才能使更改生效！请确保你在 docker 文件夹中执行此命令。

docker compose restart sillytavern

定位用户数据

SillyTavern 的数据文件夹将位于 data 文件夹中。备份文件应该很简单，但恢复或向其中添加内容可能需要你使用管理员权限来执行。

运行服务器插件

在 Docker 中运行 HoYoWiki-Scraper-TS 或 SillyTavern-Fandom-Scraper 等插件，与在非 Docker 系统上运行没有区别，但我们需要对 Docker Compose 脚本稍作修改才能做到。

Note

如果你已经在 docker 文件夹中看到 plugins 文件夹，则可以跳过步骤 1-2。

使用 nano 或代码编辑器打开 docker-compose.yml，并在 volumes 下方添加以下行。

    volumes:
        - "./config:/home/node/app/config"
        - "./data:/home/node/app/data"
        - "./plugins:/home/node/app/plugins"

在 docker 文件夹中新建一个名为 plugins 的文件夹。
按照你所用插件的说明安装插件。
使用管理员权限的 nano 或代码编辑器打开 config.yaml（位于 config 文件夹中），并启用 enableServerPlugins
```
enableServerPlugins: true
```
重启 Docker 容器。
```
docker compose restart sillytavern
```

非 root 用户模式

默认情况下，容器以 root 身份运行。如果你希望挂载卷中创建的文件归属于某个特定的宿主机用户（例如，避免产生 root 拥有的文件），你可以启用非 root 模式。

选项 1：PUID/PGID（推荐）

将 PUID 和 PGID 环境变量设置为你希望容器使用的 UID/GID。入口点（entrypoint）会更新所需目录的归属，然后以该映射用户的身份运行服务器。

Docker Compose 示例：

services:
  sillytavern:
    environment:
      - PUID=1000
      - PGID=1000

Docker CLI 示例：

docker run \
  --name="sillytavern" \
  -e PUID=1000 \
  -e PGID=1000 \
  -p "$PUBLIC_PORT:8000/tcp" \
  -v "$CONFIG_PATH:/home/node/app/config:rw" \
  -v "$DATA_PATH:/home/node/app/data:rw" \
  -v "$EXTENSIONS_PATH:/home/node/app/public/scripts/extensions/third-party:rw" \
  -v "$PLUGINS_PATH:/home/node/app/plugins:rw" \
  ghcr.io/sillytavern/sillytavern:"$SILLYTAVERN_VERSION"

选项 2：Docker `--user` 标志

你也可以使用 Docker 的 --user 标志以特定用户身份运行容器。在此模式下，容器无法自动修复权限，因此请确保你提供的 UID/GID 对挂载的卷已具有写入权限。

docker run \
  --name="sillytavern" \
  --user 1000:1000 \
  -p "$PUBLIC_PORT:8000/tcp" \
  -v "$CONFIG_PATH:/home/node/app/config:rw" \
  -v "$DATA_PATH:/home/node/app/data:rw" \
  -v "$EXTENSIONS_PATH:/home/node/app/public/scripts/extensions/third-party:rw" \
  -v "$PLUGINS_PATH:/home/node/app/plugins:rw" \
  ghcr.io/sillytavern/sillytavern:"$SILLYTAVERN_VERSION"

容器健康检查

Docker 镜像内置了健康检查（healthcheck）机制，用于监控 SillyTavern 服务器的响应能力。这对于容器编排系统（如 Docker Compose、Kubernetes 或 Docker Swarm）检测并自动重启无响应的容器非常有用。

工作原理

健康检查使用心跳文件机制：

启用后，SillyTavern 服务器会定期将时间戳写入数据目录中的 heartbeat.json 文件。
健康检查脚本 (src/healthcheck.js) 会验证心跳文件是否存在以及是否近期更新过。
如果心跳文件缺失或过于陈旧（超过 2 个间隔未更新），容器将被标记为不健康（unhealthy）。

配置

健康检查脚本不支持通过命令行参数覆盖数据目录。如果你将数据目录从默认的 /home/node/app/data 更改，请确保相应地设置 SILLYTAVERN_DATAROOT 环境变量。

健康检查由 SILLYTAVERN_HEARTBEATINTERVAL 环境变量（或 config.yaml 中的 heartbeatInterval）控制。该值指定了两次心跳写入之间以秒为单位的间隔。

默认值： 0（禁用）
推荐值： 在使用 Docker 健康检查时设为 30 秒

默认的 docker-compose.yml 文件包含已启用心跳的健康检查配置：

services:
  sillytavern:
    environment:
      - SILLYTAVERN_HEARTBEATINTERVAL=30
    healthcheck:
      test: ["CMD", "node", "src/healthcheck.js"]
      interval: 30s
      timeout: 10s
      start_period: 20s
      retries: 3

检查容器健康状态

你可以使用以下命令检查容器的健康状态：

docker inspect --format='{{.State.Health.Status}}' sillytavern

或者查看包括健康状况在内的完整容器状态：

docker ps

STATUS 列会在运行时间旁边显示 healthy、unhealthy 或 starting。

禁用健康检查

如果你不需要健康检查功能，可以通过以下方式禁用：

将环境变量设置为 0：

environment:
  - SILLYTAVERN_HEARTBEATINTERVAL=0

移除或注释掉 docker-compose.yml 中的 healthcheck 部分。

Docker 常见问题

SELinux 下挂载卷的权限问题

启用了 SELinux 的 Linux 发行版（如 RHEL、CentOS、Fedora 等）可能会因安全策略阻止 Docker 容器访问挂载的卷。当容器尝试读取或写入挂载目录时，这可能导致权限被拒绝的错误。

可以在卷挂载中添加 :z 或 :Z 两个后缀。这些后缀会告知 Docker 重新标记共享卷上的文件对象。

z 选项用于卷内容将在多个容器之间共享的情况。
Z 选项用于卷内容仅由当前容器使用的情况。

示例：

# docker-compose.yml
volumes:
  ## 共享卷
  - ./config:/home/node/app/config:z
  ## 私有卷
  - ./data:/home/node/app/data:Z

被白名单拒绝

Docker Desktop 与 Docker CE

whitelistDockerHosts 配置选项（默认启用）通过解析 host.docker.internal 和 gateway.docker.internal 主机名来工作。这些主机名仅在 Docker Desktop（Windows/Mac）中可用。如果你使用的是 Linux 上的 Docker CE，这些主机名将无法解析，自动白名单功能会失败，并在容器日志中出现类似以下的错误：

Failed to resolve whitelist hostname host.docker.internal: getaddrinfo ENOTFOUND host.docker.internal
Failed to resolve whitelist hostname gateway.docker.internal: getaddrinfo ENOTFOUND gateway.docker.internal

在这种情况下，你需要按下文所述手动将 Docker 网关 IP 添加到白名单中。

执行以下 Docker 命令以获取你的 SillyTavern Docker 容器的 IP。

docker network inspect docker_default

你应该会收到类似以下的一些输出。

[
    {
        "Name": "docker_default",
        "IPAM": {
            "Config": [
                {
                    "Subnet": "172.18.0.0/16",
                    "Gateway": "172.18.0.1"
                }
            ]
        }
    }
]

记下你在 Gateway 中看到的 IP，这一点很重要。

使用你选择的文本编辑器并以管理员权限运行，转到 config 并打开 config.yaml。

在编辑器中，向下滚动到 whitelist 部分。你应该会看到类似以下的内容。
```
whitelist:
    - 127.0.0.1
```
在 127.0.0.1 下方添加一行，并填入你从 Docker 复制的 IP。之后它应该看起来类似以下内容。
```
whitelist:
    - 127.0.0.1
    - 172.18.0.1
```
保存文件并退出文本编辑器。

注意，如果你将 Docker 网络配置为桥接（bridge）模式，你也可以像平常一样将外部 IP 地址添加到白名单中。
重启 Docker 容器以应用新配置。
```
docker compose restart sillytavern
```

Docker 安装

使用 GitHub Container Registry

Docker Compose（推荐）

Docker CLI（高级）

容器变量

卷映射（Volume Mappings）

端口映射

其他设置

运行容器

构建 Docker 镜像

Linux

Windows

关于 Windows 上的 Docker

macOS

配置 SillyTavern

定位用户数据

运行服务器插件

Note

非 root 用户模式

选项 1：PUID/PGID（推荐）

选项 2：Docker --user 标志

容器健康检查

工作原理

配置

检查容器健康状态

禁用健康检查

Docker 常见问题

SELinux 下挂载卷的权限问题

被白名单拒绝

Docker Desktop 与 Docker CE

选项 2：Docker `--user` 标志