服务器环境准备

服务器部署把整套 Runtime 运行在租户自有的 Linux 主机上，通过你在控制面确认的公网 Runtime Origin 访问。下面的示例使用 Ubuntu / Debian 的包管理命令。

本页可直接复制的主路线限定为 Ubuntu 24.04 + systemd，不是通用 Linux 安装脚本。Debian、RHEL 等系统需要管理员适配软件源，不能混用下面的命令。SSH 登录后执行 sudo -i，后续在同一个 root 终端操作。

先检查：

cat /etc/os-release
uname -m
ps -p 1 -o comm=

预期为 Ubuntu 24.04、x86_64 或 aarch64、systemd。其它结果先停止并确认部署方案。root 已能操作 Docker，无需加入 docker 用户组。

执行规则： 每个命令块执行完，先对照成功标志再继续。同一步中出现错误就停止，不要把 Reading package lists... Done 当作唯一成功依据，前面不能出现 E:。Docker、Node.js、Cosign 可以独立准备，例如 Docker 源失败时可以先安装 Node.js；但必须完成第 5 步全部检查，才能进入 Runtime 安装。带 set -e 的块会在命令失败后停止，最后几行没有执行也就没有完成该步骤。

容量规划与数据卷选择

项目	规划要求
完整单机部署入门配置	2 vCPU、4 GiB 内存；小规格服务器建议配置 2 GiB Swap。业务容量需按实际负载验证
系统盘	建议至少 60 GiB，预留公共依赖、产品镜像、日志、离线导入临时文件和升级空间
租户数据卷	新企业部署建议独立加密数据盘，按数据库、附件和工作流数据增长规划；小规模使用也可选择容量足够的加密文件卷
较大业务负载	可从 8 vCPU、16 GiB 内存、200 GiB SSD 做初始规划，再按并发、文档解析和存储量压测调整；这不是所有租户的固定要求
CLI 磁盘检查	部署目录所在文件系统至少剩余 10 GiB；这是可用空间检查，不是整套安装所需总容量

2 GiB 内存不再作为当前完整单机部署的推荐入口；CLI 当前没有强制执行 4 GiB 内存下限。健康接口返回 200 说明服务就绪，不代表代表性业务负载已通过压测。Swap 不能替代物理内存。

完整单机模式包含文档解析服务。一次 Linux AMD64 部署中，Docling 镜像报告约 8 GB，全部镜像约 14 GB；数字会随发布、架构和共享镜像层变化。40 GiB 系统盘在包含 8 GiB 加密文件卷和 2 GiB Swap 后，部署完成只剩约 11 GiB，不宜作为新部署的默认容量。只导入服务器所需架构，避免额外架构占用空间。

小规格服务器：检查并创建 Swap

在 root 终端先执行：

free -h
swapon --show
df -h /

已有 Swap 时先核对容量，不重复创建。无 Swap 且系统盘空间足够时执行；以下只创建新的 /swapfile，发现同名文件会停止：

(
  set -e
  if [ -e /swapfile ]; then
    echo '/swapfile 已存在，停止；先检查现有文件'
    exit 1
  fi
  fallocate -l 2G /swapfile
  chmod 600 /swapfile
  mkswap /swapfile
  swapon /swapfile
  if ! grep -qE '^[[:space:]]*/swapfile[[:space:]]' /etc/fstab; then
    printf '/swapfile none swap sw 0 0\n' >> /etc/fstab
  fi
  swapon --show
  free -h
)

成功标志： swapon --show 出现 /swapfile，容量约 2 GiB；free -h 的 Swap 总容量不再为 0。失败时停止这一步，检查磁盘余量和已有文件，不删除或覆盖现有 Swap。Swap 用于缓解测试机内存压力，不能替代正式容量规划。

前置条件

Docker Engine、Docker Compose v2、Docker Buildx
Node.js 22，用于运行 npx @soln/cli
Cosign，用于校验镜像签名
已开启磁盘加密（LUKS），并在部署 .env 中设置 SOLN_DATA_AT_REST_ENCRYPTED=true
精确 Runtime Origin 对应的可信 TLS 证书
到控制面、Soln 私有镜像 Registry 及所选公共依赖仓库的出站 HTTPS；公共镜像也可按单机安装教程离线导入
部署目录至少 10 GiB 可用磁盘，容量规划见上面的路线表
系统时间已同步

概念说明

Runtime Origin：部署对外访问地址的「源」，也就是协议 + 域名 + 端口，例如 https://runtime.customer.example.com（HTTPS 默认 443 端口，写不写都一样）。它不含路径、查询参数或 # 片段，并且必须与控制面注册时确认的地址完全一致
soln / npx @soln/cli：安装用的命令行工具，npm 包名是 @soln/cli，命令名是 soln（别名 sl）。不需要全局安装，用 npx @soln/cli <子命令> 直接运行即可
sl deployment prepare：在部署目录里直接生成部署文件（docker-compose.yml、.env.example、agent.config.json，以及反向代理与隧道配置），不需要先下载到别的机器再拷过来。用法见部署文件与目录
soln doctor：CLI 自带的自检命令，用法 soln doctor --dir <部署目录>。它检查 Docker、Compose、Buildx、Cosign 是否可用，文件权限是否合规，环境变量是否齐全，部署目录是否有 10 GiB 以上可用空间。安装和升级都会先跑一遍，任何一项不通过就会中止

本页用于检查和安装基础软件。新服务器尚无加密卷时，先完成基础工具安装，再按服务器单机模式安装选择一种数据卷路线；不要因挂载检查暂时没有结果而猜测设备或格式化系统盘。以下加密与 HTTPS 检查必须在运行 Runtime 安装命令前通过。

第 1 步：登录服务器并确认加密

本页所有命令都要在服务器上执行，不是在你自己电脑上。ssh 是登录 Linux 主机的标准方式：它在你电脑上开一个连到服务器的终端，之后敲的命令都作用在服务器上。

ssh deploy@runtime.example.com

deploy 是你在那台服务器上的账号，runtime.example.com 是它的地址或 IP，这两个值由机房或云厂商提供给你，请替换成自己的
成功：提示符变成 deploy@runtime:~$ 这样的形式，说明后面敲的命令是在服务器上执行
如果你已经通过云控制台、跳板机，或直接在服务器终端里登录了，跳过这条命令，直接执行下面的检查
Permission denied (publickey) —— 用户名或密钥不对，试 ssh -i ~/.ssh/id_ed25519 user@host
Could not resolve hostname —— 地址写错或 DNS 不可用
在 Windows 电脑上操作时，用 PowerShell 自带的 ssh（Windows 10 1809 及以上自带 OpenSSH 客户端）；报 ssh : 无法将“ssh”项识别为 cmdlet 说明没装「OpenSSH 客户端」可选功能

连接成功后，先进入 root 终端，再继续：

sudo -i

lsblk -f

块设备上的 crypto_LUKS 可帮助识别加密容器，但不能证明 SOLN_DATA_ROOT 已挂载在其中；文件容器形式的 LUKS 也可能不直接显示在这份列表里
云平台原生加密盘应在云控制台核实磁盘身份、挂载到实例的状态和加密状态。Linux 可能只显示 /dev/vdb 或其分区上的普通 ext4，不能据此判断云平台加密状态
尚未启用加密时，按单机模式安装选择云平台原生加密盘或 LUKS；实际核实加密与数据挂载后，才把 SOLN_DATA_AT_REST_ENCRYPTED 设为 true
command not found: lsblk —— 安装 util-linux 包，或用 sudo cryptsetup status 查看

单机模式还需要 .env 里 SOLN_DATA_ROOT 指向的租户数据目录（默认 /srv/soln/data）。它必须位于加密卷上，并且只有部署用户可以访问：

sudo install -d -m 0700 /srv/soln/data
findmnt /srv/soln/data
stat -c '%a %U:%G %n' /srv/soln/data

findmnt 必须显示预期数据文件系统挂载在 /srv/soln/data。云平台原生加密盘需核对设备和 UUID 与实际云盘对应；LUKS 则使用 sudo cryptsetup status soln-tenant-data 检查映射，名称按实际配置替换
ls -ld /srv/soln/data 应显示 drwx------；只有目录权限正确、不代表底层已经加密或挂载
加密卷挂在别的位置？在那个位置建目录，并把 .env 的 SOLN_DATA_ROOT 改成对应路径
soln doctor 会拒绝非绝对路径、/、不存在，或组/其他用户可读的 SOLN_DATA_ROOT
外部服务模式把状态存放在租户自己的 PostgreSQL、Temporal 和对象存储上，所以只有单机模式需要这个目录

云服务器需要无人值守恢复时，优先使用云平台原生加密盘，在 fstab 配置 UUID 挂载，并在单机专用主机为 Docker 配置 RequiresMountsFor 和 AssertPathIsMountPoint=/srv/soln/data。LUKS 人工口令路线仍需每次重启后解锁，包括停机调整实例规格；外部密钥服务需另行配置。CLI 不创建数据盘、不配置解锁。按存储路线配置，并在交付前完成重启验证。

第 2 步：安装 Docker Engine

2.1 先检查 Ubuntu 软件源

阿里云 ECS 的 Ubuntu 镜像可能已经配置了内网源，先查看，不直接覆盖：

grep -RnsE '^[[:space:]]*(deb |URIs:|Suites:)' \
  /etc/apt/sources.list /etc/apt/sources.list.d 2>/dev/null

Ubuntu 源是 mirrors.cloud.aliyuncs.com、mirrors.aliyuncs.com 或 mirrors.aliyun.com：继续使用。
源是 archive.ubuntu.com 或 security.ubuntu.com，国内访问慢：按阿里云 Ubuntu 镜像说明更改现有 Ubuntu 源。Ubuntu 24.04 常使用 /etc/apt/sources.list.d/ubuntu.sources 的 URIs: 字段；只修改实际存在的源文件，保留 noble、noble-updates、noble-backports、noble-security 和签名配置。
阿里云 ECS VPC 的 Ubuntu 源可使用 http://mirrors.cloud.aliyuncs.com/ubuntu/；公网源使用 https://mirrors.aliyun.com/ubuntu/。这些地址用于 Ubuntu 软件包，APT 仍需验证发布签名。

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg xz-utils

成功标志： 两条命令都正常返回，没有 E:，软件包已安装或提示已是最新版本。锁冲突时等已有 apt 进程完成；网络或解析错误时先修复当前源，不继续安装 Docker。

2.2 选择 Docker 安装源

国内 ECS 在当前 root 终端执行：

SOLN_DOCKER_APT_BASE='https://mirrors.aliyun.com/docker-ce/linux/ubuntu'

海外服务器可改用 Docker 官方源，二选一：

SOLN_DOCKER_APT_BASE='https://download.docker.com/linux/ubuntu'

随后在同一个终端添加软件源：

(
  set -e
  test -n "$SOLN_DOCKER_APT_BASE"
  install -m 0755 -d /etc/apt/keyrings
  curl -fsSL --connect-timeout 15 "$SOLN_DOCKER_APT_BASE/gpg" \
    -o /etc/apt/keyrings/docker.asc
  chmod a+r /etc/apt/keyrings/docker.asc
  cat > /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: $SOLN_DOCKER_APT_BASE
Suites: noble
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
)

成功标志： 命令块无报错，docker.sources 的 URIs: 是所选源。已有其它 Docker .list 或 .sources 文件时，先核对并只保留一份 Docker 源，避免重复源或 Signed-By 冲突。阿里云 Docker CE 镜像说明提供的是安装包镜像，不能加速后续 docker pull。

2.3 安装软件包

sudo apt-get update

成功：命令正常返回，能看到所选 Docker 源的索引记录，且没有 E:。
NO_PUBKEY ... —— 公钥配置未成功，停止并检查第 2.2 步。
File has unexpected size 或 Hash Sum mismatch —— 获取的索引与发布元数据不一致，可能是镜像同步或缓存问题。停止 Docker 安装，稍后重试 apt-get update；仍失败时切换可达的源后重试。不要关闭哈希或签名验证，也不要继续使用报错的索引。

sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

成功：最后出现 Setting up docker-compose-plugin ...
E: Unable to locate package docker-ce —— 上面的软件源行写错，或 apt-get update 失败
docker-buildx-plugin 与 docker-compose-plugin 会把 Buildx、Compose 安装为 Docker CLI 插件；CLI 从 docker info 读取插件路径，缺失时报 DOCKER_PLUGIN_PATH_INVALID

sudo systemctl enable --now docker

成功：打印 docker 服务的 Created symlink ...
System has not been booted with systemd —— 这台机器不用 systemd，请用发行版的启动方式启动 Docker

2.4 确认引擎已响应

systemctl is-active docker

成功：输出 active
inactive 或 failed —— 执行 sudo systemctl start docker，再用 systemctl status docker 看原因

docker version

成功：Client: 与 Server: 两段都在
permission denied while trying to connect to the Docker daemon socket —— 注销后重新登录（或执行 newgrp docker）让用户组生效

第 3 步：安装 Node.js 22

3.1 国内 ECS：从阿里云镜像安装 Node.js 22

先查看 command -v node 和 command -v npm。已有符合要求的版本可直接检查，不覆盖现有安装。新服务器可从阿里云 Node.js 镜像选择一个 v22.x.y 版本，并从该版本的 SHASUMS256.txt 获取对应架构文件的 SHA-256。具体取值方法：

打开镜像根目录或其中的 index.json，选择一个 v22.x.y 版本，完整复制为 SOLN_NODE_VERSION，保留开头的 v。
打开 https://mirrors.aliyun.com/nodejs-release/所选版本/SHASUMS256.txt，将「所选版本」替换为上一步值。
uname -m 为 x86_64 时查找 node-所选版本-linux-x64.tar.xz；为 aarch64 时查找 node-所选版本-linux-arm64.tar.xz。将这一行文件名前的 64 位十六进制值复制为 SOLN_NODE_SHA256。不要复制文件名，也不要取 .tar.gz 文件的值来校验 .tar.xz。

将两个占位符替换成同一版本、同一架构的值；不要使用示例字符串执行安装：

SOLN_NODE_VERSION='REPLACE_WITH_V22_RELEASE'
SOLN_NODE_SHA256='REPLACE_WITH_SHA256_FOR_THIS_ARCH'
(
  set -e
  case "$(uname -m)" in
    x86_64) SOLN_NODE_ARCH=x64 ;;
    aarch64) SOLN_NODE_ARCH=arm64 ;;
    *) echo 'Unsupported architecture'; exit 1 ;;
  esac
  test "$SOLN_NODE_VERSION" != REPLACE_WITH_V22_RELEASE
  test "$SOLN_NODE_SHA256" != REPLACE_WITH_SHA256_FOR_THIS_ARCH
  SOLN_NODE_TMP=$(mktemp -d)
  trap 'rm -rf "$SOLN_NODE_TMP"' EXIT
  curl -fL --connect-timeout 15 \
    "https://mirrors.aliyun.com/nodejs-release/$SOLN_NODE_VERSION/node-$SOLN_NODE_VERSION-linux-$SOLN_NODE_ARCH.tar.xz" \
    -o "$SOLN_NODE_TMP/node.tar.xz"
  printf '%s  %s\n' "$SOLN_NODE_SHA256" "$SOLN_NODE_TMP/node.tar.xz" | sha256sum -c -
  tar -xJf "$SOLN_NODE_TMP/node.tar.xz" -C /usr/local --strip-components=1
  node -v
  npm -v
)

成功标志： 校验输出 OK，Node.js 为 v22.x.y，npm 输出版本号。下载或校验失败时块会停止，不解压安装；检查版本、架构和下载文件。软件安装在 /usr/local，后续更新需要重新校验并安装对应版本。

海外服务器：使用 NodeSource 软件源

这条路线与上面的二进制路线二选一，不要混用：

curl -fsSL https://deb.nodesource.com/setup_22.x -o /tmp/soln-nodesource-22.sh

下载无报错后执行：

bash /tmp/soln-nodesource-22.sh

源配置成功后执行：

sudo apt-get install -y nodejs

下载、源配置或 apt 安装失败时停止该路线，修复后重试失败步骤。

3.2 确认

node -v

成功：v22.x.y
版本不是 22 —— PATH 里排在前面的还有别的 Node.js，用 which -a node 查看
command not found: node —— 安装失败，回到 3.1 重做

第 4 步：安装 Cosign

4.1 下载二进制

中国大陆服务器可按服务器单机模式安装：从镜像入口安装 Cosign使用 GitCode 或 Soln GitHub 备份安装 v3.1.2。镜像入口与下面的官方入口二选一。

在 Cosign 官方发布页选择要安装的版本：

进入该版本页面，复制发布标签（形如 vX.Y.Z）为 SOLN_COSIGN_VERSION。
展开 Assets。服务器 uname -m 为 x86_64 时选择 cosign-linux-amd64；为 aarch64 时选择 cosign-linux-arm64。即使自己的电脑是 Mac 或 Windows，也要下载服务器对应的 Linux 文件。
下载同一发布的 cosign_checksums.txt，查找所选文件名，将该行文件名前的 64 位十六进制 SHA-256 复制为 SOLN_COSIGN_SHA256。找不到该文件的校验项时停止，不使用另一版本或另一架构的值。

将以下两个占位符替换为同一发布提供的值：

SOLN_COSIGN_VERSION='REPLACE_WITH_RELEASE_TAG'
SOLN_COSIGN_SHA256='REPLACE_WITH_PUBLISHED_SHA256_FOR_THIS_ARCH'
(
  set -e
  case "$(uname -m)" in
    x86_64) SOLN_COSIGN_ARCH=amd64 ;;
    aarch64) SOLN_COSIGN_ARCH=arm64 ;;
    *) echo 'Unsupported architecture'; exit 1 ;;
  esac
  test "$SOLN_COSIGN_VERSION" != REPLACE_WITH_RELEASE_TAG
  test "$SOLN_COSIGN_SHA256" != REPLACE_WITH_PUBLISHED_SHA256_FOR_THIS_ARCH
  SOLN_COSIGN_TMP=$(mktemp -d)
  trap 'rm -rf "$SOLN_COSIGN_TMP"' EXIT
  curl -fSL "https://github.com/sigstore/cosign/releases/download/$SOLN_COSIGN_VERSION/cosign-linux-$SOLN_COSIGN_ARCH" \
    -o "$SOLN_COSIGN_TMP/cosign"
  printf '%s  %s\n' "$SOLN_COSIGN_SHA256" "$SOLN_COSIGN_TMP/cosign" | sha256sum -c -
  install -m 0755 "$SOLN_COSIGN_TMP/cosign" /usr/local/bin/cosign
)

4.2 可选：本机下载后 SCP 上传

服务器下载较慢或超时时，可在自己的电脑从文件下载入口或上述官方发布页下载所选 Linux 二进制及同一版本的 cosign_checksums.txt。按第 4.1 步取得 SHA-256。这条路线替代服务器直接下载，不改变后续签名验证流程。

以下 SCP 命令在自己的电脑终端执行，替换本机文件路径、SSH 用户和新 ECS 公网 IP。以 x86_64 服务器为例：

scp /本机下载目录/cosign-linux-amd64 SSH用户@新ECS公网IP:/tmp/soln-cosign-upload

ARM64 服务器将本机文件名改成 cosign-linux-arm64。密码登录时，按提示在终端输入 SSH 登录密码；密钥登录可指定私钥：

scp -i /本机密钥路径 \
  /本机下载目录/cosign-linux-amd64 SSH用户@新ECS公网IP:/tmp/soln-cosign-upload

成功标志： SCP 传输完成且无错误。Permission denied (publickey) 或密码认证失败时，先修正 SSH 用户、密钥或登录方式，不能继续安装；不用把密码或私钥发给 AI。

上传成功后回到服务器 root 终端，填写官方校验值并安装：

SOLN_COSIGN_SHA256='REPLACE_WITH_PUBLISHED_SHA256_FOR_THIS_ARCH'
(
  set -e
  test "$SOLN_COSIGN_SHA256" != REPLACE_WITH_PUBLISHED_SHA256_FOR_THIS_ARCH
  test -f /tmp/soln-cosign-upload
  printf '%s  %s\n' "$SOLN_COSIGN_SHA256" /tmp/soln-cosign-upload | sha256sum -c -
  install -m 0755 /tmp/soln-cosign-upload /usr/local/bin/cosign
  cosign version
  rm /tmp/soln-cosign-upload
)

成功标志： 校验输出 OK，cosign version 显示所选发布版本。校验失败时停止，不执行安装；检查是否下载了正确发布和架构，并重新上传。

4.3 确认

cosign version

成功：输出里包含 GitVersion:
command not found: cosign —— /usr/local/bin 不在 PATH；可先用 /usr/local/bin/cosign version 确认二进制本身是否正常

生产主机安装前，请用 Cosign 官方 release 公布的校验和核对下载文件。

第 5 步：逐条校验

每条都必须成功再进入 Runtime 安装；任意一项失败，回到对应依赖步骤修复，不执行 sl install。这些与 soln doctor 执行的检查一致。

docker version --format '{{.Server.Version}}'
docker compose version --short
docker buildx version
cosign version
node -v
timedatectl status

命令	成功标志	常见失败
`docker version --format '{{.Server.Version}}'`	一个版本号，例如 `27.5.1`	`permission denied` 说明 `docker` 用户组还没生效
`docker compose version --short`	一行版本号，例如 `v2.32.4`	报 `'compose' is not a docker command` 说明缺 `docker-compose-plugin`
`docker buildx version`	以 `github.com/docker/buildx` 开头	报 `'buildx' is not a docker command` 说明缺 `docker-buildx-plugin`
`cosign version`	输出包含 `GitVersion:`	`command not found` 说明 `/usr/local/bin` 不在 `PATH`
`node -v`	`v22.x.y`	版本不是 22 说明 `PATH` 里排在前面的还有别的 Node.js
`timedatectl status`	出现 `System clock synchronized: yes`	`command not found` 说明主机不用 systemd，需另法确认 NTP

访问令牌、Session 租约、Registry 凭据和 TLS 证书都与时间强相关，请保证主机时间已同步。

第 6 步：准备域名与 TLS

Runtime Origin 必须是不含路径、查询参数、片段、用户名或密码的绝对 HTTPS Origin，并且与控制面确认的地址完全一致；否则控制面会以 INTEGRATION_RUNTIME_ORIGIN_INVALID 拒绝，同一个 Origin 也不能被其他租户注册。

dig +short runtime.customer.example.com

成功：打印该 Origin 解析到的 IP
无输出 —— 缺少 DNS 记录，先补上再安装

curl -fsS -o /dev/null -w '%{http_code}\n' \
  https://runtime.customer.example.com/health/ready

成功：Runtime 安装完成后会打印 200
Could not resolve host —— DNS 还没生效
SSL certificate problem —— 证书缺失或不受信任，先把证书装好

安装前本机 Runtime 未启动时，TLS 入口返回 502 可以预期；只有安装完成后健康接口返回 200 才表示就绪。域名解析错误或证书错误必须先修复。部署内的反向代理绑定回环地址，请按单机模式安装配置主机 nginx 和可信证书。不要把部署自带的 PostgreSQL、Temporal、MinIO 管理端口或 Temporal UI 暴露到公网。

第 7 步：准备网络与端口

国内服务器：区分三种镜像与加速

类型	用途	配置位置
Ubuntu 软件源	安装 nginx、cryptsetup 等系统包	Ubuntu 的 `.sources` 或 `.list` 文件
Docker CE 安装源	安装 Docker Engine、Compose、Buildx	`/etc/apt/sources.list.d/docker.sources`
容器镜像加速	拉取 PostgreSQL 等 Docker Hub 镜像	当前账号 ACR 提供的地址及 Docker 守护进程配置

阿里云用户可在容器镜像服务 ACR 控制台查看当前账号的「镜像加速器」及适用限制，按控制台指引配置；先检查 /etc/docker/daemon.json，有现有配置时合并所需字段，不能直接覆盖。配置生效后必须用实际镜像拉取验证，拿到地址不代表所有镜像都可用。修改需要重启 Docker 时会影响已有容器，应在首次安装前完成。

Docker Hub 加速地址不能默认覆盖 Quay 或 Soln 私有 Registry。某个依赖拉取失败时，按报错中的实际仓库处理，不改成来源不明的同名镜像。

主机需要出站 HTTPS 访问 CP_URL、Soln 私有镜像 Registry，以及 Docker Hub 的 registry-1.docker.io 和认证服务 auth.docker.io；单机部署的 PostgreSQL、MinIO、nginx、Temporal 等公共依赖镜像也要拉取。只有 Runtime Origin 需要对用户可达。

curl -fsS -o /dev/null -w '%{http_code}\n' "$CP_URL"

成功：打印 HTTP 状态码，例如 200 或 401
Could not resolve host 或 Connection timed out —— 出站被防火墙/代理拦了，需要放通

dig +short registry.example.com

成功：打印 Registry 地址
无输出 —— Registry 主机解析不到，先修 DNS

检查 Docker Hub 可达性时，不要把镜像下载失败当成 Runtime 配置错误：

docker pull --platform linux/amd64 postgres:17-alpine

以上命令适用于 x86_64 服务器；ARM64 服务器将 linux/amd64 换为 linux/arm64。i/o timeout 表示 Docker 守护进程访问 Docker Hub 失败。可使用云厂商为当前账号提供的镜像加速地址，或从可访问 Docker Hub 的机器导入同架构镜像；仍需按 CLI 的正常流程校验 Soln 发布镜像签名。实际发布也可能依赖其他公共 Registry，按 docker compose 合并发布覆盖文件后的镜像清单检查。

端口	位置	用途
`8080`	服务器部署	部署内反向代理的监听端口，保持在回环地址，前面放你的 TLS 代理或隧道
`4100`	内部	Runtime Service API，只在 Compose 网络内可达

CLI 在 soln install 和 soln upgrade 期间获取短时、仅允许 pull 的 Registry 凭据，拉取完成后退出登录；手动执行 docker login 不属于正式链路。

第 8 步：规划磁盘空间

df -h /opt

成功：Avail 列不小于 10Gi
低于 10 GiB —— 安装会以 DEPLOYMENT_DISK_INSUFFICIENT 中止

soln doctor 只检查部署目录所在文件系统的可用空间，不会按本次镜像大小计算完整容量预算。安装和升级要分别预留公共依赖、产品镜像、离线压缩包、解压导入、数据库备份及新旧镜像共存的空间。创建 Swap、加密文件卷或导入依赖镜像后，以及每次升级前，都要重新检查。

df -h /opt /srv/soln/data
du -h --max-depth=1 /srv/soln/data
docker system df

系统盘剩余空间与租户数据卷剩余空间不能相加。8 GiB LUKS 文件卷格式化后约有 7.8 GiB 总空间，数据库、附件和工作流数据共同使用；扩大系统盘不会自动扩大文件卷。容量仍充足的已有文件卷可继续使用，根据增长安排扩容或迁移，并建立异机备份。Docker 的 reclaimable 不能直接视为可安全删除的空间，不能为通过检查批量删除安装所需镜像或数据卷。

注意一个坑：这条检查量的是部署目录，而镜像实际存放在 Docker 的 data-root（默认 /var/lib/docker）。如果该目录在另一块盘上，那块盘也要单独规划容量——这条检查并不覆盖它。

下一步

继续查看部署文件与目录，然后进入单机模式安装或外部服务模式安装。

容量规划与数据卷选择​

小规格服务器：检查并创建 Swap​

前置条件​

概念说明​

第 1 步：登录服务器并确认加密​

第 2 步：安装 Docker Engine​

2.1 先检查 Ubuntu 软件源​

2.2 选择 Docker 安装源​

2.3 安装软件包​

2.4 确认引擎已响应​

第 3 步：安装 Node.js 22​

3.1 国内 ECS：从阿里云镜像安装 Node.js 22​

海外服务器：使用 NodeSource 软件源​

3.2 确认​

第 4 步：安装 Cosign​

4.1 下载二进制​

4.2 可选：本机下载后 SCP 上传​

4.3 确认​

第 5 步：逐条校验​

第 6 步：准备域名与 TLS​

第 7 步：准备网络与端口​

国内服务器：区分三种镜像与加速​

第 8 步：规划磁盘空间​

下一步​