跳到主要内容

部署文件与目录

安装是在一个部署目录里执行的。这些文件由 CLI 直接在目标主机上生成，不需要先下载到别的机器再拷过去。.env 缺失时 soln install 会从 .env.example 复制生成。

第 1 步：安装 CLI​

npm install -g @soln/cli
  • 成功：命令正常结束，没有 EACCES 或 404 报错
  • EACCES: permission denied —— 全局安装目录无权限，可以改成用户级前缀：npm install -g @soln/cli --prefix "$HOME/.local"，再把 $HOME/.local/bin 加进 PATH；或者干脆不装全局，所有命令用 npx @soln/cli
  • 404 Not Found —— 当前 npm registry 没有 @soln/cli，用 npm config get registry 检查源，或向管理员索取内网仓库地址
sl help
  • 成功：打印帮助，能看到 sl prepare、sl install、sl doctor、sl status、sl upgrade、sl rollback
  • command not found: sl —— 全局 bin 目录不在 PATH，执行 npm prefix -g 把它的 bin 目录加进去；或所有命令前面加 npx @soln/cli

本页用到的命令都在 Soln CLI 里统一说明；那个页面还包括查询版本（soln version）、部署命令（prepare、doctor、install、status、upgrade、rollback）和退出码。

第 2 步：创建部署目录​

本机部署（Docker Desktop，不要用 sudo）：

mkdir -p "$HOME/soln-tenant-runtime"
cd "$HOME/soln-tenant-runtime"

Windows（PowerShell）对应命令：

New-Item -ItemType Directory -Force "$HOME\soln-tenant-runtime"
Set-Location "$HOME\soln-tenant-runtime"

服务器部署（Linux）：

sudo mkdir -p /opt/soln-tenant-runtime
sudo chown "$USER" /opt/soln-tenant-runtime
cd /opt/soln-tenant-runtime

--dir 的路径怎么写​

所有部署命令（prepare、doctor、install、status、upgrade、rollback）都接受 --dir <路径>，这个路径是部署目录本身，也就是放 docker-compose.yml 和 .env 的那个目录，不是某个文件。

deployment register、deployment prepare 和 deployment origin 必须显式填写 --dir。生命周期命令不写 --dir 时，CLI 用的是你当前所在的目录；所以上面 cd 进去之后，sl doctor 和 soln doctor --dir "$HOME/soln-tenant-runtime" 完全等价。

# 本机部署，即第 2 步创建的目录
soln doctor --dir "$HOME/soln-tenant-runtime"

# 服务器部署
soln doctor --dir /opt/soln-tenant-runtime
soln doctor --dir "$HOME\soln-tenant-runtime"
soln doctor --dir "D:\soln\tenant-runtime"
  • 相对路径按当前所在目录解析，绝对路径直接使用
  • 路径里有空格要加引号：--dir "/Users/me/Soln Tenant Runtime"
  • ~ 不要写在引号里：--dir "~/soln-tenant-runtime" 会去找一个名字就叫 ~ 的目录。写成 --dir "$HOME/soln-tenant-runtime"，或者不加引号写成 ~/soln-tenant-runtime
  • 路径指错时，sl doctor 会报 <dir>/docker-compose.yml 的 No such file or directory，以及 <dir>/.env 不存在；这只说明目录指错了，不代表主机有问题

第 3 步：通过 CLI 登记并生成文件​

先按 CLI 部署登记与授权 登录并登记目标 Runtime，然后执行：

sl deployment prepare --dir '<部署目录>'

它从控制面登记和本地 .soln-install-setup.json 生成部署文件，无需手工填写租户 ID、Runtime ID 或 Agent 密钥。登记时选择 --deployment-target local|server 和 --deployment-mode singleMachine|externalServices；本机只支持单机模式。

已有文件会拒绝覆盖，只有检查过文件后才使用 prepare --force。已安装目录使用 sl upgrade。安装配置与控制面登记不一致时，先核对登记，不要手改安装配置里的身份信息。

第 4 步：确认文件已就位​

ls -l docker-compose.yml .env.example reverse-proxy.conf \
  cloudflared-config.yml agent.config.json
  • 成功：五个文件都能列出来
  • No such file or directory —— 说明 prepare 不是在这个目录执行的，回到第 3 步
文件内容
docker-compose.yml四个 Soln 产品与反向代理，单机模式下还包含 PostgreSQL、Temporal、MinIO
.env.example部署需要的全部环境变量，权限 0600；安装时会用它生成 .env
reverse-proxy.conf同源反向代理的 nginx 配置
cloudflared-config.yml可选的 Cloudflare Named Tunnel ingress；在 Runtime Origin 确定前主机名是占位符
storage-iam-policy.example.json外部服务模式下 Bucket 策略的起点
README.md生成的部署说明

隧道凭据放在 Compose 挂载的 secrets 目录里，可以提前建好：

mkdir -p secrets
chmod 0700 secrets

Compose 挂载的其他运行目录由 CLI 在安装时自动创建，不需要手工准备。

状态文件与自动生成的密钥​

安装完成后，CLI 会把部署状态写入 .soln/deployment.json，权限 0600；该文件永远不包含 Agent 密钥，也不要手工编辑。安装时会自动替换缺失或仍为占位符的密钥：RUNTIME_SESSION_ENCRYPTION_KEY、SOLN_BACKUP_ENCRYPTION_KEY、TENANT_RUNTIME_INTERNAL_SECRET、LUNA_TOOL_APPROVAL_SECRET，以及单机模式下内置 PostgreSQL 和 MinIO 的密码。.env 需保持 0600。