在 Linux 上用 Docker Compose 安装 Olares：从环境准备、GPU 配置到激活与容器管理的完整指南

本文是基于 Terminus 仓库官方文档编写的实操指南，讲解如何在 Ubuntu 22.04–25.04 或 Debian 12/13 主机上，通过 Docker Compose 以容器化方式部署开源个人云操作系统 Olares。读完本文，你将掌握完整的安装链路：准备目录与编写 docker-compose.yaml、可选配置 GPU 驱动与 NVIDIA Container Toolkit、可选配置镜像加速、通过环境变量启动容器并验证运行状态，最后借助 LarePass 完成激活、登录，并学会 Olares 容器的日常管理与安全收尾。

安装前必读：系统要求与前置条件

在动手之前，请先确认设备满足 Olares 的系统要求。官方在 install-olares.md 中给出的自托管 Linux 硬件基线如下：

项目	要求
CPU	4 核及以上
内存	8 GB 及以上
存储	SSD 至少 150 GB 可用空间

:::warning SSD 是硬性要求 安装到 HDD（机械硬盘）会直接失败，务必使用 SSD。 :::

此外还需要满足以下软件与硬件前置条件：

• 操作系统：Ubuntu 22.04–25.04 或 Debian 12/13。官方注明这些版本已验证可用，其他版本"可能"也能工作，但视环境可能需要调整（见 reusables.md 中的版本兼容性说明）。
• Docker 与 Docker Compose：系统中需要已安装并运行 Docker Engine 与 Docker Compose（v2 插件形式或独立二进制均可）。
• LarePass：手机端必须先安装 LarePass。它是完成 Olares 首次设置与激活的必要工具，因为激活流程依赖 LarePass 在局域网内发现并配置设备（reusables.md 中明确标注"Required to finish setup and activate Olares"）。
• 宿主机 IP 地址：Olares 设备的局域网 IP。可用如下命令确认：

ip r

找到以 default via 开头的行，它会显示默认网关以及当前使用的网络接口，据此即可确定主机的局域网 IP。

第一步：创建配置目录与 docker-compose.yaml

创建独立目录存放 Olares 的编排文件，本文沿用官方示例目录名 olares-config：

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

在目录内新建 docker-compose.yaml。仓库在 code-snippets/docker-compose.yaml 与 code-snippets/docker-compose-GPU.yaml 中提供了两套官方模板，按是否启用 GPU 选择其一。

无 GPU 的标准版本

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:
      - OLARES_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:

启用 GPU 的版本

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:
      - OLARES_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:

关键字段与端口解读

对照模板逐项理解各字段的作用，有助于后续排障：

• image: beclab/olares:${VERSION}：${VERSION} 是 compose 插值变量，由启动命令中的环境变量注入，用于指定镜像版本。
• privileged: true：Olares 主容器以特权模式运行。从 compose 结构可以推断，Olares 需要在内层启动自己的容器运行时（如 k3s）来编排内部应用，特权模式是必要的。
• volumes: oic-data:/var：命名卷 oic-data 挂载到容器内 /var，Olares 的系统与应用数据都持久化在此卷中，卸载容器时只要保留卷即可不丢数据。
• environment: OLARES_HOST_IP=${HOST_IP}：把宿主机 IP 注入容器环境变量。${HOST_IP} 同样是 compose 插值变量，由启动命令环境提供（详见下文启动一节）。
• 端口映射：
  • 80:80、443:443：HTTP/HTTPS 服务入口，对应 Olares 桌面与各应用的 Web 访问。
  • 30180:30180：激活向导（Wizard）的本地访问端口。官方 CLI 激活文档中的示例 Wizard URL 即为 http://192.168.31.127:30180（见 activate-olares-using-cli.md）。
  • 18088:18088：olaresd-proxy 服务使用的端口。该端口在 daemon/cmd/mdns_agent/main.go 中被硬编码（port := 18088），是局域网服务发现（mDNS）agent 的监听口。
  • 41641:41641/udp：UDP 端口映射。从端口类型与仓库内置 headscale（WireGuard 控制面）组件可以推断，该端口服务于 VPN/Overlay 隧道通信。
• olaresd-proxy 服务：镜像 beclab/olaresd:proxy-v0.1.0，使用 network_mode: host 直接占用宿主机网络。其底层是 mdns-agent 二进制（构建方式见 daemon/docker/Dockerfile.agent），负责在局域网内广播 _terminus._tcp 服务，使 LarePass 能够"发现附近的 Olares"。因为 mDNS 需要直接访问局域网接口，所以该容器不走桥接网络；同时它通过 depends_on 等待 olares 主容器启动完成。

可选：配置 Docker 镜像源加速拉取

Olares 主镜像较大（首次拉取通常耗时较长，官方示例中 olares 镜像拉取用了数分钟），国内网络环境建议配置 Olares 官方镜像加速器。仓库提供了现成的配置模板 code-snippets/docker-daemon.json：

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

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

配置步骤：

1. 打开 Docker 守护进程配置文件 /etc/docker/daemon.json（如不存在则新建）。
2. 将上述内容写入该文件。其中 registry-mirrors 指定镜像加速地址；features.containerd-snapshotter 显式关闭 containerd snapshotter 特性，避免与镜像加速行为冲突。
3. 重启 Docker 使配置生效：

sudo systemctl restart docker

4. 验证配置是否生效：

docker info

若输出中出现以下内容，说明镜像源配置成功：

Registry Mirrors:
https://mirrors.olares.cn/

可选：为 GPU 设备安装依赖

安装 Olares 本身不强制要求 GPU，但绝大多数 AI 应用都需要 GPU 才能运行，且目前仅支持 NVIDIA GPU（install-olares.md 与 gpu-requirements.md 均明确说明）。硬件要求如下：

• 架构：Turing 或更新（GTX 16xx、RTX 20xx/30xx/40xx/50xx 系列及更新）。更早架构的 GPU 无法被 Olares 识别，依赖 GPU 的 AI 应用将无法运行。
• 显存：推荐 8 GB 及以上；即使 GPU 架构受支持，显存过小也会阻止许多 AI 应用运行。

不确定自己的 GPU 是否受支持时，可运行：

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	✗

确认 GPU 受支持后，按以下两步安装依赖。

1. 安装 NVIDIA 驱动

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

2. 安装 NVIDIA Container Toolkit

先配置官方软件源：

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

然后安装 Toolkit、为 Docker 配置 nvidia runtime 并重启 Docker：

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

3. 验证 GPU 可用性

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

安装成功时，输出应与下面类似（以 RTX 4070、驱动 590.44、CUDA 13.1 为例）：

+-----------------------------------------------------------------------------------------+
| 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-compose-GPU.yaml 中 deploy.resources.reservations.devices 的 GPU 声明才能真正生效。

启动容器：设置环境变量并执行 docker compose up

在 olares-config 目录下，执行以下命令设置环境变量并后台启动全部服务：

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

两个环境变量的含义：

• VERSION=<olares version>：指定 Olares 镜像版本，会被 compose 读取并填充到 beclab/olares:${VERSION} 的镜像标签中。把 <olares version> 替换为实际版本号，例如 1.11.5 或 1.12.5。
• OLARES_HOST_IP=<host ip>：指定 Linux 主机的 IP 地址，用于注入容器环境变量，让 Olares 内部服务正确绑定宿主机网络。把 <host ip> 替换为前面 ip r 查到的实际地址。

:::info 关于 compose 插值变量 仓库模板中容器环境变量写作 OLARES_HOST_IP=${HOST_IP}，即它读取的是 compose 插值变量 HOST_IP。如果容器内发现主机 IP 未正确注入，可在启动命令中一并设置 HOST_IP（与 OLARES_HOST_IP 同值），例如：

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

:::

首次执行时 Docker 会拉取镜像，命令输出大致如下，可以看到全部 20 个镜像层按顺序拉取完成：

[+] 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

随后用 docker ps 确认容器运行状态：

docker ps

正常时输出类似：

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       "/usr/local/bin/entr…"   2 minutes ago        Up About a minute   0.0.0.0:80->80/tcp...   olares-olares-1

注意两个容器各司其职：

• olares-olares-1：Olares 主容器，命令为 /usr/local/bin/entr…，占用 80/443 等端口。
• olares-olaresd-proxy-1：mDNS 服务发现代理容器，命令为 /mdns-agent，无端口映射（因为它使用宿主机网络）。

关于后者，源码层面可以印证其作用：mdns-agent 通过 zeroconf 在局域网注册 _terminus._tcp 服务（实例名 olaresd），并将注册 IP 与网络接口变化时自动重启广播（见 daemon/internel/mdns/server.go）。这正是 LarePass "发现附近的 Olares" 的底层机制，也是该容器必须使用 network_mode: host 的原因。

激活 Olares：通过 LarePass 完成首次设置

容器启动后，需要借助手机上的 LarePass 完成激活（完整流程见 install-and-activate-olares.md）。

:::warning 同一网络要求 为避免激活失败，请确保手机与 Olares 设备连接在同一网络下。 :::

1. 打开 LarePass。如果你还没有 Olares ID，点击 Create an account（创建账户）并按提示操作。Olares ID 由本地名和域名组成，例如 [e-mail] 中的 alice123 是本地名、olares.com 是域名（详见 create-olares-id.md）。

2. 在激活页面点击 Discover nearby Olares（发现附近的 Olares），LarePass 会列出同一网络中检测到的 Olares 实例（这正是上一步 olaresd-proxy 的 mDNS 广播在工作）：

   

3. 选择你的 Olares 实例，点击 Install now（立即安装）。

4. 安装完成后点击 Activate now（立即激活）。

5. 在弹出的 Select a reverse proxy（选择反向代理）对话框中，选择地理位置更近的节点，安装程序会据此为 Olares 配置 HTTPS 证书与 DNS。

   :::tip 说明

   • 该设置之后可在 Olares 的 更改反向代理 页面随时修改。反向代理本质是 Olares 与公网之间的安全网关：无公网 IP 时，可通过 Olares Tunnel（官方多地区节点）或 Self-built FRP（自建 FRP 服务器）对外暴露服务。
   • 如果 Olares 设备本身连接了公网 IP，此步会自动跳过。 :::

6. 选择 Olares 的系统语言。目前支持英语、简体中文、德语、西班牙语、意大利语、法语和日语。

   :::info 注意 该选择不会改变 LarePass 应用的语言，后续激活步骤仍以 LarePass 当前语言显示；激活后 Olares Desktop 将使用这里选择的语言。 :::

7. 按屏幕提示为 Olares 设置登录密码，然后点击 Complete（完成）。

   

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

登录 Olares：桌面地址与双重验证

激活完成后即可登录（流程见 log-in-to-olares.md）：

1. 在浏览器中打开 Olares 桌面地址，按任意键继续。

2. 在登录页输入你的 Olares 登录密码：

   

3. 系统会要求完成双重验证（2FA），二选一：

   • Confirm on LarePass（在 LarePass 中确认）：在手机上打开登录通知，点击 Confirm。
   • Enter the code manually（手动输入验证码）：在登录页选择 Verify using one time password from LarePass，然后从 LarePass 获取 6 位一次性密码——手机端路径为 Settings > My Olares 卡片并点击验证器，桌面端则在 Vault 列表第一项中查看。

:::info 提示 验证码是时效性的，请在过期前输入。 :::

登录成功后即进入 Olares 桌面，安装与激活流程至此全部完成。

管理 Olares 容器生命周期

日常管理中，可通过 Docker 命令控制 Olares 容器（操作参考 manage-olares-container.md）。

停止容器

docker stop oic

重新启动已停止的容器

docker start oic

完全卸载

彻底移除容器及其关联数据：

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

:::info 容器名以实际输出为准 官方 docker ps 示例中，compose 实际生成的容器名为 olares-olares-1、数据卷名为 olares-config_oic-data（compose 会自动以目录名/项目名为卷与容器名加前缀）。上面的 oic、oic-data 是文档示例名。执行管理命令前，请先用 docker ps 与 docker volume ls 确认实际名称，并据此替换。 :::

安装后的必做事项与故障排查

保护你的 Olares ID

激活完成后，最重要的一步是备份 Olares ID 的助记词（mnemonic phrase）。助记词是一串 12 个单词，是恢复 Olares ID 的唯一途径——在去中心化系统中，丢失助记词意味着永久失去数字身份（DID）与 Olares ID，且无法访问 Vault 中的数据。完整备份流程（设置本地密码、查看并离线记录、验证排列）见 备份助记词。

遇到问题怎么办

如果在安装、激活过程中遇到问题，建议：

• 提交 GitHub Issue，并附上你的平台、安装方式与错误详情（官方排障提示见 reusables.md 的安装排障小节）。
• 若需要从头重试，可先停止并清理容器（参考上文"完全卸载"小节），再重新执行 docker compose up -d；检查 docker compose ps 与容器日志定位具体故障。

安装完成后还能做什么

• 局域网内可使用 http://desktop.<username>.olares.local 之类的 .local 域名直接访问 Olares（详见 local-access.md，以及仓库中 intranet DNS 对 .olares.local 域名的 mDNS 应答实现 daemon/internel/intranet/dns.go）。
• 如需在不同安装路径（ISO 镜像、一键脚本、其他平台）间对比，可参考 install-olares.md 的安装方法总览。

至此，你已经完成了 Olares 在 Linux 上的容器化部署、GPU 可选配置、激活登录与日常运维的全部环节。把这套流程与仓库中的 compose 模板、mDNS 源码相互印证，就能在遇到问题时快速定位是网络发现、镜像拉取还是端口映射环节出了问题。