使用 Docker Compose 在 Linux 上安装 Olares

通过 Docker 可以在容器化环境中安装和运行 Olares。本文将介绍如何使用 Docker 设置 Olares、准备安装环境、完成激活过程以及管理容器生命周期。

安装遇到问题？

如果你在安装或使用过程中遇到问题，可以提交 GitHub Issue，并附上你的平台、安装方式和错误详情。

系统要求

必要配置

CPU：4 核及以上。
内存：至少 8 GB 可用内存。
存储：至少 150 GB 的可用 SSD 磁盘空间。
必须使用 SSD
使用机械硬盘 (HDD) 会导致安装失败。
支持的系统：
- Ubuntu 22.04-25.04 LTS
- Debian 12 或 13

版本兼容性

虽然以上版本已经过验证，但其他版本也可能正常运行 Olares。根据你的环境可能需要进行调整。如果你在这些平台上安装时遇到任何问题，欢迎在 GitHub 上提问。

可选硬件

安装 Olares 无需 GPU，但大多数 AI 应用需要 GPU 才能正常运行。目前仅支持 NVIDIA 显卡。

架构：Turing 或更新架构（GTX 16xx、RTX 20xx、30xx、40xx、50xx 系列及之后产品）。

INFO

旧架构 GPU 无法被 Olares 识别，依赖 GPU 的 AI 应用也无法运行。

显存：建议至少 8 GB。即使是受支持的显卡，如果显存过小，也会导致许多 AI 应用无法运行。

不确定显卡是否受支持？

在终端中运行以下命令，并查看输出中的代号前缀：

bash

lspci | grep -i nvidia

示例输出：

3b:00.0 VGA compatible controller: NVIDIA Corporation AD102 [GeForce RTX 4090] (rev a1)

常见代号前缀与显卡架构及是否受支持的对应关系如下：

代号前缀	架构	是否支持
GB	Blackwell	✓
AD	Ada Lovelace	✓
GA	Ampere	✓
TU	Turing	✓
GP	Pascal	✗
GM	Maxwell	✗

你也可以参考 NVIDIA 开源驱动仓库中提供的完整兼容 GPU 列表进行确认。

开始之前

开始安装前，请确保：

系统中已安装并运行 Docker 和 Docker Compose。
已知当前设备的 IP 地址。
查看 IP 地址
如需确认 IP 地址，在终端中运行以下命令：
bash
```
ip r
```
找到以 default via 开头的行，对应默认网关和正在使用的网络接口。
已通过 LarePass 创建 Olares ID 且使用默认的 olares.cn 域名。

创建文件夹

创建文件夹存储 Olares 的配置文件。例如，用如下命令创建名为 olares-config 的文件夹：

bash

mkdir ~/olares-config
cd ~/olares-config

准备 `docker-compose.yaml`

在 olares-config 目录中创建 docker-compose.yaml 文件。

根据是否启用 GPU，填入对应的内容：

docker-compose.yamldocker-compose-GPU.yaml

yaml

services:
  olares:
    image: beclab/olares:${VERSION}
    privileged: true
    volumes:
      - oic-data:/var
    ports:
      - "80:80"    
      - "443:443"    
      - "30180:30180"    
      - "18088:18088"    
      - "41641:41641/udp"
    environment:
      - HOST_IP=${HOST_IP}

  olaresd-proxy:
    image: beclab/olaresd:proxy-v0.1.0
    network_mode: host
    depends_on:
      olares:
        condition: service_started

volumes:
  oic-data:

yaml

services:
  olares:
    image: beclab/olares:${VERSION}
    privileged: true
    volumes:
      - oic-data:/var
    ports:
      - "80:80"    
      - "443:443"    
      - "30180:30180"    
      - "18088:18088"    
      - "41641:41641/udp"
    environment:
      - HOST_IP=${HOST_IP}
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

  olaresd-proxy:
    image: beclab/olaresd:proxy-v0.1.0
    network_mode: host
    depends_on:
      olares:
        condition: service_started

volumes:
  oic-data:

保存 docker-compose.yaml 文件。

安装 GPU 依赖（适用于启用 GPU 的设备）

为系统安装 GPU 驱动：

bash

curl -o /tmp/keyring.deb -L https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb && \
sudo dpkg -i --force-all /tmp/keyring.deb

sudo apt update
sudo apt install nvidia-kernel-open-590
sudo apt install nvidia-driver-590

安装 NVIDIA Container Toolkit，确保 Docker 能访问 GPU。

a. 配置软件源：

bash

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo sed -i -e '/experimental/ s/^#//g' /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update

b. 安装 Toolkit 并重启 Docker：

bash

sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

c. 验证安装：

bash

sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

如果安装成功，你将看到如下类似的输出：

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 590.44                 Driver Version: 590.44         CUDA Version: 13.1     |
 |-----------------------------------------+------------------------+----------------------+
 | GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
 | Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
 |                                         |                        |               MIG M. |
 |=========================================+========================+======================|
 |   0  NVIDIA GeForce RTX 4070 ...    Off |   00000000:01:00.0 Off |                  N/A |
 | N/A   41C    P8              1W /   80W |      32MiB /   8188MiB |      0%      Default |
 |                                         |                        |                  N/A |
 +-----------------------------------------+------------------------+----------------------+

更新 Docker 的镜像源

添加 Olares 的镜像源，提高镜像拉取速度：

打开 /etc/docker/daemon.json 文件。

编辑文件，加上以下内容：

json

{
  "registry-mirrors": [
    "https://mirrors.olares.cn"
  ],

  "features": {
    "containerd-snapshotter": false
  }
}

重启 Docker 服务以应用更改。
bash
```
sudo systemctl restart docker
```
验证配置文件是否修改成功：
bash
```
docker info
```
在输出的结果中，如输出结果包含如下内容，表示修改成功：
bash
```
Registry Mirrors:
https://mirrors.olares.cn/
```

设置环境变量并启动容器

在 olares-config 目录，运行以下命令设置环境变量并启动容器：

bash

VERSION=<olares version>-cn HOST_IP=<host ip> docker compose up -d

VERSION=<olares version>-cn：指定 Olares 镜像的版本。将 <olares version>-cn 替换为实际版本，如 1.11.5-cn。
HOST_IP=<host ip>：指定当前主机设备的 IP 地址。将 <host ip> 替换为实际地址。

运行完成后，输出结果如下：

bash

[+] Running 20/20
✔ olaresd-proxy Pulled                                                                           67.8s
✔ 688513194d7a Pull complete                                                                    6.8s
✔ bfb59b82a9b6 Pull complete                                                                    6.9s
✔ efa9d1d5d3a2 Pull complete                                                                    9.5s
✔ a62778643d56 Pull complete                                                                    9.6s
✔ 7c12895b777b Pull complete                                                                    9.6s
✔ 3214acf345c0 Pull complete                                                                   13.6s
✔ 5664b15f108b Pull complete                                                                   14.1s
✔ 0bab15eea81d Pull complete                                                                   14.2s
✔ 4aa0ea1413d3 Pull complete                                                                   15.0s
✔ da7816fa955e Pull complete                                                                   15.1s
✔ 9aee425378d2 Pull complete                                                                   15.1s
✔ 701c983262e9 Pull complete                                                                   36.2s
✔ 221438ca359c Pull complete                                                                   36.3s
✔ f3d0ed3b32e0 Pull complete                                                                   36.4s
✔ 70d5c1f325f6 Pull complete                                                                   43.2s
✔ olares Pulled                                                                                5863.6s
✔ 2d5815038f40 Pull complete                                                                 5759.0s
✔ 13788179ee16 Pull complete                                                                 5831.6s
✔ 5a9b10c3302f Pull complete                                                                 5831.7s

确认容器是否正常运行：

bash

docker ps

输出结果如下：

bash

CONTAINER ID   IMAGE                         COMMAND                  CREATED              STATUS              PORTS                   NAMES
28e86c473750   beclab/olaresd:proxy-v0.1.0   "/mdns-agent"            About a minute ago   Up About a minute                           olares-olaresd-proxy-1
5fd68a8709ad   beclab/olares:1.11.5-cn       "/usr/local/bin/entr…"   2 minutes ago        Up About a minute   0.0.0.0:80->80/tcp...   olares-olares-1

安装并激活 Olares

检查网络连接

为避免激活失败，请确保你的手机和 Olares 设备连接到同一网络。

打开 LarePass，在账号激活页面点击发现附近的 Olares。LarePass 将列出同一网络中检测到的 Olares 实例。
从列表中选择目标 Olares 实例，并点击立即安装。
安装完成后，点击立即激活。
在选择反向代理对话框中，选择一个地理位置离你较近的节点并点击确认。安装程序会自动为 Olares 配置 HTTPS 证书和 DNS。
提示
- 你可以稍后在 Olares 中的更改反向代理页面调整此设置。
- 如果你的 Olares 设备连接的是公网 IP 网络，此步骤会自动跳过。
按照屏幕提示设置 Olares 的登录密码，然后点击完成。

激活完成后，LarePass 将显示 Olares 设备的桌面地址，如 https://desktop.marvin123.olares.cn。

登录 Olares

打开 Olares 桌面地址，按任意键继续。
在登录页面输入 Olares 登录密码。
系统会要求完成双重验证。你可以选择在 LarePass 上确认登录，或手动输入 6 位验证码。
INFO
验证码有时效限制，请在过期前完成输入。

登录后你就会看到 Olares 桌面。🎉

管理 Olares 容器

停止容器

要停止运行中的容器：

bash

docker stop oic

重启容器

容器停止后，使用以下命令重启：

bash

docker start oic

容器重启后，所有服务可能需要 6–7 分钟才能完全初始化。在此时间内请耐心等待。

卸载容器

要完全移除容器及其关联数据：

bash

docker stop oic
docker rm oic
docker volume rm oic-data

下一步：安全保存 Olares ID

你已经准备好开始使用 Olares！在此之前，请务必确保 Olares ID 已安全备份。如果不备份，你将无法在需要时恢复 Olares ID。

备份助记词

安装激活

Linux

macOS

Windows (WSL 2)

PVE

文件管理器

Vault

控制面板

设置

管理用户

管理应用

配置网络

管理 GPU

备份与恢复

使用 Docker Compose 在 Linux 上安装 Olares

系统要求

必要配置

可选硬件

开始之前

创建文件夹

准备 `docker-compose.yaml`

安装 GPU 依赖（适用于启用 GPU 的设备）

更新 Docker 的镜像源

设置环境变量并启动容器

安装并激活 Olares

登录 Olares

管理 Olares 容器

停止容器

重启容器

卸载容器

下一步：安全保存 Olares ID

管理 GPU

使用 Docker Compose 在 Linux 上安装 Olares ​

系统要求 ​

必要配置 ​

可选硬件 ​

开始之前 ​

创建文件夹 ​

准备 docker-compose.yaml ​

安装 GPU 依赖（适用于启用 GPU 的设备） ​

更新 Docker 的镜像源 ​

设置环境变量并启动容器 ​

安装并激活 Olares ​

登录 Olares ​

管理 Olares 容器 ​

停止容器 ​

重启容器 ​

卸载容器 ​

下一步：安全保存 Olares ID ​

使用 Docker Compose 在 Linux 上安装 Olares

系统要求

必要配置

可选硬件

开始之前

创建文件夹

准备 `docker-compose.yaml`

安装 GPU 依赖（适用于启用 GPU 的设备）

更新 Docker 的镜像源

设置环境变量并启动容器

安装并激活 Olares

登录 Olares

管理 Olares 容器

停止容器

重启容器

卸载容器

下一步：安全保存 Olares ID