服务器外部服务模式安装

外部服务模式只跑四个 Soln 产品和同源反向代理，PostgreSQL、Temporal、对象存储都留在租户自己的系统里。这些服务需要并入现有的备份、监控和访问控制体系时选它。

前置条件与执行位置

本路线面向已有 PostgreSQL、Temporal、MinIO 和文档解析服务的运维团队。第一次部署、没有这些服务时，使用单机安装。外部依赖的创建、备份、证书和 KMS 管理由租户团队负责。

以下命令都在 Ubuntu 24.04 部署服务器的同一个 root 终端执行。先完成服务器环境准备，并按单机安装的域名与 HTTPS 步骤准备公开入口；不执行单机模式的数据盘和安装步骤。

准备实际的控制面 API 地址、租户子域名、具有 tenant.runtime.deployment.manage 权限的成员邮箱、访问域名，以及各外部服务地址和凭据。示例值必须替换。

第 0 步：登录、登记并生成文件

npm install -g @soln/cli@latest
sl version
sl deployment login --base-url https://api.solncn.com \
  --tenant example --email operator@example.com --method email
sl deployment status --json

确认租户正确、尚未登记，再执行：

sl deployment register --dir /opt/soln-tenant-runtime \
  --deployment-target server --deployment-mode externalServices \
  --runtime-origin https://runtime.customer.example.com
sl deployment prepare --dir /opt/soln-tenant-runtime
cd /opt/soln-tenant-runtime
cp -n .env.example .env
chmod 0600 .env

保留 .soln-install-setup.json，它包含一次性安装所需的 Agent 密钥。已有登记或配置时先核对原目录和未完成安装，不要用 --force 覆盖；不要把密钥拼进命令或发给 AI。

第 1 步：准备 PostgreSQL

为这个租户 Runtime 建一个专用数据库和账号。账号需要有建表和改表权限，因为租户数据库结构由 Database Migrator 应用。

psql "postgresql://soln_user@db-host:5432/soln_customer_runtime?sslmode=verify-full" -c 'select 1'

成功：打印 1 并退出；把用户名、主机、端口和库名换成你自己的
could not translate host name —— DNS 或主机名写错
no pg_hba.conf entry for host —— 数据库还没放行这台主机
password authentication failed —— 凭据不对
FATAL: database "soln_customer_runtime" does not exist —— 先建库

把连接串写进 .env。TLS 是强制的：除 sslmode=verify-full 之外的任何取值都会被 soln doctor 拒绝。

SOLN_DEPLOYMENT_MODE=externalServices
DATABASE_URL=postgresql://soln_user:strong_password@db-host:5432/soln_customer_runtime?sslmode=verify-full

sslmode=verify-full 还会校验证书主机名；要确保签发服务端证书的 CA 在部署镜像内被信任，私有 CA 的具体信任配置须由数据库管理员验证，不能只放入 Temporal 证书目录就认为 PostgreSQL 已信任该 CA
Database Migrator 先连库并应用结构；Runtime Service 和 Workflow Worker 不执行 DDL

第 2 步：准备 Temporal

为这个租户建一个 namespace，并记下 Workflow Worker 要用的端点。

TEMPORAL_ADDRESS=temporal.customer.example.com:7233

这里填前端地址，不是 Web UI，端口保持 :7233
Workflow Worker 需要从主机出站访问这个地址
需要 TLS 或 mTLS 时，把 CA 和可选的客户端密钥对挂载到 /run/secrets，证书文件权限保持 0600
TEMPORAL_ADDRESS 还是占位符时，soln doctor 会报 DEPLOYMENT_ENV_INCOMPLETE

模板将部署目录的 secrets/ 挂载到 Runtime 和 Worker 的 /run/secrets。由管理员提供真实证书，放到以下位置，并配置 .env：

install -d -m 0700 /opt/soln-tenant-runtime/secrets

TEMPORAL_NAMESPACE=soln
TEMPORAL_TLS_ENABLED=true
TEMPORAL_TLS_SERVER_NAME=temporal.customer.example.com
TEMPORAL_TLS_CA_PATH=/run/secrets/temporal-ca.pem
TEMPORAL_TLS_CERT_PATH=/run/secrets/temporal-client.pem
TEMPORAL_TLS_KEY_PATH=/run/secrets/temporal-client-key.pem

对应主机文件为 secrets/temporal-ca.pem、secrets/temporal-client.pem、secrets/temporal-client-key.pem，权限为 0600。只使用服务端 TLS、不要求客户端证书时，将 CERT 和 KEY 两项留空。使用公开可信 CA 时可以将 CA_PATH 留空。namespace 必须已在 Temporal 创建；以服务管理员提供的认证方式为准。

第 3 步：准备对象存储

准备一个存储桶、一对访问密钥、Runtime Service 能访问的服务端端点、用户浏览器能访问的浏览器端点，以及 KMS 加密。

FILES_STORAGE_BACKEND=minio
FILES_MINIO_ENDPOINT=https://s3.customer.example.com
FILES_MINIO_BROWSER_ENDPOINT=https://files.customer.example.com
FILES_MINIO_BUCKET=soln
FILES_MINIO_ACCESS_KEY=your-access-key
FILES_MINIO_SECRET_KEY=your-secret-key
FILES_MINIO_REGION=us-east-1
FILES_MINIO_FORCE_PATH_STYLE=true
FILES_MINIO_SERVER_SIDE_ENCRYPTION=AES256

两个端点都必须用 HTTPS，可以是不同主机名：一个供服务端之间调用，一个用于给浏览器签名
FILES_MINIO_SERVER_SIDE_ENCRYPTION 必须是 AES256；其它取值会被 soln doctor 拒绝。安装前需将租户自有 MinIO KES 后端配置为 Google Cloud KMS；Soln 无法验证外部 KES 配置。
soln prepare 会在部署目录里生成 storage-iam-policy.example.json，可以作为桶策略的起点

安装前先在主机上探一下端点：

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

返回任何 HTTP 状态码说明端点可达；000 说明不可达
Could not resolve host —— DNS 问题；SSL certificate problem —— 证书问题

第 4 步：补齐配置并确认加密

使用服务器上的文本编辑器编辑 .env，填入第 1～3 步的真实值，保留生成的身份配置，不要重新创建整份文件。

外部模式还需要可从 Runtime 访问的文档解析服务，模板默认协议为 docling-serve-v1.30.0：

DOCUMENT_PARSER_URL=https://docling.customer.internal
DOCUMENT_PARSER_VERSION=docling-serve-v1.30.0

由服务管理员确认这个地址和接口兼容，不能保留示例主机名。确认数据库、Temporal 持久化存储和对象存储已按租户要求启用静态加密后，设置：

SOLN_DATA_AT_REST_ENCRYPTED=true

该值是管理员确认，不会自动开启外部服务加密。再次确认 .env 为 0600、数据库 TLS 证书有效、Temporal namespace 已创建、对象存储密钥有正确桶权限。检查不通过就停止。

第 5 步：使用私有 setup 文件安装

sl install --dir /opt/soln-tenant-runtime \
  --setup-file /opt/soln-tenant-runtime/.soln-install-setup.json --yes

命令会保留 .env 已填写值，补齐身份信息和内置密钥，然后先运行 doctor。首次安装前直接运行 doctor 可能因内置密钥未生成而失败；不要手工填写示例密钥来绕过检查。doctor 失败时安装停止，不会继续迁移。

检查通过后，CLI 校验签名发布和镜像、拉取镜像、运行 Database Migrator、启动产品和代理，等待 /health/ready，写入 .soln/deployment.json。

成功：Soln Tenant Runtime <版本> is ready.
DEPLOYMENT_SETUP_FILE_MISMATCH：核对 .env 与 setup 文件的身份、目标和模式，不要修改身份来迁就错误目录。
DEPLOYMENT_ENV_INCOMPLETE：填写列出的缺失值后重跑同一条安装命令；不要重新登记。

第 6 步：验证

soln status --dir /opt/soln-tenant-runtime

成功：已安装的发布版本、四个产品，以及 ready

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

成功：200
数据库、Temporal 或对象存储有问题时，通常会在这里暴露出来，处理办法见部署排查

确认健康接口返回 200，打开租户地址并测试登录，再执行：

(
  set -e
  sl doctor --dir /opt/soln-tenant-runtime --json
  sl status --dir /opt/soln-tenant-runtime --check --json
  rm /opt/soln-tenant-runtime/.soln-install-setup.json
  sl deployment logout
)

检查命令均成功再清理 setup 文件。保留 .env、secrets/ 和 .soln/deployment.json。

运维要点

租户数据库请用你们自己的工具备份；soln upgrade 会额外写一份迁移前备份到 <部署目录>/.soln/backups，soln rollback 会用它恢复
轮换数据库、Temporal 或对象存储凭据都要改 .env 并执行一次生命周期操作，请安排轮换窗口
.env 权限保持 0600，不要提交到代码库；里面存着数据库密码和 Agent 密钥

下一步：服务器升级与回滚。

需要更换已部署 Runtime 的访问地址时，参见更换租户访问域名。

前置条件与执行位置​

第 0 步：登录、登记并生成文件​

第 1 步：准备 PostgreSQL​

第 2 步：准备 Temporal​

第 3 步：准备对象存储​

第 4 步：补齐配置并确认加密​

第 5 步：使用私有 setup 文件安装​

第 6 步：验证​

运维要点​