逐服务手动部署
路径 A 的展开视图:每个服务一份清单,适合审计、定制,以及「Bundle apply 成功但没起来」时的逐项排查。
← 文档索引
路径 B:逐服务手动部署
这条路用于排障、定制和安全审计。每个服务一节,末尾标注它在 Bundle 里对应哪个 pack,
方便两条路径互相对照。
小节按依赖顺序排列:Rhea → Themis → Theia → Tethys(可选)。每个服务先说明它做什么, 再给需要准备的东西。所有 Service 名就是配置里填的 host。
小节名基本就是集群里的对象名,它们都带产品线标签 fewbox.com/family
(例外:mcp-* 是五个 mcp 服务的合集,thia-jobs-tick 是 CronJob)。
想知道某条线在当前集群里到底有哪些 Deployment,按标签查即可:
kubectl get deploy -n <您的命名空间> -l fewbox.com/family=thia
标签值可取 thia / themis / rhea / tethys / phoebe。Mnemosyne 没有独立服务——
它运行在 thia-agent 里,等它拆出来才会带上自己的标签值。
Rhea:基础服务
rhea-email
作用:事务性邮件——注册验证、密码重置、通知。它只负责投递,"什么时候发"由调用方决定;
themis-auth 通过 EMAIL_SERVICE_URL 调它。
清单:一个 Deployment(无状态、无 PVC)+ 一个 ClusterIP Service,端口按惯例 80 → 3000。
探针打 GET /api/v1/livez 与 GET /api/v1/readyz——注意路径在 /api/v1 下面(rhea-payment
的两条探针反过来挂在根路径,抄配置时别照搬)。不要挂公网 Ingress:它没有任何鉴权,
能连上就能发信,而唯一合法的调用方在集群内。
前置:一个可用的 SMTP 账号。没有 SMTP 也能启动成功——SMTP_HOST 缺省时会退回
smtp.example.com,进程不报错,只是每封信都发不出去;探针也发现不了,因为它们只看进程。
环境变量
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | 服务端口 | 3006 |
NODE_ENV |
字面量 | 是 | 运行环境 | production |
LOG_LEVEL |
ConfigMap | 可选 | 日志级别 | info |
SERVICE_NAME |
ConfigMap | 可选 | 日志/链路服务名 | <product>-email |
SHUTDOWN_TIMEOUT |
ConfigMap | 可选 | 优雅退出等待(毫秒) | 30000 |
SMTP_HOST |
ConfigMap | 是 | SMTP 服务器。留空退回 smtp.example.com 且不报错,见上 |
smtp.<provider> |
SMTP_PORT |
ConfigMap | 是 | SMTP 端口 | 587 |
SMTP_SECURE |
ConfigMap | 是 | true 为隐式 TLS(通常 465),false 为 STARTTLS(通常 587) |
false |
SMTP_FROM |
Secret | 是 | 发件地址;真实邮件服务里它通常不是登录账号,留空则取 SMTP_USER |
[email protected] |
SMTP_USER |
Secret | 是 | SMTP 登录名或 API key | <user> |
SMTP_PASS |
Secret | 是 | SMTP 密码或 API key | <password> |
调用方配置
# 地址要写到方法级:themis-auth 直接 POST 这个 URL,不会自己拼路径
EMAIL_SERVICE_URL=http://rhea-email/api/v1/email/send
请求体 { "to", "subject", "body" },body 是 HTML。投递失败会返回非 2xx——themis-auth 据此
经 rhea-push 给运维发提醒,但注册/重置密码的响应照旧,不让外部看出邮件没发出去。
对应 Bundle pack:app: rhea-email
rhea-payment
作用:支付、订阅与积分账本。注册时 themis-auth 经 PAYMENT_SERVICE_URL 调它发放赠送积分;
对话消耗与结算也记在这里。
清单:一个 Deployment + 一个 ClusterIP Service(80 → 3000)+ 一个 PostgreSQL 库。
探针打 GET /livez / GET /readyz,这两条挂在根路径(rhea-email 的探针在 /api/v1 下,
两者不一样)。同样不挂公网 Ingress;对外只有两条合法入口:rhea-gateway 的 GraphQL,
以及 thia-gateway 的 POST_PROXIES 把 Stripe 回调透传进来。
⚠️
DATABASE_URL缺失不会报错。 进程照常启动、界面照常有余额,因为它悄悄换成了内存仓储: 重启即清零,库里一条记录都没有。新环境先确认这一项,再看一笔真实入账。
数据库
五张表,建表脚本全文见数据库表结构。其中 credit_transactions.event_id
的唯一约束是幂等的地基,缺了同一笔支付可能重复入账。套餐目录是另一段可选的种子,见同一页的
「套餐目录」一节。
入账永远按 credit_packages.credits 发放,不按支付金额换算;折扣只体现在 price_minor 上。
环境变量
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | 服务端口 | 3000 |
NODE_ENV |
字面量 | 是 | 运行环境 | production |
SERVICE_NAME |
ConfigMap | 可选 | 日志/链路服务名 | <product>-payment |
SHUTDOWN_TIMEOUT |
ConfigMap | 可选 | 优雅退出等待(毫秒) | 30000 |
DATABASE_URL |
Secret | 是 | PostgreSQL 连接串。空值静默走内存,见上 | postgres://<user>:<pass>@<host>:5432/<db> |
STRIPE_SECRET_KEY |
Secret | 用 Stripe 时必填 | 服务端密钥 | sk_<env>_... |
STRIPE_WEBHOOK_SECRET |
Secret | 用 Stripe 时必填 | 校验回调签名;缺了回调一律被拒 | whsec_... |
STRIPE_API_VERSION |
ConfigMap | 可选 | 固定 Stripe API 版本,建议填,避免 SDK 升级后行为漂移 | <version> |
STRIPE_RETURN_URLS |
ConfigMap | 用 Stripe 时必填 | 多站点回跳表,JSON:{"<site>":{"success":"<url>","cancel":"<url>","portal":"<url>"}}。格式不对启动即失败(故意不兜底,免得把用户退回别的站点);调用方用 site 选站点,未知站点 400 |
<json> |
STRIPE_CHECKOUT_SUCCESS_URL |
ConfigMap | 可选 | 老的单站点写法,请求不带 site 时兜底 |
<url> |
STRIPE_CHECKOUT_CANCEL_URL |
ConfigMap | 可选 | 同上 | <url> |
STRIPE_PORTAL_RETURN_URL |
ConfigMap | 可选 | 同上,自助退订 / 换卡 / 发票的回跳 | <url> |
PAYPAL_CLIENT_ID |
ConfigMap | 用 PayPal 时必填 | 公开值 | <client-id> |
PAYPAL_CLIENT_SECRET |
Secret | 用 PayPal 时必填 | 回调经 /webhooks/paypal |
<secret> |
PAYPAL_WEBHOOK_ID |
Secret | 用 PayPal 时必填 | Webhook 校验 ID | <webhook-id> |
PAYPAL_API_BASE |
ConfigMap | 可选 | 默认 sandbox;生产改成 https://api-m.paypal.com |
https://api-m.<env>.paypal.com |
CURRENCY_RATES |
ConfigMap | 可选 | 汇率表;不填或填错都用内置默认值(填错会在日志里 warn) | <json> |
IDP_SESSION_SECRET |
Secret | 是 | 与 themis-auth 同值,用于解析会话 cookie | <random-string> |
单站点部署用 STRIPE_CHECKOUT_* 三个变量,多站点用 STRIPE_RETURN_URLS,两者不必同时设置。
接口(除探针外都在 /api/v1 下)
| 方法 | 路径 | 谁在用 |
|---|---|---|
GET |
/packages |
套餐目录,前端定价页 |
POST |
/checkout |
一次性购买,建 Stripe Checkout 会话 |
POST |
/subscribe |
订阅;请求带 site 决定回跳到哪个站点 |
POST |
/me/subscription/portal |
自助退订 / 换卡 / 发票 |
GET |
/me/credits/balance、/me/credits/transactions |
当前用户的钱包与流水 |
POST |
/me/credits/transfer |
把积分转给组织或个人 |
POST |
/credits/topup、/credits/deduct |
管理操作(加扣),对外只经网关的 ADMIN 字段 |
POST |
/webhooks/stripe、/webhooks/paypal |
支付回调。公网入口在 thia-gateway 的 /webhooks/stripe,由它透传到这里 |
对应 Bundle pack:app: rhea-payment
rhea-push
作用:把通知投递到用户自己配置的目标——飞书 / Slack / Discord 的 incoming webhook,
或浏览器 Web Push。它只负责传输,不存地址簿;"发给谁"由 thia / tethys 按用户的
NotificationChannel 决定,通过 PUSH_SERVICE_URL 调用。与 rhea-email 的分工相同:
平台服务只管投递,业务服务决定时机与内容。
它是纯内部服务:只建 ClusterIP Service,不要挂公网 Ingress,也没有用户界面。
入站流量只有集群内的后端服务;出站才是用户配置的 webhook 或推送服务。因此
PUSH_SERVICE_TOKEN 仍必须设置——内部网络不等于可信网络,而这个接口的语义是
「给我一个地址我就 POST」。
前置:一个共享服务令牌。只有用 Web Push 时才需要 VAPID 密钥。
① 生成 VAPID 密钥(仅 Web Push,只用 webhook 时跳过)
npx web-push generate-vapid-keys
公钥可以下发到前端用于订阅,私钥只放 Secret,不要写进镜像、Bundle 或代码。
② 环境变量
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | 服务端口(与同族 Rhea 服务一致;本地调试常用 3007 错开 themis-web) | 3000 |
NODE_ENV |
字面量 | 是 | 运行环境 | production |
LOG_LEVEL |
ConfigMap | 可选 | 日志级别 | info |
SERVICE_NAME |
ConfigMap | 可选 | 日志/链路服务名 | <product>-push |
SHUTDOWN_TIMEOUT |
ConfigMap | 可选 | 优雅退出等待(毫秒) | 30000 |
PUSH_SERVICE_TOKEN |
Secret | 是 | 调用方用 Authorization: Bearer <令牌>。留空等于免鉴权,生产禁止 |
<random-string> |
PUSH_MAX_ATTEMPTS |
ConfigMap | 可选 | 投递重试次数 | 3 |
PUSH_RETRY_BASE_DELAY_MS |
ConfigMap | 可选 | 重试基础退避(毫秒) | 300 |
PUSH_TIMEOUT_MS |
ConfigMap | 可选 | 单次投递超时(毫秒) | 8000 |
PUSH_TTL_SECONDS |
ConfigMap | 可选 | 消息有效期 | 3600 |
PUSH_TARGET_ALLOW_HTTP |
ConfigMap | 可选 | 是否允许 http 目标。非生产环境代码默认为 true,生产必须显式设 false |
false |
PUSH_TARGET_ALLOW_PRIVATE_NETWORKS |
ConfigMap | 可选 | 是否允许访问回环 / 私网 / 链路本地 / 云 metadata 地址;生产必须为 false |
false |
PUSH_TARGET_ALLOWED_HOSTS |
ConfigMap | 建议 | 允许的目标主机白名单,逗号分隔,含子域,如 open.feishu.cn,hooks.slack.com;留空为任意公网 |
<host1>,<host2> |
PUSH_VAPID_SUBJECT |
ConfigMap | 否(Web Push 时必填) | mailto:<运维邮箱> 或站点 URL |
mailto:<ops> |
PUSH_VAPID_PUBLIC_KEY |
Secret | 否(Web Push 时必填) | 公钥可下发到前端用于订阅 | <vapid-public> |
PUSH_VAPID_PRIVATE_KEY |
Secret | 否(Web Push 时必填) | 不配置时 webpush 渠道返回 503,webhook 不受影响 | <vapid-private> |
③ 调用方配置
# Service 端口按统一惯例是 80 → targetPort 容器端口;两个侧面的令牌同名同值。
PUSH_SERVICE_URL=http://rhea-push/api/v1/push/send
PUSH_SERVICE_TOKEN=<与 rhea-push 侧同名同值>
webhook URL 本身就是凭证——拿到的人就能往那个频道发消息。服务日志只记录脱敏后的 host 与路径末尾,不会出现完整地址;订阅失效(404 / 410)由调用方负责删除对应渠道。
对应 Bundle pack:app: rhea-push(待加入 Bundle)
rhea-gateway
作用:Rhea 唯一的 GraphQL 入口——积分钱包与账本、订阅、套餐目录、支付事件与 Stripe 映射
全部经它读写。它不碰数据库、也没有用户表:账单与积分问 rhea-payment,「这个人是谁、
属于哪个组织」问 themis-auth。
浏览器 → rhea-web(管理台)
→ rhea-gateway(验签 + 权限 + 聚合) → rhea-payment(账本本体)
↘ themis-auth(身份与组织)
它是 Rhea 里唯一需要暴露到公网的组件。产品站的浏览器直接请求它的 /graphql(公开定价页
也读它),所以 CORS 必须逐个列出这些站的真实 origin:cors() 收的是精确匹配数组,
没有子域通配。漏掉一个的失败是静默的——请求照常返回,但响应里没有
Access-Control-Allow-Origin,前端只会看到「余额为空」或「套餐目录退回内置值」,看起来像
数据问题而不是部署问题。
前置:rhea-payment 与 themis-auth 可达;themis-auth 的 ES256 公钥。
环境变量
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | 服务端口 | 3000 |
PAYMENT_ENDPOINT |
ConfigMap | 是 | rhea-payment 地址,JSON。缺失时进程直接拒绝启动(不留「目录为空」这种假象) |
{"protocol":"http","host":"rhea-payment","port":80,"basePath":"api/v1"} |
AUTH_ENDPOINT |
ConfigMap | 是 | themis-auth 地址,同格式。组织钱包的 owner 校验要读 organizations |
{"protocol":"http","host":"themis-auth","port":80,"basePath":"api/v1"} |
JWT_PUBLIC_KEY_PATH |
Secret(文件) | 是 | themis-auth 公钥 PEM,推荐以文件挂载。只接受 ES256,没有 HS256 兜底;缺失同样启动即失败 | /etc/jwt/public.pem |
JWT_PUBLIC_KEY |
Secret | 否 | 同上,内联形式(\n 转义)。与上一行二选一 |
<pem> |
CORS |
ConfigMap | 是 | JSON 数组、精确匹配,没有子域通配:["https://<console>","https://<site>"]。漏一个 → 请求 200 但没有 Access-Control-Allow-Origin |
[] |
AJAX_TIMEOUT_MS |
ConfigMap | 可选 | 上游超时(毫秒) | 30000 |
PROXY |
ConfigMap | 可选 | 出口代理,与产品站同一套;设置了会同时写进 HTTP(S)_PROXY |
<url> |
权限上只有 creditPackages 匿名可读(公开定价页用),其余要求登录,管理类字段还要 ADMIN。
对应 Bundle pack:app: rhea-gateway
rhea-web
作用:计费管理台,四个只给 ADMIN 的视图——套餐目录(含改价、下架)、支付事件、Stripe
映射、钱包(余额 / 流水 / 加扣)。它自己不持有任何数据:读写走 rhea-gateway;Stripe 映射页的
用户选择器读 themis-gateway(身份不是 Rhea 的,Rhea 网关里刻意没有 users 查询)。
登录:它是 accounts.titanides.com 的 OIDC 依赖方(公共客户端 + PKCE)。与 themis-web 不同,
它和 IdP 不同源,所以走 /api/auth/start → /api/auth/callback 由服务端换码——refresh token 只
进 HttpOnly cookie,浏览器拿到的 access token 只活在内存里,没有任何令牌会落到 JavaScript 可读处。
前置:rhea-gateway 有公网地址(浏览器直连);themis-gateway 可达;IdP 侧登记了这个客户端
(OIDC_CLIENTS,回调形如 https://console.titanides.com/api/auth/callback)。
环境变量
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | Next 服务端口 | 3000 |
rheaGateway |
ConfigMap | 是 | Tier 2(进 /api/config):浏览器直连的网关地址,JSON,无 basePath |
{"protocol":"https","host":"rhea-gateway.titanides.com"} |
themisGateway |
ConfigMap | 是 | Tier 2:Stripe 映射页的用户选择器用,格式同上 | {"protocol":"https","host":"themis-gateway.titanides.com"} |
RHEA_OIDC_ISSUER |
ConfigMap | 是 | IdP 的 issuer | https://accounts.titanides.com |
RHEA_OIDC_CLIENT_ID |
ConfigMap | 是 | 公共客户端(PKCE,无 secret),须在 IdP 的 OIDC_CLIENTS 里登记 |
rhea-web |
RHEA_OIDC_REDIRECT_URI |
ConfigMap | 是 | 与登记值精确一致 | https://<console>/api/auth/callback |
AUTH_FLOW_TOKEN |
Secret | 是 | 签名登录流程 cookie(state/nonce/PKCE)。生产环境无默认值,不填时 /api/auth/token 返回 503 not_configured |
<random-string> |
AUTH_SESSION_TOKEN |
Secret | 是 | 加密 HttpOnly 会话 cookie;必须与上一行不同,所有副本同值;生产环境同样无默认值 | <random-string> |
rheaGateway / themisGateway 是 Tier 2 键(进 /api/config 与 SSR 首屏,浏览器要用),
OIDC 那几个是 Tier 1(只服务端读)。两个网关的 CORS 都要列出本站 origin,否则 Stripe
映射页的用户搜索会被浏览器拦掉。
对应 Bundle pack:app: rhea-web
Themis:身份
三个服务是链式的,按 auth → gateway → web 的顺序装:后一个要填前一个的 Service 地址。
浏览器 → themis-web(登录页 + 同源透传) → themis-gateway(验签 + 转发) → themis-auth(真身份)
如果要把这套身份作为独立 OIDC 服务接给其它应用,配置、接入流程与验收清单见 「Themis 作为独立 OIDC 服务」。
themis-auth
作用:整套系统唯一的身份源。注册、登录(用户名密码 / Google / 企业 SSO)、签发与刷新
access token;对其它子品牌作为 OIDC IdP 提供 /authorize、/token、/jwks、
/.well-known/openid-configuration 与 /logout(RP 发起的登出,见「Themis 作为独立 OIDC 服务」)。
它不出内网。 只接受来自 themis-gateway 的流量——它的 /users、/roles 管理接口没有自己的
鉴权,边界在网关那一层。
前置:PostgreSQL 可用;rhea-email 可达;一对 ES256 密钥。
① 生成密钥对
openssl ecparam -name prime256v1 -genkey -noout -out jwt-private.pem
openssl ec -in jwt-private.pem -pubout -out jwt-public.pem
② 建表
新库直接跑初始化脚本(11 张表 + 六条角色种子,全文见数据库表结构):
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f themis-auth-init.sql
脚本不建任何用户——装完谁都登录不了。管理员账号要自己注册再绑角色,步骤见同一页的「管理员账号」一节。
③ 配置
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | 服务端口 | 3000 |
NODE_ENV |
字面量 | 是 | 运行环境 | production |
LOG_LEVEL |
字面量 | 可选 | 日志级别 | info |
SERVICE_NAME |
字面量 | 可选 | 日志/链路服务名 | <product>-auth |
SHUTDOWN_TIMEOUT |
字面量 | 可选 | 优雅退出等待(毫秒) | 30000 |
JWT_EXPIRES_IN |
字面量 | 是 | access token 有效期 | 24h |
REFRESH_TOKEN_EXPIRES_IN |
字面量 | 是 | refresh token 有效期;应与会话配置一致 | 7d |
BCRYPT_ROUNDS |
字面量 | 可选 | 密码哈希成本 | 12 |
GOOGLE_CLIENTID |
ConfigMap | 可选 | 启用 Google 登录时才填 | <google-client-id> |
SIGNUP_VERIFY_URL |
ConfigMap | 是 | 注册验证邮件里的回跳地址模板 | https://<web-host>/{locale}/verify-email |
PASSWORD_RESET_URL |
ConfigMap | 是 | 重置密码邮件里的回跳地址模板 | https://<web-host>/{locale}/reset-password |
SIGNUP_BONUS_CREDITS |
ConfigMap | 可选 | 注册赠送额度;0 表示关闭 | 0 |
OIDC_CALLBACK_URL |
ConfigMap | 可选 | 作为 OIDC 客户端登录第三方 IdP 时的统一回调地址,启用企业 SSO 时才填 | https://<accounts-origin>/api/v1/oidc/callback |
SSO_PROVIDERS(别名 OIDC_PROVIDERS) |
ConfigMap | 可选 | 第三方 IdP 注册表,JSON 数组,见下方「企业 SSO」;含 clientSecret 时整段应进 Secret |
[{"key":"<key>","issuer":"<issuer>","clientId":"<id>","clientSecret":"<secret>","scopes":"openid profile"}] |
JWT_SIGN_ALGORITHM |
ConfigMap | 是 | 默认 ES256。不要改成 HS256——那等于把签发权交给每个持密钥的网关 |
ES256 |
JWT_PRIVATE_KEY_PATH |
ConfigMap | ES256 必填 | 私钥 PEM 文件路径(Secret 以文件挂载)。挂成文件比写进环境变量安全 | <path> |
JWT_PUBLIC_KEY_PATH |
ConfigMap | ES256 必填 | 公钥 PEM 文件路径;gateway 用它验签 | <path> |
OIDC_ISSUER |
ConfigMap | 是 | 公网 issuer,如 https://accounts.titanides.com,无尾斜杠;四个 OIDC 端点由它推导 |
https://<accounts-origin> |
OIDC_KEY_ID |
ConfigMap | 是 | JWKS 里的 key id(kid),必须与签名密钥对应 | <kid> |
OIDC_CLIENTS |
ConfigMap | 是 | 允许接入的 RP:client_id、redirect_uris、post_logout_redirect_uris 三份精确白名单,JSON。留空 = 拒绝一切 |
<json> |
LOGIN_URL |
ConfigMap | 是 | 未登录访问 /authorize 时跳转到的登录页 |
https://<web-host>/<locale>/signin |
IDP_SESSION_TTL_SECONDS |
ConfigMap | 可选 | IdP 会话 cookie 有效期 | 604800 |
AUTH_CODE_TTL_SECONDS |
ConfigMap | 可选 | 授权码有效期 | 60 |
ID_TOKEN_EXPIRES_IN |
ConfigMap | 可选 | id_token 有效期 | 1h |
IDP_SESSION_SECRET |
Secret | 是 | 会话 cookie 与流程 state 的封印密钥(或 _PATH 变体)。无默认值,缺失时启动直接失败;themis-gateway 与 rhea-payment 必须同值 |
<random-string> |
DATABASE_URL |
Secret | 是 | PostgreSQL 连接串。与其它服务共用实例时请指定独立 schema 或独立库 | postgres://<user>:<pass>@<host>:5432/<db> |
EMAIL_SERVICE_URL |
ConfigMap | 是 | rhea-email 的地址 |
http://<email-svc>:<port>/api/v1 |
PAYMENT_SERVICE_URL |
ConfigMap | 是 | rhea-payment 的充值端点(完整 URL) |
http://<payment-svc>:<port>/api/v1/credits/topup |
PUSH_SERVICE_URL |
ConfigMap | 可选 | 邮件投递失败告警,与 ALERT_WEBHOOK_URL 同时配置才生效 |
http://<push-svc>:<port>/api/v1 |
PUSH_SERVICE_TOKEN |
Secret | 可选 | 与 rhea-push 共享的服务令牌 |
<token> |
ALERT_WEBHOOK_URL |
Secret | 可选 | 运维群 webhook,凭证,放 Secret | <webhook-url> |
ALERT_WEBHOOK_FORMAT |
ConfigMap | 可选 | raw / feishu / slack / discord,必须与目标渠道匹配 |
raw |
ALERT_WEBHOOK_KEYWORD |
ConfigMap | 可选 | 飞书群机器人开了「自定义关键词」校验时,从机器人设置里原样复制一个关键词(不加引号)。飞书只要命中任意一个就放行,所以填一个即可;机器人没开校验就不填 | <keyword> |
ALERT_COOLDOWN_SECONDS |
ConfigMap | 可选 | 同类告警冷却,默认 60 秒 | 60 |
告警内容只包含邮件类型、脱敏后的收件人(a***@example.com)、错误信息和服务名;
验证/重置链接里的 token 不会进入日志或告警。同一类型在冷却窗口内只发一条,
避免 SMTP 故障时每个注册请求都往群里发一条。
OIDC_CLIENTS 是一个 JSON 数组,每一项就是一个 RP:
[
{
"client_id": "tethys-web",
"redirect_uris": ["https://console.titanides.com/api/auth/callback"],
"post_logout_redirect_uris": ["https://console.titanides.com/"]
}
]
redirect_uris:授权码回跳地址,逐字精确匹配,多一个路径都不行。post_logout_redirect_uris:登出后允许回跳的地址,同样逐字精确匹配,且只能指向公开页面 (通常就是站点根/)。不配时退回到「redirect_uris的同源根」——这是给早期客户端留的 兼容路径;新接入请显式写,否则该域名下的任意路径都能被当作登出回跳地址。- 这些是公共客户端,没有
client_secret;安全性由 PKCE(S256)保证。
JWT_EXPIRES_IN、REFRESH_TOKEN_EXPIRES_IN、IDP_SESSION_TTL_SECONDS、AUTH_CODE_TTL_SECONDS
都有合理默认值,通常不用动。
企业 SSO(auth 作为 OIDC 客户端):用户在企业 IdP(Microsoft Entra、Okta、Keycloak……)的 登录页完成认证,回到本服务后拿到的只是本服务的会话 cookie,随后浏览器被送回原来的页面。厂商差异 全部写在注册表里,代码与 URL 中没有任何厂商特定内容:
[{"key":"entra","issuer":"https://login.microsoftonline.com/<tenant>/v2.0","clientId":"<应用注册的客户端 ID>","clientSecret":"<客户端密钥>","scopes":"openid profile email","claimMapping":{"displayName":"name","orgId":"tid"},"usernamePrefix":"ms"}]
- 旧部署里的
OIDC_PROVIDERS是SSO_PROVIDERS的别名,两者取其一即可。 key:登录页按钮与/api/v1/oidc/start?provider=<key>用的标识。issuer:逐字匹配(含尾斜杠与否要与企业 IdP 的 discovery 一致)。claimMapping:把显示名 / 组织 id / 组织名映射到该厂商的 claim 名;不映射orgId就不会 自动建组织。OIDC_CALLBACK_URL:报给企业 IdP 的唯一回跳地址,例如https://accounts.titanides.com/api/v1/oidc/callback。必须与登录页同源——流程的 state/nonce/PKCE 存在同源 cookie 里,换个域名必然校验失败。
登录完成后只种 fewbox_idp_session 并 302 到调用方给的 return(同源相对路径,缺省 /);
需要 token 的应用走 /authorize 授权码流程,URL 里不传任何凭据。失败则 302 回
LOGIN_URL?sso_error=<原因>&return=<路径>,用户在登录页看到提示后可直接重试。
④ 部署
apiVersion: apps/v1
kind: Deployment
metadata:
name: themis-auth
namespace: <您的命名空间>
spec:
replicas: 1
selector:
matchLabels: { app: themis-auth }
template:
metadata:
labels: { app: themis-auth }
spec:
containers:
- name: themis-auth
image: <您的镜像仓库>/fewbox-themis-auth:<版本>
ports:
- containerPort: 3000
envFrom:
- configMapRef: { name: themis-auth-config }
- secretRef: { name: themis-auth-secret }
volumeMounts:
- name: keys
mountPath: /etc/themis-keys
readOnly: true
readinessProbe:
httpGet: { path: /api/v1/readyz, port: 3000 }
livenessProbe:
httpGet: { path: /api/v1/livez, port: 3000 }
volumes:
- name: keys
secret: { secretName: themis-auth-keys }
---
apiVersion: v1
kind: Service
metadata:
name: themis-auth
namespace: <您的命名空间>
spec:
type: ClusterIP
ports:
- port: 80
targetPort: 3000
selector: { app: themis-auth }
验证:Pod READY;容器内 wget -qO- localhost:3000/api/v1/livez 有返回(探针路径在
/api/v1 下面,写 /livez 会 404,探针一直失败);故意删掉 IDP_SESSION_SECRET 后重启应
起不来——这是刻意的失败姿态,不是缺陷。
对应 Bundle pack:app: themis-auth
themis-gateway
作用:身份域唯一对外入口,做两件事——① 管理 GraphQL(用户 / 角色 / 组织),供管理台使用; ② 把五条 OIDC 端点(含登出)原样转发给 themis-auth,让 auth 始终不出内网。JWT 验签与 ADMIN 门禁也在这一层。
前置:themis-auth 已就绪。
配置
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | 网关端口 | 4004 |
CORS |
ConfigMap | 是 | 允许的来源,JSON 数组 | ["https://<web-host>"] |
AUTH_ENDPOINT |
ConfigMap | 是 | auth 的 REST API(登录/注册/组织/个人资料),JSON,basePath 为 api/v1 |
{"protocol":"http","host":"themis-auth","port":80,"basePath":"api/v1"} |
AUTH_OIDC_ENDPOINT |
ConfigMap | 是 | auth 的 IdP 协议端点(/authorize、/token、/jwks),没有 basePath,在 auth 的根路径 |
{"protocol":"http","host":"themis-auth","port":80} |
JWT_VERIFY_ALGORITHM |
ConfigMap | 是 | 验签算法,必须与 auth 的签名算法一致 | ES256 |
JWT_PUBLIC_KEY_PATH |
ConfigMap | 是 | 与 auth 同一把公钥(PEM 文件路径) | <path> |
REDIRECT_PROXIES |
ConfigMap | 是 | 3xx 透传表:/authorize、/logout、OIDC start/callback、SSO assert |
[{"endpoint":"AUTH_OIDC","path":"authorize","publicPath":"/authorize"}] |
GET_PROXIES |
ConfigMap | 是 | GET 透传表:JWKS、discovery、/me、组织、注册验证等 | [{"endpoint":"AUTH_OIDC","path":"jwks","publicPath":"/jwks"}] |
POST_PROXIES |
ConfigMap | 是 | POST 透传表:token、登录/注册、找回密码、登出(带 clearSessionCookie)、组织成员 |
[{"endpoint":"AUTH","path":"signin/form","publicPath":"/api/v1/signin/form"}] |
PUT_PROXIES |
ConfigMap | 可选 | PUT 透传表:改密码、改资料、改组织 | [{"endpoint":"AUTH","path":"me","publicPath":"/api/v1/me"}] |
DELETE_PROXIES |
ConfigMap | 可选 | DELETE 透传表:注销账号、移除成员 | [{"endpoint":"AUTH","path":"me","publicPath":"/api/v1/me"}] |
IDP_SESSION_SECRET |
Secret | 是 | 与 themis-auth 完全同值;用于解析会话 cookie | <random-string> |
五条端点必须显式写 publicPath:
REDIRECT_PROXIES=[{"endpoint":"AUTH_OIDC","path":"authorize","publicPath":"/authorize"},{"endpoint":"AUTH_OIDC","path":"logout","publicPath":"/logout"}]
POST_PROXIES=[{"endpoint":"AUTH_OIDC","path":"token","publicPath":"/token"}]
GET_PROXIES=[{"endpoint":"AUTH_OIDC","path":"jwks","publicPath":"/jwks"},{"endpoint":"AUTH_OIDC","path":".well-known/openid-configuration","publicPath":"/.well-known/openid-configuration"}]
不写的话默认路径是 /auth_oidc/authorize 这种,OIDC 客户端找不到。
/logout 必须放在 REDIRECT_PROXIES:auth 的响应是 302 加 Set-Cookie(清会话 cookie)。
按普通 GET 代理处理,302 会被当成数据体吞掉,浏览器既收不到跳转,也收不到清 cookie 的指令。
部署:与 auth 同形的 Deployment + ClusterIP Service(80 → 3000),探针 /livez、/readyz。
验证:/.well-known/openid-configuration 返回的 issuer 应等于 OIDC_ISSUER;带一个管理员
token 调 /graphql 查 users,非管理员应被拒。
对应 Bundle pack:app: themis-gateway
themis-web
作用:accounts.titanides.com 的登录页,同时是同源透传层。一个域名只能绑一个服务,所以
/authorize、/token、/jwks、/.well-known、/logout 与 /api/v1/* 由本服务转给
themis-gateway。这一层不做策略,白名单只在网关一处。
配置
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | Next 服务端口 | 3000 |
GATEWAY_ENDPOINT |
ConfigMap | 是 | themis-gateway 地址。只在服务端读取,不进浏览器;没设时协议路径回 502 并写明原因 | http://themis-gateway |
googleClientId |
ConfigMap | 可选 | 与 auth 的 GOOGLE_CLIENTID 同值;留空隐藏按钮 |
<google-client-id> |
ssoProviders |
ConfigMap | 可选 | 按钮元数据 [{"key","label","logoUrl"}],与 auth 的注册表保持一致,不填则对应按钮不渲染。key 必须与 auth 注册表里的 key 对上,label 可以直接写字符串或按语言给对象 |
[] |
部署:Deployment + Service(80 → 3000);边缘把 accounts.titanides.com 指向它。
验证:打开 accounts.titanides.com,走完注册 → 收信 → 验证 → 登录;再直接访问
https://accounts.titanides.com/.well-known/openid-configuration,能拿到文档就说明透传通了。
透传路径是镜像里的固定清单(
app/authorize、app/token、app/jwks、app/.well-known/openid-configuration、app/logout),不是配置项。新增路径只能靠升级镜像 获得——只改网关的REDIRECT_PROXIES、镜像还是旧的,访问/logout会落到 Next 自己的 404。
对应 Bundle pack:app: themis-web
登出链路
退出登录跨三个服务。任何一环缺失,表现都不是「退不出去」,而是更隐蔽的两件事:登出页 404, 或者下次点登录直接静默进去(IdP 会话没被清)。
- 应用侧(如
tethys-web)先删掉 refresh token、拉黑 access token 的jti,清掉浏览器里的 token;然后返回登出地址TETHYS_OIDC_LOGOUT_ENDPOINT(默认${TETHYS_OIDC_ISSUER}/logout)。 - 浏览器整页导航到这个地址。这一步不能省:会话 cookie 是
HttpOnly; SameSite=Lax, 只有accounts.titanides.com自己能清。 themis-web把/logout同源透传给themis-gateway(与/authorize一样是 302 +Set-Cookie,所以必须走REDIRECT_PROXIES)。themis-auth校验id_token_hint(只用来识别是哪个 RP,过期也接受)与post_logout_redirect_uris,清fewbox_idp_session,302 回注册过的地址。
各处的配置:
| 位置 | 要配什么 |
|---|---|
themis-auth 的 OIDC_CLIENTS |
RP 的 redirect_uris + post_logout_redirect_uris |
themis-gateway 的 REDIRECT_PROXIES |
{"endpoint":"AUTH_OIDC","path":"logout","publicPath":"/logout"} |
themis-web 镜像 |
包含 /logout 透传路由 |
tethys-web |
TETHYS_OIDC_ISSUER / CLIENT_ID / REDIRECT_URI;post_logout_redirect_uris 要包含控制台的 ${origin}/ |
验证:curl -I "https://accounts.titanides.com/logout?client_id=<client_id>",响应头应带
x-powered-by: Express(来自网关)。如果看到 x-powered-by: Next.js 加 404,说明请求停在
themis-web,是镜像里没有 /logout 路由。
Theia:AI Agent
thia-agent
作用:Agent 引擎——多 LLM 提供商与故障切换、MCP 工具集成、技能与长期记忆;同时是心跳与
定时任务的执行体(thia-jobs-tick 每 5 分钟敲它一次)。它既是 API 服务,又是后台任务进程,
两者在同一个 Pod 里。
清单:一个 Deployment + 一个 ClusterIP Service(80 → 3000)+ 同一个 PostgreSQL 库。
探针打根路径 GET /livez、GET /readyz;GET /metrics 是 Prometheus 格式的指标。
不要挂公网 Ingress:它不校验 JWT,只信任网关铸的 x-user-id 头——能直连就能冒充任意用户。
⚠️
/readyz只表示「进程还在」,不表示能用。 它不查数据库、不查配置、不查 MCP。 库连不上、配置没加载,Pod 照样 Ready。真正的探活看日志里的Agentic system ready。
数据库:这个库必须带 pgvector 扩展(记忆向量列是 vector(1024))。代码不建表,
22 张表全部来自初始化脚本,全文见数据库表结构:
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f thia-agent-init-db.sql
漏了建表不会报错——启动成功、探针全绿,直到某个功能第一次查那张表才 500。
配置从哪来:绝大多数配置不在环境变量里,而在挂载进去的 config/agentic.yaml
(LLM 提供商表、MCP 服务表、记忆、计费单价、任务开关)。环境变量的作用是给这份 YAML 做
${VAR} 插值——YAML 里写 apiKey: '${KIMI_API_KEY}',真实值放 Secret。
⚠️ 镜像里没有
config/,也没有skills/。 打包只拷dist与依赖,.dockerignore还把 技能目录排除了。所以agentic.yaml必须用 ConfigMap 挂进来(技能同理),别指望镜像自带。 没挂上时启动日志是Agentic config file not found, skipping initialization,进程照常监听、 探针照常通过——只有对话和工具全都不工作。
环境变量
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | 服务端口 | 3000 |
NODE_ENV |
字面量 | 是 | 运行环境 | production |
LOG_LEVEL |
ConfigMap | 可选 | 日志级别 | info |
SERVICE_NAME |
ConfigMap | 可选 | 日志/链路服务名 | <product>-agent |
SHUTDOWN_TIMEOUT |
ConfigMap | 可选 | 优雅退出等待(毫秒)。必须小于 Pod 的 terminationGracePeriodSeconds,否则长任务收尾时被 SIGKILL |
30000 |
DEBUG_MODE |
ConfigMap | — | 部署中存在的调试开关;当前代码未直接读取,疑似历史变量 | false |
BROWSER_TOOLS_ENABLED |
ConfigMap | 可选 | true 时给模型启用浏览器工具 |
false |
OPENROUTER_API_KEY |
Secret | 可选 | OpenRouter 推理密钥 | <key> |
DEEPSEEK_API_KEY |
Secret | 可选 | DeepSeek 推理密钥 | <key> |
BYTEPLUS_API_KEY |
Secret | 可选 | BytePlus / 火山方舟推理密钥 | <key> |
KIMI_API_KEY |
Secret | 可选 | Kimi(Moonshot)推理密钥 | <key> |
EMBEDDING_API_KEY |
Secret | 可选 | 向量化(Embedding)服务密钥 | <key> |
BRAVE_API_KEY |
Secret | 可选 | Brave 搜索密钥 | <key> |
TAVILY_ENDPOINT |
ConfigMap | 可选 | Tavily 搜索 MCP 端点 | http://<tavily-host>/mcp |
VISION_ENDPOINT |
ConfigMap | 按装了几个 MCP | 视觉 MCP 端点,http://mcp-vision/mcp 这种形式,带 /mcp 路径 |
http://<vision-svc>/mcp |
MOTION_ENDPOINT |
ConfigMap | 按装了几个 MCP | 视频/动效 MCP 端点,格式同上 | http://<motion-svc>/mcp |
PERCEPTION_ENDPOINT |
ConfigMap | 按装了几个 MCP | 感知 MCP 端点,格式同上 | http://<perception-svc>/mcp |
ANALYSIS_ENDPOINT |
ConfigMap | 按装了几个 MCP | 只读 SQL 分析 MCP 端点(ADMIN 专用) | http://<analysis-svc>/mcp |
FETCH_ENDPOINT |
ConfigMap | — | 部署中存在;当前代码未直接读取(取网页能力由 agent 配置里的 MCP 段声明) | http://<fetch-svc>/mcp |
DATABASE_URL |
Secret | 是 | PostgreSQL 连接串,YAML 里 store.postgresUrl 引用的就是它 |
postgres://<user>:<pass>@<host>:5432/<db> |
ALERT_WEBHOOK_URL |
Secret | 可选 | 运行告警回调地址;值属于凭据,放 Secret | <webhook-url> |
SHARE_ACCESS_SECRET |
Secret | 可选 | 签名分享访问令牌;没设时点「解锁」会直接报错,而不是静默放行 | <random-string> |
POD_NAME |
Downward API | 多副本时 | 用于区分副本身份 | <pod-name> |
出厂配置里主循环引用
${KIMI_API_KEY}、工具调用引用${DEEPSEEK_API_KEY}——YAML 里 enabled 了哪个提供商,就欠哪个 key。变量名存在但代码里搜不到不代表没生效,它可能在 YAML 里被引用(见上)。
MCP 服务是在 YAML 里登记的,不是自动发现。装完 MCP 服务,要在 mcp.servers[] 里加一条
(完整的字段、三种 transport、计价与权限见 MCP 工具服务):
- id: 'fewbox-remote-vision'
name: 'FewBox Remote Vision'
enabled: true
transport:
type: 'streamable-http'
url: '${VISION_ENDPOINT}'
pricing: { pricePerCall: 0 } # 按工具计费的写这里,按模型/按量的写在 provider 侧
resilience:
callTimeoutMs: 300000 # 生图/生视频是长任务,别用默认 30s
id 可以随便起,工具名才是契约:运行时按工具名找服务(心跳里抓 RSS 用的是
findServerForTool('fetch_feed')),所以 mcp-fetch 不登记的话,有抓取来源的例行任务会在
启动时被打一条 Routine runtime fetch NOT available 的警告,然后每一轮都退回模型轮。
mcp-analysis 的那条要额外加两个字段——权限和心跳豁免:
requiredRoles: ['ADMIN'] # 只有 ADMIN 能看到/调用
availableInRoutines: false # 心跳永不自动跑 SQL
⚠️
${VAR}未设置时整个键会被丢掉。 插值逻辑对「整值就是一个变量」的写法返回undefined,随后这份配置要过 zod 校验,缺必填项日志里就是Failed to load agentic configuration。 但进程不会退出:这条错误会被吞掉,HTTP 服务照常监听,/livez、/readyz全绿—— 表现是「装好了、能连、但对话发不出去」。判断只看启动日志里有没有Agentic system ready和Environment variable X is not set。
⚠️
poolSize是每个 Pod 的连接数。 多个副本共用一个 PostgreSQL 池时,副本数 × poolSize + 1(那 1 个是 LISTEN 连接)必须留在数据库侧允许的会话数之内。
验证:curl http://thia-agent/livez;http://thia-agent/docs 能打开 Swagger 只说明进程装起来了。
再调三条:
curl http://thia-agent/api/v1/agents # 返回列表 → 数据库与迁移都在
curl -H 'x-user-id: <真实用户 id>' http://thia-agent/api/v1/me/conversations
curl http://thia-agent/.well-known/agent-card.json # 200 → agentic 配置已加载(503 表示没加载)
这三条在应用层都不验 JWT(/me/* 只读 x-user-id 头),所以能返回就证明进程、库与配置都在;
反过来说,它们都 404 / 500 才需要去查网络与迁移。最后从 thia-web 发一条对话,日志里应看到
各个 MCP 服务逐个连接成功。
对应 Bundle pack:app: thia-agent
thia-gateway
作用:thia-web 与浏览器扩展的统一入口。浏览器只认识它:GraphQL(/graphql)、
SSE(/stream)与文件上传都从这里进;JWT 验签也在这一层。另有几张「代理表」把路径原样转给
thia-agent / themis-auth / rhea-payment,用于流式事件、WebSocket 和支付回调。
清单:一个 Deployment + 一个 ClusterIP Service(80 → 3000)。探针打根路径
GET /livez、GET /readyz。对外需要一个域名:thia-web 的 endpoint / wsEndpoint 都指向它。
A2A 客户端不走这里:agent 卡与 JSON-RPC(
/.well-known/agent-card.json、/a2a)挂在thia-agent上,而它本身没有入站鉴权。要对外提供 A2A,得由您在网关上加一条代理或单独开 Ingress,并自行在那一层补鉴权。
⚠️
PORT不能删。 镜像里设了PORT=3000,代码里没有兜底默认值——变量不在了, Node 会在随机端口上监听,Pod 显示 Running 但 Service 打不到,探针也一直失败。
环境变量
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | 网关端口。代码没有默认值,删了会在随机端口监听 | 3000 |
CORS |
ConfigMap | 是 | 允许的来源数组,JSON。JSON 写错只打一行 [Config] Invalid JSON in env CORS 就退回 ["http://localhost:3000"],表现是浏览器报 CORS 而 curl 正常 |
["https://<web-host>"] |
JWT_PUBLIC_KEY |
Secret | 是 | 与 themis-auth 当前签名密钥成对的 ES256 公钥(PEM)。缺了或格式不对,进程启动即退出 1;也可用 JWT_PUBLIC_KEY_PATH 挂文件 |
<pem> |
JWT_VERIFY_ALGORITHM |
ConfigMap | 可选 | 设了就只能是 ES256;填别的一律启动失败(不支持 HS256) |
ES256 |
AUTH_ENDPOINT |
ConfigMap | 是 | 身份服务 REST 端点,JSON | {"protocol":"http","host":"themis-auth","port":80,"basePath":"api/v1"} |
AGENT_ENDPOINT |
ConfigMap | 是 | agent 服务端点,JSON | {"protocol":"http","host":"thia-agent","port":80} |
PAYMENT_ENDPOINT |
ConfigMap | 用到支付回调时 | 只用于 POST_PROXIES 的支付 webhook 透传(endpoint: "PAYMENT");GraphQL 的 payment 字段已搬去 rhea-gateway,不再读它。不挂 webhook 就可不配 |
{"protocol":"http","host":"rhea-payment","port":80} |
GET_PROXIES |
ConfigMap | 按功能 | GET 代理表,JSON 数组,元素 {endpoint, path, publicPath?}。endpoint 是上面几个服务名,path 是后端路径,公共路径默认拼成 /<endpoint 小写>/<path> |
[] |
GET_SSE_PROXIES |
ConfigMap | 按功能 | GET SSE 代理表,格式同上。thia-web 的对话事件流走这条 |
[{"endpoint":"AGENT","path":"events"}] |
POST_PROXIES |
ConfigMap | 按功能 | POST 代理表,格式同上。支付回调用这条 | [{"endpoint":"PAYMENT","path":"api/v1/webhooks/:provider"}] |
POST_SSE_PROXIES |
ConfigMap | 按功能 | POST SSE 代理表,格式同上 | [] |
WS_PROXIES |
ConfigMap | 按功能 | WebSocket 代理表,格式同上。当前 thia-web 不用它——对话流是 /graphql 上的 WebSocket,网关内置处理 |
[] |
IMAGE_SUPPORTED_TYPES |
ConfigMap | 可选 | 原样透传的图片 MIME 数组;不在列表内的图片会被转成 jpeg | ["image/png","image/jpeg","image/webp","image/gif"] |
IMAGE_MAX_SIZE_BYTES |
ConfigMap | 可选 | 图片原样透传的大小上限(字节) | 10485760 |
UPLOAD_MAX_FILE_SIZE |
ConfigMap | 可选 | 上传单文件大小上限(字节)。仓库里那份示例 ConfigMap 写的是 6——沿用它,浏览器一次抓十几张图就会 413 |
10000000 |
UPLOAD_MAX_FILES |
ConfigMap | 可选 | 单次上传文件数上限(浏览器抓图一次最多 12 张,留余量) | 20 |
AJAX_TIMEOUT_MS |
ConfigMap | 可选 | 转发到后端的超时(毫秒)。代码默认 30000(示例文件里的 600000 不是默认值)。生图/生视频那几路是长任务,生产建议显式设 600000 |
600000 |
GRAPHQL_BODY_LIMIT |
ConfigMap | 可选 | GraphQL JSON 体上限,默认 1mb;与边缘 nginx 的 client_max_body_size 是两层,都要够 |
1mb |
ENABLE_HTTPS |
ConfigMap | 可选 | true 时网关自己终止 TLS |
false |
SSL_KEY_PATH |
ConfigMap | 可选 | TLS 私钥文件路径(Secret 以文件挂载时用) | <path> |
SSL_CERT_PATH |
ConfigMap | 可选 | TLS 证书文件路径 | <path> |
TRACING_ENABLED |
ConfigMap | 可选 | 打开 OpenTelemetry 链路追踪 | false |
TRACING_DEBUG |
ConfigMap | 可选 | 打开 OTel 内部诊断日志,仅排障时用 | false |
OTEL_SERVICE_NAME |
ConfigMap | 可选 | 链路里的服务名 | <product>-gateway |
OTEL_EXPORTER_OTLP_ENDPOINT |
ConfigMap | 可选 | OTLP 导出地址 | http://<collector>:4318/v1/traces |
JWT_OPERATION_NAME_WHITELIST |
ConfigMap | — | 历史变量:当前 gateway 代码已不读取,可从部署里删除 | — |
⚠️
endpoint的 JSON 里没有自动前缀。 代理是按path原样拼接的,AUTH_ENDPOINT不带basePath就要自己在每条path里写全api/v1/...。⚠️ 代理表解析失败 = 那条代理不存在。 五张表走同一个
parseJsonEnv:JSON 不合法时整体退回 空数组,只留一行[Config] Invalid JSON in env GET_SSE_PROXIES之类的错误,启动照常成功。 所以配完要看启动日志里有没有对应那几条[SSE PROXY] /agent/events -> …,而不是看进程起没起来。
必须存在的代理(缺哪条,对应功能就是「界面正常、调用 404」):
| 功能 | 表 | 条目 |
|---|---|---|
| Agent 事件流(SSE) | GET_SSE_PROXIES |
{"endpoint":"AGENT","path":"events"} → 公共路径 /agent/events,thia-web 的对话流走这条 |
| 支付回调 | POST_PROXIES |
{"endpoint":"PAYMENT","path":"api/v1/webhooks/:provider"} → 公共路径 /payment/api/v1/webhooks/:provider,填进 Stripe 后台的 Webhook URL |
对话的交互流不需要代理:它是 /graphql 上的 graphql-transport-ws,由网关内置处理。
WS_PROXIES 留给其他要直连 WebSocket 的集成(控制台的 tethys-gateway 用它,见 Tethys 一节)。
⚠️ 代理不强制鉴权。 带 token 的请求会被验签并铸
x-user-id;不带 token 的请求照样转发, 只是没有身份头。所以代理只能指向本来就允许匿名访问的路径——把thia-agent的管理路由 (如/api/v1/jobs/tick、/api/v1/billing/settle)挂上去,就等于把它们开放给公网。
验证:curl https://gateway.titanides.com/livez 返回 {"status":"ok"}。注意 /readyz 也只表示进程在监听,
不检查 AUTH_ENDPOINT / AGENT_ENDPOINT 是否可达——那两个配错时探针一样绿。带一个用户 token 调
POST /graphql 查 myConversations(不带 token 时应返回
Access Denied: Authentication required),能返回列表就说明验签与 agent 链路都通了。再看启动日志里每张代理表打印的
[GET PROXY] /x -> http://…,确认拼出来的路径与后端路由一致。
对应 Bundle pack:app: thia-gateway
thia-web
作用:团队使用的 Web 应用——营销页、策展页、对话界面都在这里。它同时是 OIDC 的 RP:
浏览器只跟它打交道,登录跳转、回调换 token、登出全在它的 /api/auth/* 路由里完成,
后端服务不直接面对浏览器。
清单:一个 Deployment(Next.js standalone,node server.js,无 PVC)+ 一个 ClusterIP
Service,端口 80 → 3000。
⚠️ 它没有
/livez//readyz。 镜像里只有业务路由,别照抄其他服务的探针路径—— 探针用 TCP 3000,或者打GET /api/config(动态渲染,能证明 Node 进程还能出响应)。 打/livez会 404,探针会一直判失败,Pod 反复重启。
前置:themis-auth(OIDC IdP,thia-web 这个 client 必须已在它的 OIDC_CLIENTS 里注册过)、
thia-gateway、rhea-gateway。
服务端变量(只在服务端读,不会下发到浏览器)
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | Next 服务端口 | 3000 |
SITE_DOMAIN |
ConfigMap | 是 | 对外主域,用于 canonical / hreflang / sitemap / robots / OG。进程启动时读取一次,改值重启 Pod 即可 | titanides.com |
API_DOMAIN |
ConfigMap | 是 | 允许前端连接的注册域,用于生成 CSP connect-src;可空格/逗号分隔多个域。必须是网关对外域名,否则 CSP 只报不拦也记不到 |
titanides.com |
CONTACT_EMAIL |
ConfigMap | 可选 | 页脚联系方式 | <address> |
DISCORD_URL |
ConfigMap | 可选 | Discord 邀请链接 | <url> |
COMPANY_URL |
ConfigMap | 可选 | 公司/官网链接 | <url> |
EXTENSION_STORE_URL |
ConfigMap | 可选 | Chrome 扩展商店链接;留空显示「即将上线」 | <url> |
EXTENSION_PREVIEW_ZIP_URL |
ConfigMap | 可选 | 扩展预览包下载地址 | <url> |
PLACEHOLDER_HOST |
ConfigMap | 可选 | 需要显示告知文案的完整 host(与 Host 头精确比较,不做通配)。留空关闭 | <host> |
PLACEHOLDER_NOTICE |
ConfigMap | 可选 | 上述 host 上显示的一行文案 | <notice> |
THIA_OIDC_ISSUER |
ConfigMap | 是 | IdP 的 issuer,如 https://accounts.titanides.com。缺了进程启动即抛错 |
https://accounts.titanides.com |
THIA_OIDC_CLIENT_ID |
ConfigMap | 是 | 公共客户端,固定 thia-web |
thia-web |
THIA_OIDC_REDIRECT_URI |
ConfigMap | 是 | https://titanides.com/api/auth/callback,必须与 OIDC_CLIENTS 里登记的一致 |
https://<site>/api/auth/callback |
AUTH_FLOW_TOKEN |
Secret | 是 | 封存 PKCE / state 流程 cookie 的 HMAC 密钥。生产环境不填,/api/auth/token 直接 503 not_configured |
<random-string> |
AUTH_SESSION_TOKEN |
Secret | 是 | 会话 cookie 的 AES-256 密钥。多副本必须一致;轮换等于全员登出 | <random-string> |
AUTH_SESSION_TTL_SECONDS |
ConfigMap | 可选 | 会话有效期(秒);小于 60 的值被忽略 | 604800 |
AUTH_FLOW_TTL_SECONDS |
ConfigMap | 可选 | 登录往返的时限(秒) | 1800 |
客户端变量(经 /api/config 下发,变量名就是小驼峰,不要改成大写)
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
endpoint |
ConfigMap | 是 | 主网关的 JSON。缺了服务端渲染的数据页直接 500 | {"PROTOCOL":"https","HOST":"<gateway-host>","PORT":443} |
wsEndpoint |
ConfigMap | 是 | Agent 交互流的 WebSocket 地址,缺了对话发不出去 | {"PROTOCOL":"ws","HOST":"<gateway-host>","PORT":443,"BASEPATH":"ws"} |
themisEndpoint |
ConfigMap | 是 | themis-gateway 的地址,缺了个人资料区不刷新 | {"PROTOCOL":"https","HOST":"<themis-gateway-host>","PORT":443} |
rheaEndpoint |
ConfigMap | 是 | rhea-gateway 的地址。不配的后果是静默的:余额与流水显示为空、定价回落到内置套餐(没有 priceId,订阅按钮永远置灰) |
{"PROTOCOL":"https","HOST":"<rhea-gateway-host>","PORT":443} |
rheaConsoleUrl |
ConfigMap | 可选 | 计费控制台地址;用户页的钱包卡片用它跳转,留空则不渲染链接 | https://<rhea-console-host> |
agentVariantHeader |
ConfigMap | 可选 | 变体/灰度路由的请求头名,必须与 VirtualService 的 header match 完全一致 | variant-<agent> |
defaultAgent |
ConfigMap | 可选 | 默认 agent 的 code,必须是 agent 目录里真实存在的值,留空由后端决定 |
<agent-code> |
gaMeasurementId |
ConfigMap | 可选 | GA4 衡量 ID(G-...),留空关闭统计。只应在生产环境设置 |
G-<id> |
googleClientId |
ConfigMap | 可选 | Google OAuth client id,本身是公开值,留空则隐藏 Google 登录按钮 | <google-client-id> |
staticCdnUrl |
ConfigMap | 可选 | 站点静态资源 CDN 基址(完整 URL、无尾斜杠),策展素材与 3D 模型也用它 | <cdn-base-url> |
staticAssetVersion |
ConfigMap | 可选 | 静态资源缓存版本后缀,用于在 CDN 缓存未过期时强制刷新 | <version> |
ssoProviders |
ConfigMap | 可选 | SSO 入口数组,JSON:[{"key":"<provider>","label":"<label>","logoUrl":"<url>"}];key 必须对上 themis-auth 的 provider 注册 |
[] |
⚠️
endpoint的 JSON 解析失败是静默的。getServerConfig()把JSON.parse包在空 catch 里, 写错一个全角逗号,这个键就直接消失——进程照常启动,表现是数据页 500 或界面一片「—」。
验证:打开站点 → 点登录 → 在 accounts.titanides.com 登录 → 回到本站并看到自己的头像;
新建会话发一条消息,看到流式回复。
常见错配(都表现为"登录后立刻回到未登录"):THIA_OIDC_REDIRECT_URI 与 IdP 登记的不一致,
或者 AUTH_SESSION_TOKEN 在多个副本间不同。
SITE_DOMAIN / API_DOMAIN 写错不会拦住登录——CSP 目前是 Report-Only,只记录不拦。
所以它也不能拿来兜底:CSP 报错日志多,不代表没有配置问题。
对应 Bundle pack:app: thia-web
mcp-*
作用:Agent 干活时调用的工具服务,各自是一个独立的 MCP server。按需安装——装哪个由 您要用哪些能力决定,五个之间没有依赖。每个服务提供哪些工具、怎么计价,见 MCP 工具服务。
| 服务 | 提供什么 | 外部凭据 |
|---|---|---|
mcp-vision |
文生图、改图、混图(Seedream / Gemini) | 至少一套模型 key |
mcp-perception |
看图说话、取景对比 | Ark key |
mcp-motion |
文/图/参考图生视频(Seedance) | Ark key |
mcp-fetch |
抓网页与 RSS | 无 |
mcp-analysis |
只读 SQL 查询 | 数据库连接串 |
清单:每个都是一个 Deployment + ClusterIP Service(80 → 3000)。全部无状态、无 PVC,
MCP_TRANSPORT=http 由镜像设好,HTTP 模式只暴露 POST /mcp;它在协议里就是无会话的
(每个请求新建一个 server 实例),所以扩副本不需要粘性会话。
⚠️ 探针不是每个都有。 只有
mcp-fetch和mcp-analysis提供GET /health; 另外三个没有健康路由,探针用 TCP 3000。
⚠️ 五个都没有入站鉴权。 能连上就能调,所以只挂
ClusterIP,不要暴露到公网或同域的 Ingress。mcp-analysis的权限收在 agent 侧:只有ADMIN角色的会话能拿到这个工具。
五个服务共有 MCP_TRANSPORT(集群内固定 http)、PORT(3000)与 LOG_LEVEL(输出到 stderr)。
下表按服务逐个列出完整变量。
mcp-vision
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
MCP_TRANSPORT |
字面量 | 是 | 集群内固定 http;stdio 只用于本地调试 |
http |
PORT |
字面量 | 是 | 服务端口 | 3000 |
LOG_LEVEL |
ConfigMap | 可选 | 日志级别 | info |
SEEDREAM_ENDPOINT |
ConfigMap | 二选一 | Seedream 模型 API 基址 | https://<model-api>/api/v3 |
SEEDREAM_MODELS |
ConfigMap | 二选一 | 可用的 Seedream 模型列表,逗号分隔;留空等于关闭该提供商 | <model-id> |
SEEDREAM_API_KEY |
Secret | 二选一 | Seedream 密钥 | <key> |
GEMINI_ENDPOINT |
ConfigMap | 可选 | Gemini 或自建中转网关地址 | https://<gemini-endpoint> |
GEMINI_API_KEY |
Secret | 可选 | Gemini 密钥 | <key> |
GEMINI_MODELS |
ConfigMap | 可选 | 可用 Gemini 模型列表 | <model-id> |
GEMINI_RELAY_TOKEN |
Secret | 可选 | 中转网关的 x-relay-token |
<token> |
DEFAULT_MODEL |
ConfigMap | 多个模型时 | 调用方不指定模型时用哪个,多模型时必须能唯一选中 | <model-id> |
RESPONSE_CONTENT_TYPE |
ConfigMap | 可选 | 返回形态:text / resource_link / image |
text |
STORAGE_* |
ConfigMap/Secret | 可选 | S3 兼容存储七个变量(AK / SK / region / endpoint / bucket / public URL / ACL),配齐才生效,返回持久 URL;否则用提供方的临时 URL。配法见对象存储与静态资源 | 同 mcp-motion |
mcp-perception
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
MCP_TRANSPORT |
字面量 | 是 | 集群内固定 http |
http |
PORT |
字面量 | 是 | 服务端口 | 3000 |
LOG_LEVEL |
ConfigMap | 可选 | 日志级别 | info |
ENDPOINT |
ConfigMap | 是 | 模型服务 API 基址 | https://<model-api>/api/v3(Ark 北京区) |
MODEL |
ConfigMap | 是 | 默认视觉模型标识 | doubao-seed-2-0-mini-260215 |
API_KEY |
Secret | 是 | Ark 密钥。⚠️ 启动时不校验,空值照样起得来,第一次调用才 401 | <key> |
RESPONSE_CONTENT_TYPE |
ConfigMap | 可选 | 返回形态 | text |
THINKING_MODE |
ConfigMap | 可选 | enabled / disabled / auto;描述类任务通常设 disabled 省延迟 |
空(用模型默认,doubao 默认开启) |
mcp-motion
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
MCP_TRANSPORT |
字面量 | 是 | 集群内固定 http |
http |
PORT |
字面量 | 是 | 服务端口 | 3000 |
LOG_LEVEL |
ConfigMap | 可选 | 日志级别 | info |
ENDPOINT |
ConfigMap | 是 | 模型服务 API 基址。⚠️ 启动时不校验,第一次调用才 401 | https://<model-api>/api/v3 |
MODEL |
ConfigMap | 是 | 默认视频模型标识,决定能力表(哪些输入组合可用) | <model-id> |
API_KEY |
Secret | 是 | 模型服务密钥(与 mcp-perception 同源时可共用一个 key) | <key> |
RESPONSE_CONTENT_TYPE |
ConfigMap | 可选 | 返回形态:text 或 resource_link |
text |
POLLING_INTERVAL |
ConfigMap | 可选 | 生成任务轮询间隔(毫秒) | 10000 |
POLLING_TIMEOUT |
ConfigMap | 可选 | 轮询总超时(毫秒) | 300000 |
ARK_ASSET_* |
ConfigMap/Secret | 可选 | 人物资产库,配齐才启用 | <...> |
STORAGE_ACCESS_KEY_ID |
Secret | 可选 | 对象存储 AK;不配则用提供商的临时 URL | <key> |
STORAGE_SECRET_ACCESS_KEY |
Secret | 可选 | 对象存储 SK | <secret> |
STORAGE_REGION |
ConfigMap | 可选 | 存储区域 | <region> |
STORAGE_ENDPOINT |
ConfigMap | 可选 | S3 兼容上传端点 | https://<s3-endpoint> |
STORAGE_BUCKET |
ConfigMap | 可选 | 桶名 | <bucket> |
STORAGE_PUBLIC_URL |
ConfigMap | 可选 | 公开下载地址前缀(CDN/自定义域) | <public-base-url> |
STORAGE_FORCE_PATH_STYLE |
ConfigMap | 可选 | MinIO 等需要 path-style 时设 true |
false |
STORAGE_ACL |
ConfigMap | 可选 | 对象 ACL;Cloudflare R2 等应留空。七个变量的配法见对象存储与静态资源 | public-read |
mcp-fetch
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
MCP_TRANSPORT |
字面量 | 是 | 集群内固定 http |
http |
PORT |
字面量 | 是 | 服务端口 | 3000 |
LOG_LEVEL |
ConfigMap | 可选 | 日志级别 | info |
PER_HOST_RPM |
ConfigMap | 可选 | 单主机每分钟请求上限;超限是等待,不是失败 | 20 |
MAX_BYTES |
ConfigMap | 可选 | 单次响应体上限(字节) | 2000000 |
TIMEOUT_MS |
ConfigMap | 可选 | 单次抓取超时(毫秒) | 20000 |
HTTPS_PROXY |
ConfigMap | 可选 | 出网代理。集群不能直连外网时必须配,否则抓取全超时 | <url> |
NO_PROXY |
ConfigMap | 可选 | 不走代理的地址列表 | <host>,<host> |
ALLOW_HOSTS / DENY_HOSTS |
ConfigMap | 可选 | 主机白/黑名单,黑名单先判;留空为任意公网 | <host1>,<host2> |
USER_AGENT |
ConfigMap | 可选 | 抓取请求的 UA | <ua> |
该服务始终拒绝回环、私网、链路本地与云 metadata 地址,不依赖上面的名单。
mcp-analysis
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
MCP_TRANSPORT |
字面量 | 是 | 集群内固定 http |
http |
PORT |
字面量 | 是 | 服务端口 | 3000 |
LOG_LEVEL |
ConfigMap | 可选 | 日志级别 | info |
SERVER_NAME |
ConfigMap | 可选 | MCP 服务标识 | <product>-mcp-analysis |
PG_DATABASES |
Secret | 是 | 可查询库的 JSON 数组 [{"id","label","url"}],url 必须是 postgres://。连接串含口令,必须放 Secret;缺失或格式错,进程启动即抛错 |
<json> |
MAX_ROWS |
ConfigMap | 可选 | 单条查询返回行数上限 | 1000 |
STATEMENT_TIMEOUT_MS |
ConfigMap | 可选 | 服务端语句超时 | 10000 |
QUERY_TIMEOUT_MS |
ConfigMap | 可选 | 客户端查询超时(含流式读取) | 15000 |
CONNECTION_TIMEOUT_MS |
ConfigMap | 可选 | 建连超时 | 10000 |
POOL_MAX |
ConfigMap | 可选 | 每个库的连接池上限 | 5 |
部署后:在 thia-agent 的配置里登记这些服务的地址(见本文开头 thia-agent 一节),否则
工具不会被注册到模型的工具表里——服务跑着,但对话里永远调不到。
thia-jobs-tick
它不是一个 Service,而是一个 Kubernetes CronJob:每 5 分钟向 thia-agent 的默认变体
POST /api/v1/jobs/tick(不带令牌、也没有密钥——它按「集群内可信」设计)。真正跑什么由系统
决定,CronJob 只负责到点敲门。
| 要求 | 值 | 不满足会怎样 |
|---|---|---|
| 节奏 | 每 5 分钟(*/5 * * * *),timeZone: Asia/Shanghai |
心跳最短只能到 5 分钟一拍;时区不对会让「每天 9 点」错位 |
| 并发策略 | concurrencyPolicy: Forbid |
上一拍没跑完又起一拍;有租约兜底不会重复执行,但会白跑一次 |
| 目标 | 默认变体的 Service:POST http://thia-agent/api/v1/jobs/tick |
打到没开 jobs.enabled 的变体时返回 disabled,不报错 |
| 变体配置 | 默认变体 jobs.enabled: true 且 routines.enabled: true |
只开后者不开前者,或反过来,心跳都静默不跑——出厂的 agentic.yaml 里没有 routines: 段,默认是关的 |
| 存储 | store.driver: postgresql |
SQLite 或没配库时任务运行时不启动,只留一条警告 |
| 迁移 | 先执行 2026-09-add-scheduled-jobs.sql 等迁移,再建 CronJob |
任务表不存在时任务运行时降级关闭,/jobs/* 返回 disabled,进程不退出 |
| 网络 | sidecar.istio.io/inject: "false";网格不是 STRICT mTLS |
开了严格双向 TLS 后,这个不带 sidecar 的 CronJob 敲不进来,心跳静默停摆 |
/jobs/tick 默认立即返回 202,?wait=true 会等本轮跑完再返回——排障时用后者,能看到真实的执行结果。
整个集群只建一个:不要为每个用户或每个任务各建一个——几千用户就是几千个集群对象, 还要把集群 API 权限交出去。节奏和「谁在跑」都记在数据库的任务行里,一个 CronJob 扫全表就够了。
Tethys:DevOps(可选)
不装 Tethys,整套系统照常运行。 它解决的是另一件事:把应用打包成 Bundle 发布到目标集群, 并在界面上管理集群资源、租户与微服务生命周期——发布、升级、伸缩、回滚,以及从控制台启动 出口代理和网络诊断容器。
它由三个服务组成;另外两个常见功能(出口代理、网络诊断)不是常驻服务,见本节最后。
tethys-shipping
作用:两个进程,通常拆成两个 Deployment。
- Shipping API:REST 接口,对 Kubernetes 原生资源、Istio 资源与 FewBox CRD 做增删改查, 并封装租户、微服务生命周期、任务调度与中间件安装。
- PackingTable operator:监听
Bundle、Infrastructure、Middleware三个 CRD, 把它们 reconcile 成 Deployment / Service。路径 A 的 Bundle 部署依赖它——「底座安装」装的就是它。Tenant与Registry没有 controller:前者是控制台维护的记录,后者由平台侧预装。
前置:一个带集群级权限的 ServiceAccount。operator 要创建 Deployment、Service、Ingress、
ClusterRole 乃至 CRD,权限清单见 operator-role.yaml——它天生是特权组件,只应装在受控集群里。
① CRD 与 operator
就是「一键部署 / PackingTable operator」里的那一步: 三份清单(ClusterRole、ClusterRoleBinding、Deployment)的全文在那一节,这里不重复。 CRD 由 operator 启动时自装(实体类型转译而来),不需要单独 apply。
② ServiceAccount
kubectl create namespace fewbox-system
kubectl create serviceaccount fewbox -n fewbox-system
③ 部署 operator
kubectl apply -f deploy/deployment.yaml
kubectl get pods -n fewbox-system
operator 用 POD_NAMESPACE 与 DevOps__Endpoints__K8SEndpoint__* 连接 API Server;集群内填
kubernetes.default.svc、端口 443,凭据走 ServiceAccount token。
④ 部署 Shipping API
镜像用仓库根目录的 Dockerfile 构建(operator 用的是 packingtable 那一份)。容器端口由 PORT
决定,镜像缺省是 8080(.NET 容器惯例),Service 对外仍是 80——targetPort 必须与容器实际
监听的端口一致,SHIPPING_ENDPOINT.port 填的则是 Service 端口 80。需要:
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | Shipping 端口;PackageTable/控制台按它拼 Service 端口 | 5000(镜像缺省 8080) |
DevOps__Endpoints__K8SEndpoint__Host |
ConfigMap | 是 | 集群内用 kubernetes.default.svc,集群外用 API Server 地址 |
kubernetes.default.svc |
DevOps__Endpoints__K8SEndpoint__Port |
ConfigMap | 是 | API Server 端口 | 443 |
DevOps__Endpoints__K8SEndpoint__AppSettingsToken |
Secret | 是 | ServiceAccount token | <token> |
集群内它用 ServiceAccount 访问 apiserver,所以不需要 kubeconfig;只有在本机直接跑 Shipping 时才在
.env 里填 K8S_ENDPOINT / K8S_TOKEN。Shipping 指向哪个集群,就决定控制台管理哪个集群。
token 的取法:
kubectl create token fewbox --duration 8760h -n fewbox-system
它的数据存在 SQLite 文件里。需要保留发布历史与租户数据,就把该文件所在目录挂到 PVC 上; 不挂的话 Pod 重建即丢。
验证:kubectl get crds | grep fewbox.com 能看到六个 CRD(tenants、bundles、infrastructures、
middlewares、families、registries);operator 与 API 的 Pod 都是
READY;从 tethys-gateway 侧能调通用户列表查询。
对应 Bundle pack:app: tethys-shipping
tethys-gateway
作用:控制台的 GraphQL 入口——把管理操作转给 Shipping API,并做 JWT 验签与 CORS;
同时提供 /stream(SSE)与 WebSocket,供控制台看任务输出与日志。
配置
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | 网关端口;Service 端口 80 → 容器端口 | 3000 |
SHIPPING_ENDPOINT |
ConfigMap | 是 | host 填 Service 名(= 控制台里的应用名),port 填 Service 端口 80;跨命名空间用 <service>.<tenant>.svc.cluster.local |
{"protocol":"http","host":"tethys-shipping","port":80,"basePath":"api"} |
SHIPPINGWS_ENDPOINT |
ConfigMap | 用实时列表时必填 | 没有 basePath:/watch、/xterminal 挂在 Shipping 的根路径 |
{"protocol":"http","host":"tethys-shipping","port":80} |
WS_PROXIES |
ConfigMap | 用实时列表时必填 | 见下方 JSON。每个 watch 路径必须逐条列出,详见下面的匹配规则 | [{"name":"<name>","path":"ws","target":"ws://<svc>:8080"}] |
GRAPHQL_BODY_LIMIT |
ConfigMap | 可选 | /graphql 请求体上限,express.json 语法(如 10mb、512kb)。Bundle 导入把整份 YAML 塞进一个 GraphQL 变量,默认值已放宽到 10mb |
10mb |
JWT_VERIFY_ALGORITHM |
ConfigMap | 是 | 只接受 ES256。填成别的值会启动即失败;没有 HS256 / JWT_SECRET 回退 |
ES256 |
JWT_PUBLIC_KEY |
Secret | 是 | themis 签名公钥 PEM,支持单行字面量 \n;与 JWT_PUBLIC_KEY_PATH 二者取其一 |
<pem> |
JWT_PUBLIC_KEY_PATH |
Secret(文件) | 是 | 指向挂载的 Secret 文件;与上一行同时配置时以文件为准 | <path> |
CORS |
ConfigMap | 是 | JSON 数组。浏览器直连网关,Origin 必须逐字对上 | ["https://console.titanides.com"] |
PERMISSIONS_OPEN |
ConfigMap | 可选 | 临时跳过 JWT 校验与 ADMIN 鉴权,只在身份服务尚未接好时使用。日志会打 [SECURITY] 警告,不要留到生产 |
false |
SUPABASE |
Secret | 是 | 控制台的用户表目前放在 Supabase | {"url":"https://<项目>.supabase.co","key":"<anon key>"} |
公钥必须与身份服务当前签名用的一致。 缺失时进程启动即失败(启动自检);反过来说, 网关能启动、但每个 GraphQL 字段都返回
Access Denied: ...,意味着公钥存在但不是身份服务 当前那把——常见于身份服务轮换了签名密钥(JWKS 的kid会变)。公钥取自https://accounts.titanides.com/jwks里的 EC P-256 公钥:把 JWK 的x、y按04 || x || y拼接,外包一层 EC SubjectPublicKeyInfo,再 base64 成 PEM 即可。
每个 GraphQL 根字段都是
and(isAuthenticated, isAdmin),PERMISSIONS_OPEN之外没有 只读公开字段。账号没有ADMIN角色时返回Access Denied: ADMIN role required,界面提示 后停下,不会反复跳转。
WS_PROXIES 完整值(公共路径默认为 /<endpoint 小写>/<path>,即 /shippingws/...):
[
{"endpoint":"SHIPPINGWS","path":"watch/api/v1/namespaces"},
{"endpoint":"SHIPPINGWS","path":"watch/apis/apps/v1/deployments"},
{"endpoint":"SHIPPINGWS","path":"watch/api/v1/pods"},
{"endpoint":"SHIPPINGWS","path":"watch/apis/batch/v1/jobs"},
{"endpoint":"SHIPPINGWS","path":"watch/apis/batch/v1/cronjobs"},
{"endpoint":"SHIPPINGWS","path":"xterminal"}
]
匹配是整条 pathname 精确比对,没有前缀匹配。少列一条,就只有那一条 WebSocket 断, 其余功能正常——表现为某个列表不刷新。
tethys-web的wsEndpoint.BASEPATH必须等于这里 的公共前缀(shippingws)。
⚠️
SUPABASE是 Tethys 的历史遗留——它比统一身份早,用户表独立在formuser。接入 themis 之后这一项会去掉;在那之前,私有化部署要多准备一个 Supabase 实例。不想引入它,也可以先不装 Tethys——核心产品不依赖它。
部署:Deployment + ClusterIP Service(80 → 3000),探针 /livez、/readyz。
验证:/livez 返回 {"status":"ok"};带 Origin 的预检返回 204 且带
Access-Control-Allow-Origin: https://console.titanides.com;不带 token 查一个根字段应返回
Access Denied: Authentication required(说明鉴权生效,而不是被 PERMISSIONS_OPEN 旁路)。
对应 Bundle pack:app: tethys-gateway
tethys-web
作用:集群管理控制台——集群总览、命名空间与工作负载、Bundle 与 CRD、租户、微服务生命周期、 存储、日志与终端。
配置
| 变量 | 来源 | 必填 | 说明 | 占位/默认 |
|---|---|---|---|---|
PORT |
字面量 | 是 | Next 服务端口;Service 端口 80 → 容器端口 | 3000 |
endpoint |
ConfigMap | 是 | 网关 GraphQL/SSE 地址,JSON。公网地址——浏览器用它调 GraphQL,填 Service 名的话浏览器解析不到 | {"PROTOCOL":"https","HOST":"console.titanides.com","PORT":443} |
wsEndpoint |
ConfigMap | 是 | 网关 WebSocket 地址,JSON。BASEPATH 必须等于 tethys-gateway 的 SHIPPINGWS 公共路径前缀 |
{"PROTOCOL":"wss","HOST":"console.titanides.com","PORT":443,"BASEPATH":"shippingws"} |
TETHYS_OIDC_ISSUER |
ConfigMap | 是 | 身份服务的公网 issuer,无尾斜杠;必须与 themis-auth 的 OIDC_ISSUER 逐字一致 |
https://accounts.titanides.com |
TETHYS_OIDC_CLIENT_ID |
ConfigMap | 是 | 本应用在 OIDC_CLIENTS 里的 client_id |
tethys-web |
TETHYS_OIDC_REDIRECT_URI |
ConfigMap | 是 | 授权码回跳地址,必须与 OIDC_CLIENTS 的 redirect_uris 逐字一致 |
https://console.titanides.com/api/auth/callback |
AUTH_FLOW_TOKEN |
Secret | 是 | 登录流程 cookie(state / nonce / PKCE verifier)的密封密钥。生产环境无默认值,缺失时登录直接报配置错误 | <random-string> |
AUTH_SESSION_TOKEN |
Secret | 是 | 会话 cookie(tethys_session)的加密密钥。它与上一个分开生成,不能共用;同样生产环境无默认值 |
<random-string> |
TETHYS_OIDC_LOGOUT_ENDPOINT |
ConfigMap | 可选 | 登出地址,默认 ${TETHYS_OIDC_ISSUER}/logout(即 auth discovery 里的 end_session_endpoint)。只有网关对外的登出路径不同才需覆盖 |
${TETHYS_OIDC_ISSUER}/logout |
TETHYS_OIDC_AUTHORIZATION_ENDPOINT |
ConfigMap | 可选 | 默认 ${TETHYS_OIDC_ISSUER}/authorize;一般不用填 |
— |
TETHYS_OIDC_TOKEN_ENDPOINT |
ConfigMap | 可选 | 默认 ${TETHYS_OIDC_ISSUER}/token;一般不用填 |
— |
TETHYS_OIDC_SIGNOUT_ENDPOINT |
ConfigMap | 可选 | 默认 ${TETHYS_OIDC_ISSUER}/api/v1/signout;一般不用填 |
— |
AUTH_FLOW_TTL_SECONDS |
ConfigMap | 可选 | 流程 cookie 有效期(秒);小于 60 的值会被忽略 | 1800 |
AUTH_SESSION_TTL_SECONDS |
ConfigMap | 可选 | 会话滑动有效期(秒);对齐身份服务的 REFRESH_TOKEN_EXPIRES_IN |
604800 |
endpoint/wsEndpoint是小写开头的 JSON 字符串,浏览器端从本服务的/api/config读 ——它把环境变量里所有以Endpoint结尾的键(以及小写的endpoint)原样转出,大小写敏感。 写成TETHYS_ENDPOINT就匹配不到,前端什么也读不到。其余TETHYS_OIDC_*/AUTH_*只在服务端读,不会出现在/api/config里。
多副本必须同值。
AUTH_FLOW_TOKEN、AUTH_SESSION_TOKEN每个副本都要一致:cookie 由 任一副本签发,请求可能落到另一个副本。不一致时的表现是"有时能登、有时登不上"——会话 cookie 解不开,/api/auth/token直接 401。
TETHYS_OIDC_* 全是服务端专用(大写),浏览器只看到同源的 /api/auth/*:
- 登录:浏览器跳到
${issuer}/authorize(带 PKCE 的code_challenge),授权码回到TETHYS_OIDC_REDIRECT_URI,服务端用/token换到 token。refresh token、id_token 与缓存 的 access token 只写进 HttpOnly 的加密 cookie,浏览器内存里只保留 access token,不落 localStorage。已在 IdP 登录过时是一次静默 302,不弹登录页。 - 续期:access token 临近过期时,浏览器调同源的
POST /api/auth/token,服务端用 cookie 里的 refresh token 换新(refresh token 会轮换),并把新 token 重新封回 cookie。 - 退出:先调本地
/api/auth/signout删 refresh token、拉黑 access token 的jti并清掉 会话 cookie;再整页跳到TETHYS_OIDC_LOGOUT_ENDPOINT清 IdP 会话,最后回到post_logout_redirect_uris里注册的地址——固定为站点根,不回到退出前所在页面。 - 控制台拿到的是 themis 签发的 token,因此
tethys-gateway必须配同一把公钥(见上一节)。
部署前要一起改的三处(任何一处没对上,症状都是登录不进去,而不是报配置错):
- 身份服务
OIDC_CLIENTS里注册本应用,redirect_uris与TETHYS_OIDC_REDIRECT_URI逐字匹配(结尾斜杠、http/https 都不能差),并登记post_logout_redirect_uris。 客户端配置在进程内缓存,改完要重启身份服务。 tethys-gateway的CORS加上控制台的 Origin(如["https://console.titanides.com"]),否则 浏览器请求全部被拦。- 控制台域名要真的走 https:
TETHYS_OIDC_REDIRECT_URI是https://时会话 cookie 带Secure,边缘若实际是 http,登录会一直回到未登录。
部署:Deployment + Service(80 → 3000);边缘把控制台域名指向它。
验证:登录后能载入集群总览与命名空间列表;刷新页面仍在线(不会重新弹登录);点退出应回到 站点根,且再点登录需要重新输入(不会静默 SSO 直接进去)。如果登录成功却反复跳回登录页,见 「排障」里的「登录成功后无限跳回登录页」。
对应 Bundle pack:app: tethys-web
出口代理与网络诊断(从控制台启动)
下面两个不是预装的 Deployment,而是控制台「管理微服务」页里的两个一键预设:装好
tethys-web 就自带,不需要单独 apply 清单。
出口代理
让集群里的服务经由一条固定出口访问 LLM 提供商与镜像源,适合目标集群直连境外不通的场景。
- 默认镜像
metacubex/mihomo:latest,启动命令/mihomo -d /etc/mihomo - 端口
7897,配置以config.yaml挂到/etc/mihomo - 以
isRawNetwork方式启动——脱离服务网格,否则代理自身会被网格接管
⚠️ 模板里带的是一条示例 VLESS 节点,server 与 uuid 必须换成您自己的出口配置,不要照抄。
启动后把需要走代理的服务(例如要访问境外模型的 thia-agent)的 HTTP_PROXY / HTTPS_PROXY
指向该 Service。
网络诊断
一键启动一个 nicolaka/netshoot 容器(sleep infinity),在控制台终端里直接跑 curl、
ping、nslookup、traceroute,用来排查连通性、DNS 与网格问题。用完删掉即可,它不常驻。