环境变量参考
变量的命名与密钥约定、来源与生效方式、跨命名空间的指向关系,以及「某个服务的变量在哪」的索引。 逐服务的完整变量表在逐服务手动部署对应的服务小节里——部署时只去那一处。
← 文档索引
配置约定
命名规则
本系统不使用 NEXT_PUBLIC_ 前缀。 如果您在找它,说明这里被当成了普通的 Next.js 应用——
那会让同一个镜像没法用不同配置跑不同实例。环境变量分两级,区别在于值是否需要到达浏览器:
| 级别 | 命名 | 读取方式 | 例子 |
|---|---|---|---|
| 服务端专用 | SCREAMING_SNAKE_CASE |
process.env.X,只读在服务端 |
DATABASE_URL、SITE_DOMAIN |
| 需要给前端 | camelCase |
经服务端白名单转发到浏览器 | googleClientId、staticCdnUrl |
判断标准不是"运行时还是构建时",而是可见性。同一个运行时值,服务端用的写大写下划线, 浏览器要用的写小驼峰。
密钥类
| 变量 | 说明 |
|---|---|
JWT_PRIVATE_KEY / JWT_PRIVATE_KEY_PATH |
ES256 签名私钥,仅 themis-auth 持有 |
JWT_PUBLIC_KEY / JWT_PUBLIC_KEY_PATH |
ES256 验签公钥,各 gateway 持有 |
IDP_SESSION_SECRET |
会话签名,必填且无默认值,与其他密钥无关 |
JWT_SIGN_ALGORITHM / JWT_VERIFY_ALGORITHM |
默认 ES256 |
密钥一律通过 Kubernetes Secret 注入,或用
_PATH变体指向挂载的文件。 不要把密钥写进 Bundle 的runtimeVariables——那里是明文。因此在 Bundle 中,密钥只以
secretName/secretKey的引用形式出现, 导入前需要先在目标命名空间创建对应的 Secret,见「路径 A / 导入前准备」的 ④。
变量表在哪
每个服务的完整变量表只有一处:逐服务手动部署里该服务小节紧跟「环境变量」的那张表。 它同时给出「来源」(字面量 / ConfigMap / Secret)与占位/默认值,可以直接照着建 ConfigMap 与 Secret。 本文其余部分只讲所有服务共用的规则,以及变量之间的指向关系。
变量与 Bundle 参考:范围与约定
本文不含任何环境数据。 所有主机、域名、端口、仓库地址、账号、密钥、Webhook、Secret 名一律写成占位符 (
<...>)。要核对某个环境的真实取值,请直接看该环境对应 Deployment 的env、ConfigMap 与 Secret, 不要把真实值抄回本文。部署步骤见 install-bundle.md,升级与回滚见 operations.md。
1.1 覆盖范围
| 部分 | 内容 |
|---|---|
| PackingTable | operator 自身的运行变量、启动时安装哪些 CRD、权限要求 |
| rhea | rhea-email / rhea-payment / rhea-push / rhea-gateway / rhea-web |
| themis | themis-auth / themis-gateway / themis-web |
| thia | thia-web / thia-gateway / thia-agent / 5 个 MCP 服务 / thia-jobs-tick |
| tethys | tethys-shipping / tethys-gateway / tethys-web |
| Bundle | fewbox.com/v1 的 Bundle 字段、镜像拼装、reconcile、删除、导入导出与已知限制 |
示例拓扑是「一个集群、四个产品命名空间」,四个命名空间里用 Service 短名互访。把某个产品拆到独立集群时, 变量名和取值规则不变,只是把短名换成对应集群的可达地址。
1.2 变量的来源
服务小节里的「来源」一列只有三种值:
| 来源 | 含义 | 改动后如何生效 |
|---|---|---|
| 字面量 | 直接写在 Deployment 的 env 里 |
改 Deployment,滚动重启 |
| ConfigMap | 通过 valueFrom.configMapKeyRef 或 envFrom 注入 |
改 ConfigMap,再重启 Pod(env 不会热更新) |
| Secret | 通过 valueFrom.secretKeyRef 注入 |
改 Secret,再重启 Pod;不要把 Secret 内容写进 ConfigMap 或镜像 |
「必填」指这套拓扑能跑起来所需,不是代码层面的硬性校验。标为「可选」的变量留空时,服务应按自身默认值降级。
1.3 各服务都有的通用变量
| 变量 | 说明 | 占位/默认 |
|---|---|---|
PORT |
容器监听端口。必须与 Service 的 targetPort、探针端口一致 |
按服务约定,例如 3000 |
NODE_ENV |
production / development。影响日志详细度、错误回显和少数本地回退 |
production |
LOG_LEVEL |
debug / info / warn / error |
info |
SERVICE_NAME |
日志与链路追踪里的服务标识 | 服务名,例如 <product>-<service> |
SHUTDOWN_TIMEOUT |
收到 SIGTERM 后等待在途请求的毫秒数。长任务服务(如 agent)要调大,但必须小于 Pod 的 terminationGracePeriodSeconds,否则收尾没结束就被 SIGKILL |
30000 |
Node 服务默认都读这套变量;.NET 服务(Shipping / PackingTable)只读 PORT,其余用自身配置。
并非每个服务都用到全部五项——以各服务小节的实际表格为准。
1.4 命名与「会不会进浏览器」
- 服务端变量用
SCREAMING_SNAKE_CASE,Secret 变量名通常带_KEY/_TOKEN/_SECRET后缀。 - Next.js 前端有两层配置,都是运行期读取(没有任何
NEXT_PUBLIC_,一个镜像服务多个品牌), 名字风格不同不是笔误:- 只服务端读(
SCREAMING_SNAKE_CASE,直接process.env.X):PORT、SITE_DOMAIN、API_DOMAIN、OIDC 密钥等。改值重启 Pod 即可,不用重建镜像。 - 要下发到浏览器(服务端读出来,经
/api/config与 SSR 首屏):endpoint、wsEndpoint、googleClientId、ssoProviders等保持 camelCase——它们会原样成为前端配置对象上的属性名。
- 只服务端读(
- 凡经
/api/config下发的值都会进浏览器,一律不能放密钥。 密钥只放服务端变量或 Secret keyRef。 - Secret 命名建议
<服务>-<用途>,变量名与 Secret 内的 key 同名,便于对照;本文只用<service>-<purpose>这类占位符举例。 - 不建议用
envFrom把整个 Secret 注入:一旦 Secret 里多了无关键,会顺带进入进程环境。
逐服务变量索引
| 产品线 | 服务 | 变量表位置 | 备注 |
|---|---|---|---|
| rhea | rhea-email |
install-manual.md | |
| rhea | rhea-payment |
install-manual.md | DATABASE_URL 缺失会静默走内存 |
| rhea | rhea-push |
install-manual.md | VAPID 三件套仅 Web Push 需要 |
| rhea | rhea-gateway |
install-manual.md | CORS 精确匹配、无通配 |
| rhea | rhea-web |
install-manual.md | rheaGateway / themisGateway 是 Tier 2 |
| themis | themis-auth |
install-manual.md | 唯一的密钥签发方 |
| themis | themis-gateway |
install-manual.md | 五条 OIDC 端点须显式 publicPath |
| themis | themis-web |
install-manual.md | 同源透传层,无策略 |
| thia | thia-agent |
install-manual.md | 多数配置在 agentic.yaml,env 只做 ${VAR} 插值 |
| thia | thia-gateway |
install-manual.md | 五张代理表,解析失败静默退空数组 |
| thia | thia-web |
install-manual.md | 分服务端 / 客户端两组表 |
| thia | mcp-* |
install-manual.md | 五个服务共用 MCP_TRANSPORT / PORT / LOG_LEVEL |
| thia | thia-jobs-tick |
install-manual.md | CronJob,无环境变量 |
| tethys | tethys-shipping |
install-manual.md | 集群内不用 kubeconfig |
| tethys | tethys-gateway |
install-manual.md | WS_PROXIES 逐条精确匹配 |
| tethys | tethys-web |
install-manual.md | endpoint / wsEndpoint 必须写公网地址 |
| — | PackingTable | 见下文「PackingTable 自身」 | operator 不是 Path-B 服务 |
PackingTable 自身
PackingTable 是用 KubeOps 写的 operator,监听 fewbox.com/v1 的 CR。它通常以单副本 Deployment 运行,
用集群内的 ServiceAccount 访问 apiserver,不需要挂 kubeconfig;因为要安装 CRD、跨命名空间创建资源,
该 ServiceAccount 需要 cluster 级权限(cluster-admin 或等价的 ClusterRole/ClusterRoleBinding)。
启动时会做两件事:
- 读取
fewbox.com/v1的实体类型,转译成 CRD 并保存(已存在则更新 schema),并给 CRD 打上brand=fewbox标签。权限不足时只记录告警,按「CRD 已预装」继续运行。 - 注册四个 controller/finalizer:Tenant、Infrastructure、Middleware、Bundle。
注意:
Registry(fewbox.com/v1,cluster-scoped)不在 operator 自装的四个 CRD 里。它由平台侧预装, operator 只在物化镜像拉取凭证时读取它。
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | operator 监听端口;Docker 镜像默认 8080 | 8080 |
K8S_ENDPOINT |
本地 .env |
仅本地运行 | 本地跑 operator 时连的 apiserver 地址 | https://<k8s-api> |
K8S_TOKEN |
本地 .env |
仅本地运行 | 本地运行时的访问凭据;集群内不要配,走 ServiceAccount | <k8s-token> |
ASPNETCORE_URLS |
本地环境 | 仅本地运行 | 覆盖监听地址,常用于避开已占用端口 | http://localhost:5299 |
本地运行方式:在 PackingTable 目录放一个 .env(K8S_ENDPOINT / K8S_TOKEN),然后
ASPNETCORE_URLS=http://localhost:5299 dotnet run。本地进程和集群内的 operator 不要同时跑同一个集群,
否则同一份 CR 会被两个 reconciler 来回处理。
跨命名空间的指向关系
| 调用方 | 被调用方 | 使用的变量 |
|---|---|---|
| thia-web | thia-gateway | endpoint、wsEndpoint |
| thia-web | themis-gateway / rhea-gateway | themisEndpoint(用户档案)、rheaEndpoint(余额·流水·套餐·结算)、rheaConsoleUrl(跳计费台,不配则不渲染链接) |
| thia-gateway | thia-auth / thia-agent,以及 rhea-payment(仅 /webhooks/stripe 透传) |
AUTH_ENDPOINT、AGENT_ENDPOINT、PAYMENT_ENDPOINT 与各类 *_PROXIES |
| thia-agent | mcp-* | VISION_ENDPOINT、MOTION_ENDPOINT、PERCEPTION_ENDPOINT、ANALYSIS_ENDPOINT |
| tethys-web | tethys-gateway | endpoint、wsEndpoint |
| tethys-gateway | tethys-shipping | SHIPPING_ENDPOINT、SHIPPINGWS_ENDPOINT |
| themis-web | themis-gateway | GATEWAY_ENDPOINT |
| themis-gateway | themis-auth | AUTH_ENDPOINT、AUTH_OIDC_ENDPOINT |
| themis-auth | rhea-email / rhea-payment / rhea-push | EMAIL_SERVICE_URL、PAYMENT_SERVICE_URL、PUSH_SERVICE_URL、PUSH_SERVICE_TOKEN |
| rhea-payment | themis-auth(校验会话) | IDP_SESSION_SECRET |
| rhea-gateway | themis-auth / rhea-payment | AUTH_ENDPOINT、PAYMENT_ENDPOINT |
| rhea-web | rhea-gateway / themis-gateway | rheaGateway、themisGateway |
⚠️ 两种地址写法不要混:
*_ENDPOINT是 JSON(protocol/host/port/basePath),*_SERVICE_URL是一条完整 URL(含路径,如http://rhea-email/api/v1/email/send)。 填反了不会在启动时报错,只在真正调用时静默失败。
两个密钥必须跨服务同值:
IDP_SESSION_SECRET:themis-auth 签发,themis-gateway 与 rhea-payment 解析。三处任一不同,表现为「登录成功但 gateway 认为未登录」或支付页拿不到用户。- themis-auth 的 JWT 签名密钥对:auth 用私钥签,所有 gateway 用公钥验。公钥与当前 kid 必须来自同一对密钥,
否则每个请求都返回
Access Denied: invalid signature。公钥可以从 auth 的/jwks换算成 PEM。