配置参考¶

SlotServe 读取 SLOTSERVE_* 环境变量，或工作目录下的 .env 文件。Docker Compose 会自动加载 .env。

Compose 变量¶

这些变量只在 docker-compose.yml 中使用，描述的是宿主机。

变量	默认值	说明
`LLAMA_CPP_DIR`	必填	`llama-server` 所在目录，只读挂载到 `/opt/llama.cpp`
`MODELS_DIR`	必填	`.gguf` 模型目录，挂载到 `/models`
`DATA_DIR`	`./data`	SQLite 数据库与日志，挂载到 `/data`
`PORT`	`8000`	对外端口
`CUDA_IMAGE`	`nvidia/cuda:12.8.1-runtime-ubuntu24.04`	基础镜像；CUDA 主版本需与 llama.cpp 编译时一致

llama-server¶

对于 llama.cpp 模型，SlotServe 运行 SLOTSERVE_LLAMA_SERVER_CMD；在 Docker 中它是 /opt/llama.cpp/llama-server，即 LLAMA_CPP_DIR 中的 llama-server。健康检查 engine（以及设置进度中的推理引擎）会显示是否找到了它。找不到时：LLAMA_CPP_DIR 必须是直接包含 llama-server 的目录（通常是 llama.cpp/build/bin），该文件必须可执行并且是为本机构建的，动态库构建还需要把 lib*.so 放在它旁边。不使用 Docker 时，把 SLOTSERVE_LLAMA_SERVER_CMD 设为完整路径。

SlotServe 设置¶

除部署参数外，所有设置都可由管理员在管理 → 系统设置中直接修改，无需重启：修改保存在数据库中，优先于 .env；点恢复默认即可取消覆盖。每次修改都会以修改前后的值记入审计日志（密钥只记录指纹），并且可以撤销。层级表示设置出现的位置：常用在策略卡片上，进阶在完整列表中，专家默认折叠。标有 ⚠️ 的设置可以在宿主机上以 root 身份执行命令（推理后端命令、挂载目录、转发镜像）：修改会记为敏感修改并通知所有管理员（之后的版本还会要求再次输入密码）。部署参数在启动时读取：请在 .env 中修改并重启。

注册与访问¶

变量	默认值	层级	说明
`SLOTSERVE_REGISTRATION_OPEN`	`true`	常用	是否允许凭邀请码注册
`SLOTSERVE_INVITE_CODE`	`change-me`	常用	注册所需邀请码；为 `change-me`（或为空）时只有第一个管理员能注册（使用初始化码）
`SLOTSERVE_APPROVAL_MODE`	`off`	常用	`off`、`long` 或 `all`：哪些预约需要管理员审批
`SLOTSERVE_APPROVAL_HOURS`	`4`	进阶	`long` 模式下，超过这个时长的预约需要审批
`SLOTSERVE_API_KEY_REVEAL`	`false`	进阶	为新建的 API 密钥保存加密副本，所有者之后可以再次查看

预约与公平使用¶

变量	默认值	层级	说明
`SLOTSERVE_QUOTA_WEEKLY_HOURS`	`0`	常用	每人每周可预约小时数（0 不限，管理员不受限；管理员可为个人临时增加额度）
`SLOTSERVE_MAX_RESERVATION_HOURS`	`8`	常用	单次预约最长时长
`SLOTSERVE_MAX_ADVANCE_DAYS`	`30`	常用	最多可提前几天预约
`SLOTSERVE_QUOTA_UPCOMING`	`0`	进阶	每人可持有的未结束预约数（0 不限）
`SLOTSERVE_SLOT_MINUTES`	`30`	进阶	日历时间粒度
`SLOTSERVE_REMINDER_MINUTES`	`10`	进阶	开始和结束提醒的提前量（分钟）

通知与时间¶

变量	默认值	层级	说明
`SLOTSERVE_TIMEZONE`	`UTC`	常用	IANA 时区，用于通知和每周配额
`SLOTSERVE_PUBLIC_URL`	空	常用	大家访问 SlotServe 的地址，用于链接及识别 SlotServe 自己的页面
`SLOTSERVE_CHAT_DEFAULT_LOCALE`	`en`	进阶	`en` 或 `zh-CN`：群机器人 Webhook、群聊和尚未绑定的聊天使用的语言
`SLOTSERVE_TELEGRAM_BOT_TOKEN`	空	进阶	Telegram 机器人 Token，留空则不启用
`SLOTSERVE_TELEGRAM_PROXY`	空	进阶	连接 Telegram 的 `http://` 或 `socks5://` 代理

开发环境¶

变量	默认值	层级	说明
`SLOTSERVE_DEVENV_ENABLED`	`false`	常用	开发环境：把 GPU 时段预约成带 SSH 的 Docker 容器
`SLOTSERVE_DEVENV_CPU_ENABLED`	`true`	进阶	允许以无 GPU 模式启动开发环境（无需预约）
`SLOTSERVE_DEVENV_CPU_PER_USER`	`2`	常用	每人同时可运行的无 GPU 环境数
`SLOTSERVE_DEVENV_CPU_CORES`	`4`	常用	单个无 GPU 环境可用的 CPU 核心数（0 表示整个共享池）
`SLOTSERVE_DEVENV_CPU_MEMORY_GB`	`16`	常用	单个无 GPU 环境可用的内存（0 表示主机内存减去 max(4 GB, 10%)）
`SLOTSERVE_DEVENV_CPU_MEMORY_POOL_GB`	`0`	专家	所有无 GPU 环境合计可占用的内存（0 表示不限）
`SLOTSERVE_DEVENV_CPU_CORES_PER_GPU`	`8`	专家	每个通道按每块 GPU 为其预约保留的 CPU 核心数（cpuset）；0 表示不保留
`SLOTSERVE_DEVENV_SSH_HOST`	空	进阶	ssh 命令中显示的主机名；留空则使用浏览器访问的地址
`SLOTSERVE_DEVENV_SSH_PORTS`	`2200-2299`	进阶	分配给开发环境的宿主机端口
`SLOTSERVE_DEVENV_PASSWORD_LOGIN`	`true`	进阶	除公钥外也允许用环境密码 SSH 登录
`SLOTSERVE_DEVENV_CPUS`	`0`	进阶	单个 GPU 环境的 CPU 上限（0 表示不限）
`SLOTSERVE_DEVENV_MEMORY_GB`	`0`	进阶	单个 GPU 环境的内存上限（0 表示主机内存减去 max(4 GB, 10%)）
`SLOTSERVE_DEVENV_PIDS_LIMIT`	`4096`	专家	单个开发环境可同时运行的进程数（fork 炸弹只影响它自己的容器）
`SLOTSERVE_DEVENV_SHM_GB`	`8`	进阶	单个环境的共享内存（`/dev/shm`）
`SLOTSERVE_DEVENV_CUSTOM_IMAGES`	`true`	进阶	允许用户用任意镜像新建模板
`SLOTSERVE_DEVENV_ALLOWED_REGISTRIES`	空	进阶	允许的镜像仓库，逗号分隔；留空表示不限
`SLOTSERVE_DEVENV_SAVED_IMAGES`	`3`	进阶	每人可保存的环境镜像数
`SLOTSERVE_DEVENV_PULL_MINUTES`	`60`	专家	预约开始前多久下载镜像
`SLOTSERVE_DEVENV_PROJECTS`	`3`	进阶	每人可保留（暂停）的环境数；0 表示不允许
`SLOTSERVE_DEVENV_PROJECT_DAYS`	`0`	进阶	自动删除闲置这么多天的保留环境（0 表示从不）
`SLOTSERVE_DEVENV_PUBLIC_PORTS_ENABLED`	`true`	进阶	允许用户把容器端口直接发布到宿主机端口（无需登录 SlotServe）
`SLOTSERVE_DEVENV_PUBLIC_PORTS`	`2300-2399`	进阶	直连端口使用的宿主机端口（与 SSH 端口分开）
`SLOTSERVE_DEVENV_PUBLIC_PORT_LIMIT`	`5`	进阶	每人直连端口数；管理员不受限制；0 表示只有管理员
`SLOTSERVE_DEVENV_WEB_URL`	空	专家	浏览器访问开发环境网页端口的地址，例如经过反向代理时；留空则为同一主机的 `DEVENV_WEB_PORT`
`SLOTSERVE_DEVENV_WEB_COMPAT`	`false`	专家	兼容模式：用于在共享网页源的环境隔离规则下无法正常工作的网页应用（会削弱环境之间的隔离）
`SLOTSERVE_DEVENV_PLATFORM_CONTEXT`	`true`	进阶	新环境内提供 `SLOTSERVE_*` 变量、登录提示（剩余时间、`/workspace`、如何调用模型）以及指向容器侧网关的 `OPENAI_BASE_URL`
`SLOTSERVE_DEVENV_LLM_KEY`	`true`	专家	为每个个人环境发放专属 LLM 密钥（`llm` 权限，环境停止即吊销；以 0600 文件提供，登录 shell 中导出为 `OPENAI_API_KEY`，从不放进容器环境变量；共享环境不发放）
`SLOTSERVE_DEVENV_FORWARDER_IMAGE`	`alpine/socat:1.8.1.1`	专家	⚠️ 以 root 身份在宿主机上执行。每个端口的转发容器所用镜像（PATH 中需要有 `socat`）
`SLOTSERVE_DEVENV_STORAGE_DIR`	空	专家	⚠️ 以 root 身份在宿主机上执行。 Docker 主机上存放持久数据的目录（绑定挂载）；留空则使用 Docker 命名卷。系统目录（`/etc`、`/root`、`/var/lib/docker`、`/proc`、`/sys`、`/boot`、`/usr`、`/bin`、`/lib*`、`/var/run` 等）会被拒绝

模型与下载¶

变量	默认值	层级	说明
`SLOTSERVE_DEFAULT_LLAMA_ARGS`	`-ngl 99 -c 8192`	常用	新登记模型的默认启动参数
`SLOTSERVE_HF_ENDPOINT`	`https://huggingface.co`	常用	Hugging Face 地址或镜像
`SLOTSERVE_HF_TOKEN`	空	进阶	受限或私有仓库所需的 Token
`SLOTSERVE_DOWNLOAD_MIN_FREE_GB`	`2`	进阶	下载完成后磁盘至少保留的空间
`SLOTSERVE_PLAYGROUND_ENABLED`	`true`	进阶	网页上与模型对话的试用页（使用浏览器会话，不使用密钥）
`SLOTSERVE_PLAYGROUND_RATE_PER_MINUTE`	`20`	进阶	每人每分钟的试用请求数；0 表示不限
`SLOTSERVE_PLAYGROUND_DEFAULT_MODEL_ONLY`	`false`	进阶	试用页只使用默认模型，不使用其他已加载的模型

模型加载¶

变量	默认值	层级	说明
`SLOTSERVE_PRELOAD_MIN_MINUTES`	`3`	进阶	预约的模型至少提前多少分钟开始加载
`SLOTSERVE_LOAD_TIMEOUT_SECONDS`	`1800`	进阶	超过此时间仍未就绪则判定加载失败
`SLOTSERVE_DRAIN_SECONDS`	`30`	进阶	切换模型前等待进行中请求完成的最长时间
`SLOTSERVE_PRELOAD_BUFFER_SECONDS`	`60`	专家	预加载时额外预留的时间
`SLOTSERVE_STOP_TIMEOUT_SECONDS`	`20`	专家	强制结束推理进程前的等待时间
`SLOTSERVE_DISK_READ_MBPS`	`150`	专家	模型首次加载前用于估算加载时间
`SLOTSERVE_SCHEDULER_INTERVAL_SECONDS`	`5`	专家	调度器重新评估的间隔

推理后端¶

变量	默认值	层级	说明
`SLOTSERVE_VLLM_CMD`	`vllm serve`	专家	⚠️ 以 root 身份在宿主机上执行。 vLLM 后端的启动命令
`SLOTSERVE_SGLANG_CMD`	`python -m sglang.launch_server`	专家	⚠️ 以 root 身份在宿主机上执行。 SGLang 后端的启动命令
`SLOTSERVE_CUSTOM_ENGINE_CMD`	空	专家	⚠️ 以 root 身份在宿主机上执行。自定义后端命令模板：`{model}` `{host}` `{port}` `{name}`
`SLOTSERVE_CUSTOM_ENGINE_HEALTH`	`/health`	专家	轮询判断自定义后端就绪的路径

飞书 / Lark¶

变量	默认值	层级	说明
`SLOTSERVE_FEISHU_ENABLED`	`false`	进阶	飞书 / Lark 机器人（配置方法）
`SLOTSERVE_FEISHU_APP_ID`	空	进阶	飞书应用的 App ID
`SLOTSERVE_FEISHU_APP_SECRET`	空	进阶	飞书应用的 App Secret
`SLOTSERVE_FEISHU_DOMAIN`	`https://open.feishu.cn`	专家	开放平台地址；Lark 使用 `https://open.larksuite.com`

钉钉¶

变量	默认值	层级	说明
`SLOTSERVE_DINGTALK_ENABLED`	`false`	进阶	钉钉 Stream 模式机器人
`SLOTSERVE_DINGTALK_CLIENT_ID`	空	进阶	钉钉应用的 Client ID（AppKey）
`SLOTSERVE_DINGTALK_CLIENT_SECRET`	空	进阶	钉钉应用的 Client Secret（AppSecret）
`SLOTSERVE_DINGTALK_ROBOT_CODE`	空	专家	RobotCode；留空即 Client ID

企业微信¶

变量	默认值	层级	说明
`SLOTSERVE_WECOM_ENABLED`	`false`	进阶	企业微信自建应用
`SLOTSERVE_WECOM_CORP_ID`	空	进阶	企业 ID（CorpID）
`SLOTSERVE_WECOM_AGENT_ID`	空	进阶	应用的 AgentId
`SLOTSERVE_WECOM_SECRET`	空	进阶	应用的 Secret
`SLOTSERVE_WECOM_TOKEN`	空	进阶	回调 Token；只在接收命令时需要
`SLOTSERVE_WECOM_AES_KEY`	空	进阶	回调 EncodingAESKey（43 位）；只在接收命令时需要

QQ¶

变量	默认值	层级	说明
`SLOTSERVE_QQ_ENABLED`	`false`	进阶	QQ 官方机器人
`SLOTSERVE_QQ_APP_ID`	空	进阶	QQ 机器人的 AppID
`SLOTSERVE_QQ_APP_SECRET`	空	进阶	QQ 机器人的 AppSecret
`SLOTSERVE_QQ_SANDBOX`	`false`	专家	使用 QQ 沙箱环境

群机器人 Webhook¶

变量	默认值	层级	说明
`SLOTSERVE_GROUP_EVENTS`	`admin_alerts,announcements`	进阶	发到群里的内容：`admin_alerts`、`approvals`、`announcements`
`SLOTSERVE_FEISHU_WEBHOOK_URL`	空	进阶	飞书 / Lark 群机器人 Webhook
`SLOTSERVE_FEISHU_WEBHOOK_SECRET`	空	进阶	飞书 / Lark 群机器人的签名密钥
`SLOTSERVE_DINGTALK_WEBHOOK_URL`	空	进阶	钉钉群机器人 Webhook
`SLOTSERVE_DINGTALK_WEBHOOK_SECRET`	空	进阶	钉钉群机器人的加签密钥
`SLOTSERVE_WECOM_WEBHOOK_URL`	空	进阶	企业微信群机器人 Webhook

监控¶

变量	默认值	层级	说明
`SLOTSERVE_METRICS_TOKEN`	空	专家	`/metrics` 的 Bearer Token，留空则关闭
`SLOTSERVE_USAGE_BUSY_PERCENT`	`10`	专家	某一分钟内 GPU 利用率不低于此值时计为“使用中”（对新采样生效）

清理与备份¶

变量	默认值	层级	说明
`SLOTSERVE_USAGE_RETENTION_DAYS`	`365`	进阶	逐条请求记录保留天数，之后合并为按天汇总（0 表示永久；否则至少 90）
`SLOTSERVE_USAGE_SAMPLE_DAYS`	`30`	专家	按分钟的 GPU 使用采样保留天数，之后合并为按小时汇总（0 表示不合并）
`SLOTSERVE_AUDIT_RETENTION_DAYS`	`730`	进阶	审计日志保留天数（0 表示永久）
`SLOTSERVE_BACKUP_KEEP`	`7`	进阶	保留的每日备份包份数（0 表示关闭自动备份）
`SLOTSERVE_BACKUP_TARGET`	空	常用	每个备份包另外复制到哪里：绝对路径或 `storage:<id>`（留空表示不复制到本机以外）
`SLOTSERVE_BACKUP_HOUR`	`3`	进阶	每日备份的本地时间（小时；-1 表示从启动起每 24 小时一次）

部署参数（重启后生效）¶

变量	默认值	层级	说明
`SLOTSERVE_DEVENV_GATEWAY_PORT`	`8002`	专家	容器侧网关的端口：只提供 `/v1` 接口，供开发环境使用（`http://slotserve-gw:<端口>/v1`）；0 表示关闭
`SLOTSERVE_DEVENV_GATEWAY_HOST`	空	专家	容器侧网关监听的地址；留空时，SlotServe 直接运行在主机上则为 Docker 网桥地址（`docker0`），运行在容器中则为所有地址
`SLOTSERVE_SECRET_KEY`	自动生成	专家	会话 Cookie 签名与已存密钥加密所用的密钥。未设置、为空或为 `change-me` 时，SlotServe 首次启动会生成随机密钥并保存在 `DATA_DIR/secret_key`（仅属主可读）。显式设置的值始终优先
`SLOTSERVE_HOST`	`0.0.0.0`	专家	监听地址
`SLOTSERVE_PORT`	`8000`	专家	监听端口
`SLOTSERVE_COOKIE_SECURE`	`false`	专家	Cookie 加 `Secure` 标记；在 HTTPS 后面时设为 `true`
`SLOTSERVE_FORWARDED_ALLOW_IPS`	`127.0.0.1`	专家	信任其 `X-Forwarded-For` 的反向代理地址（逗号分隔，`*` 表示任意），以便登录限速和日志看到真实客户端地址
`SLOTSERVE_DATA_DIR`	`data`	专家	数据库与日志目录
`SLOTSERVE_MODELS_DIR`	`models`	专家	模型目录（扫描及下载目标）
`SLOTSERVE_STATIC_DIR`	内置	专家	前端构建产物目录
`SLOTSERVE_LLAMA_SERVER_CMD`	`llama-server`	专家	⚠️ 以 root 身份在宿主机上执行。启动 llama-server 的命令，可带前缀，如 `taskset -c 0-15 llama-server`
`SLOTSERVE_LLAMA_HOST`	`127.0.0.1`	专家	推理进程监听地址（请保持本地）
`SLOTSERVE_LLAMA_PORT`	`8081`	专家	第一个通道推理进程的端口；第 N 个通道为此值 + N - 1
`SLOTSERVE_DOCKER_HOST`	`unix:///var/run/docker.sock`	专家	⚠️ 以 root 身份在宿主机上执行。开发环境使用的 Docker（或 Podman）接口
`SLOTSERVE_DROPBEAR_PATH`	`/opt/slotserve/bin/dropbearmulti`	专家	复制进每个开发环境的静态 Dropbear（`dropbearmulti`）；镜像中已自带
`SLOTSERVE_DEVENV_WEB_PORT`	`8001`	专家	开发环境网页界面的端口，作为独立的源（0 表示在 `PORT` 上提供，不推荐）
`SLOTSERVE_STORAGE_HELPER_IMAGE`	`busybox:1.37`	专家	检查存储并在其中创建目录的临时辅助容器所用的镜像（从不使用个人的镜像；缺少时自动拉取）
`SLOTSERVE_STORAGE_CHECK_MINUTES`	`30`	专家	多久检查一次存储（可用空间、每人用量）；0 表示只在手动检查时
`SLOTSERVE_TELEGRAM_API_BASE`	`https://api.telegram.org`	专家	Telegram Bot API 地址，用于自建的 Bot API 服务
`SLOTSERVE_DINGTALK_API_BASE`	`https://api.dingtalk.com`	专家	钉钉 API 地址（仅用于代理或测试）
`SLOTSERVE_WECOM_API_BASE`	`https://qyapi.weixin.qq.com`	专家	企业微信 API 地址（仅用于代理或测试）
`SLOTSERVE_QQ_API_BASE`	`https://api.sgroup.qq.com`	专家	QQ 机器人 API 地址（仅用于代理或测试）
`SLOTSERVE_QQ_TOKEN_URL`	`https://bots.qq.com/app/getAppAccessToken`	专家	QQ 机器人 Token 地址（仅用于代理或测试）

每个模型的启动参数¶

每个模型有一行自由填写的参数，会追加到命令末尾。llama.cpp 模型的命令为：

<SLOTSERVE_LLAMA_SERVER_CMD> -m <文件> --host 127.0.0.1 --port 8081 --alias <名称> <你的参数>

vLLM、SGLang 和自定义后端以同样方式拼接命令，见多 GPU 与推理后端。

-m、--host、--port、--alias 始终由 SlotServe 设置，你参数里的同名项会被忽略。常用参数：

目的	参数
全部层放到 GPU	`-ngl 99`
上下文长度	`-c 16384`
并发请求	`-np 4`（上下文在各 slot 间平分）
Flash Attention	`--flash-attn on`
视觉模型	`--mmproj /models/mmproj-model-f16.gguf`
向量模型	`--embedding --pooling mean`
KV 缓存量化	`-ctk q8_0 -ctv q8_0`

完整列表见 llama-server --help。修改了当前已加载模型的参数后，在总览页点击重新加载模型即可生效。

备份与恢复¶

SlotServe 每天在 SLOTSERVE_BACKUP_HOUR 向 data/backups/ 写出一个备份包（数据库、自动生成的会话密钥、SSH 主机密钥、清单），保留最新的 SLOTSERVE_BACKUP_KEEP 份；设置了 SLOTSERVE_BACKUP_TARGET（挂载的路径或 storage:<id>）时，每个备份包还会复制到那里。管理 → 概览 → 备份中可以查看和立即备份。每次数据库升级前也会做一份快照，这类快照不会被自动删除。slotserve restore <备份包> 可以把备份放回去（需先停止服务），下次启动时会显示核对报告。

workspace、保留环境的数据、保存的镜像和模型不在备份内。详细说明、异地副本和恢复步骤见备份和从备份恢复。

初始化码与第一个管理员¶

还没有管理员账号时，SlotServe 每次启动都会在日志中打印一个一次性的初始化码：

docker compose logs slotserve | grep -A4 "No admin account"
docker compose exec slotserve slotserve setup-code     # 或直接查询

打开 SlotServe，注册表单会要求填写初始化码（而不是邀请码），注册的账号即成为管理员。一旦存在管理员，初始化码立即失效；已经有管理员的安装不会要求填写。其他人用邀请码注册（或由管理员在管理 → 用户中创建）。

来自其他页面的请求¶

SlotServe 拒绝不是由自己页面发出的修改类请求（POST、PUT、PATCH、DELETE）：Origin 必须是 SlotServe 自己的地址（浏览器访问用的主机，或 SLOTSERVE_PUBLIC_URL），Origin: null 一律拒绝；带会话 Cookie 但没有 Origin 的请求必须带 X-SlotServe: 1 请求头（网页界面会自动带上）。这样开发环境端口上的页面或其他网站无法冒用已登录用户的身份。API 客户端不受影响：使用 API 密钥的 /v1、/metrics、聊天平台回调，以及不带会话 Cookie 的脚本。

在反向代理之后，请转发原始主机名（nginx：proxy_set_header Host $host;）或设置 SLOTSERVE_PUBLIC_URL，否则在网页上的修改会被拒绝（提示“不是从 SlotServe 页面发出的”）。

管理员命令行¶

日常的账号管理在管理 → 用户中完成。命令行用于没有管理员能登录的情况：

docker compose exec slotserve slotserve setup-code               # 创建第一个管理员所需的初始化码
docker compose exec slotserve slotserve reset-password <用户名>
docker compose exec slotserve slotserve set-admin <用户名>
docker compose exec slotserve slotserve set-admin <用户名> --revoke
docker compose exec slotserve slotserve doctor                   # 运行健康检查（有错误时退出码为 1）
docker compose run --rm --no-deps slotserve slotserve restore <备份包>   # 需先停止服务

什么时候用哪个命令，见运维手册。