切换主题
环境变量参考
本页列出平台读取的环境变量。修改后重新启动或重新创建容器；配置不支持热更新。
服务与数据库
| 变量 | 默认值 | 用途 |
|---|---|---|
| SPARKTIDE_BIND | 127.0.0.1 | HTTP 监听地址；Dockerfile 设置为 0.0.0.0 |
| PORT | 8080 | HTTP 端口 |
| SPARKTIDE_DB_URL | jdbc:h2:file:./data/sparktide;DB_CLOSE_ON_EXIT=FALSE | JDBC URL；生产改 PostgreSQL |
| SPARKTIDE_DB_USER | sa | 数据库账户 |
| SPARKTIDE_DB_PASSWORD | 空 | 数据库口令 |
| SPARKTIDE_ADMIN_TOKEN | 空 | 平台管理员凭据，至少 32 字符；为空时不启用该管理员入口 |
| SPARKTIDE_CLUSTERED | false | 多实例协调模式；所有同库实例必须一致 |
| SPARKTIDE_MAX_RUNS | 8 | 最大并发运行数，1–128 |
| SPARKTIDE_EVENT_RETENTION_HOURS | 168 | 事件可读取小时数，1–8760；不代表自动删除 |
出站访问与密钥
| 变量 | 默认值 | 用途 |
|---|---|---|
| SPARKTIDE_ALLOWED_ORIGINS | 空 | 允许平台访问的精确 origin，逗号分隔 |
| SPARKTIDE_SECRET_NAMES | 空 | 可被 secretRef 引用的环境变量名，逗号分隔 |
| SPARKTIDE_SECRET_ORIGINS | 空 | 变量名=origin 的绑定，逗号分隔 |
| SPARKTIDE_ALLOW_HTTP | false | 是否允许非 TLS 出站连接；正式服务保持 false |
| MODEL_API_KEY | 无内置值 | Compose 默认注入的模型密钥；名称由 secretRef 约定 |
origin 形如 https://model.example.com 或带非默认端口的 https://business.example.com:9443，不包含路径，不支持通配符。endpoint 另外填写完整路径。密钥必须同时在名称白名单和对应 origin 绑定中，否则注册或执行失败。
出站默认禁止重定向。不要通过关闭 TLS 校验处理证书错误；应修正证书链或实际服务地址。
模型健康与恢复
Compose 已显式注入以下变量。自动恢复默认关闭；启用后仅探测等待恢复的模型，不定时调用健康模型。合成探测可能产生供应商费用，所有实例应使用一致的策略。应用暂停或归档期间不发送探测请求。
| 变量 | 默认值 | 有效范围与用途 |
|---|---|---|
| SPARKTIDE_MODEL_FAILURE_THRESHOLD | 3 | 1–20；窗口内故障隔离阈值 |
| SPARKTIDE_MODEL_FAILURE_WINDOW_SECONDS | 60 | 10–3600；故障统计窗口 |
| SPARKTIDE_MODEL_OPEN_SECONDS | 30 | 1–3600；隔离后的恢复等待时间 |
| SPARKTIDE_MODEL_PROBE_INTERVAL_SECONDS | 30 | 10–3600；同一模型最短探测间隔 |
| SPARKTIDE_MODEL_PROBE_TIMEOUT_SECONDS | 5 | 1–10；单项探测超时 |
| SPARKTIDE_MODEL_PROBES_PER_MINUTE | 6 | 1–60；每个应用每分钟探测次数 |
| SPARKTIDE_MODEL_AUTO_PROBE | false | 是否启用后台恢复探测 |
操作、证据、费用和故障处理见模型健康探测与恢复。
OIDC 身份
SPARKTIDE_OIDC_ISSUER、SPARKTIDE_OIDC_JWKS_URI、SPARKTIDE_OIDC_AUDIENCE 默认空，启用时三项同时配置。角色与声明要求见应用与权限。
Compose 与独立 Jar 的区别
独立 Jar 可直接读取进程环境。Compose 只把 environment 或 env_file 明确注入的值传入容器；.env 中存在的任意变量不一定进入容器。调整并发、事件窗口或新增密钥时，同时检查 Compose 的 environment。
保持当前运行配置的受控清单，但清单不包含真实密钥。使用 /actuator/health、实际 API 与服务日志验证配置生效，避免把环境文件存在当作已生效。
密钥所属应用授权
SPARKTIDE_SECRET_APPLICATIONS 显式指定密钥允许的能力所属应用，例如 MODEL_API_KEY=global,DEVICE_KEY=monitor;maintenance。与名称白名单和 origin 绑定同时生效；未授权返回 SECRET_SCOPE_DENIED。global 不是通配符。升级前必须盘点现有 secretRef，详见 运行治理与执行核对。
文件摄入与 OCR
| 变量 | 默认 | 约束与用途 |
|---|---|---|
| SPARKTIDE_INGESTION_CAPACITY_BYTES | 67108864 | 原件字节额度 4 MiB–1 GiB；数据库 Base64 与解析/索引开销另计 |
| SPARKTIDE_DOCUMENT_PARSER | builtin | 运维部署的 ServiceLoader 标识，不接收上传输入选择代码 |
| SPARKTIDE_OCR_EXECUTABLE | 宿主空；镜像 /usr/bin/tesseract | 宿主需配置绝对可执行路径；未配置时扫描页/图片明确失败 |
| SPARKTIDE_OCR_LANGUAGES | 宿主 eng；镜像 eng+chi_sim | 必须已安装对应语言包 |
| SPARKTIDE_INGESTION_AUTO | true | 自动协调持久任务；生产保持启用 |
独立解析进程与 OCR 的内存另计，不能只限制主 Java 堆。资源上限、原件清理和状态恢复见文件摄入。
向量索引配置
| 变量 | 默认值 | 用途 |
|---|---|---|
| SPARKTIDE_VECTORS_AUTO | true | 自动协调持久向量构建任务；false 时不启动任务 worker |
| SPARKTIDE_VECTORS_CAPACITY_BYTES | 67108864 | 向量持久容量，允许 1 MiB–1 GiB；不足时拒绝提交，不替换部分索引 |
Embedding origin 与 Secret 仍按应用/运营者出站配置授权，操作见向量与混合检索。
调用链采集与出口
| 变量 | 默认 | 约束 |
|---|---|---|
| SPARKTIDE_TRACE_RETENTION_HOURS | 168 | 1–8760；到期只清理调用链元数据 |
| SPARKTIDE_TRACE_CAPACITY | 100000 | 1000–1000000；全库 Span 上限 |
| SPARKTIDE_TRACE_SAMPLE_PERCENT | 100 | 0–100；进程指标独立于采样 |
| SPARKTIDE_OTLP_ENDPOINT | 空 | 可选 Collector 完整 HTTPS URL，路径以 /v1/traces 结尾 |
| SPARKTIDE_OTLP_ORIGINS | 空 | 独立精确 origin 白名单，逗号分隔 |
| SPARKTIDE_OTLP_TOKEN | 空 | Collector Bearer，由环境 secret 注入 |
详见可观测性与调用链。配置更新后重启，不在业务后台或浏览器暴露 Collector 凭据。