私有化部署概览
服务之间的依赖、两条部署路径的取舍、集群与网络的准备条件。决定要装之后再往下读。
← 文档索引
组件与依赖
装起来是 19 个 Service 加一个定时任务(逐个见 Service 与端口)。它们之间的调用形状很固定:
每条线内部都是 web → gateway → 后端 三级,于是只需要认识跨线的那九条边——接错线时出问题的一定在这里。
这张表只列「边」和断裂后的表现,不列变量:每条边由哪个变量接线见变量之间的指向关系,
变量本身的来源与默认值在逐服务手动部署对应小节里。
| 调用方 | 被调用方 | 断了会怎样 |
|---|---|---|
thia-gateway |
themis-auth |
解析不出用户与角色,控制台整片认证失败 |
rhea-gateway |
themis-auth |
组织钱包打不开(读不到组织归属) |
phoebe-gateway |
themis-auth |
用户目录与获客统计为空 |
themis-auth |
rhea-payment |
注册赠分不发;注册本身不受影响 |
themis-auth |
rhea-email |
验证信、重置信、邀请信发不出 |
themis-auth |
rhea-push |
告警推不出去(需同时配 ALERT_WEBHOOK_URL 才启用) |
thia-gateway |
rhea-payment |
Stripe 回调打不进来,充值不到账 |
phoebe-gateway |
thia-agent |
用量与调用统计为空 |
phoebe-gateway |
rhea-payment |
积分统计为空 |
产品线层面则是这一条,它直接回答了最常见的问题——能不能只装一部分:
- Rhea 与 Themis 是一对底座,要一起装。Themis 借 Rhea 发验证信与赠分,Rhea 借 Themis 的组织信息——两个方向都不报错,只是邮件不发、组织钱包不可用。装 Theia 之前先把这两个装齐。
- Themis 是唯一的登录入口:所有控制台都通过它认证,换 IdP 等于换掉所有控制台的登录。
- Tethys 是可选的,只有需要私有化打包发布与集群管理台时才安装。
- Theia 内部可以裁剪,工具服务(
mcp-*)按需安装,不影响主体。 - Phoebe 完全只读,摘掉它其他线照常运转。
换句话说,您可以先从最小的一组开始用,之后再按需要往上加,不必一次装全。
定时任务(必需)
系统里有一类工作在后台按节奏发生:心跳巡检、记忆整理去重、积分结算入账。它们由一个 定时任务触发,没有它,系统照样装得上、页面照样打得开,只是这三件事永远不发生—— 而且失败是静默的,事后很容易被当成「功能没做」。
它不随 Bundle 走——导出的 Bundle 里没有 scheduledTaskPacks,要在 apply 完 Bundle 之后单独
apply 一份清单(agent 仓 k8s/thia-jobs-tick.yaml,一个 ConfigMap + 一个 CronJob)。两条部署路径的
装法见「一键部署 / 定时任务」与
「逐服务手动部署」里的 thia-jobs-tick 一节。
两条部署路径
本文档中的
<>都是占位符,请替换为您环境中的真实值。域名一律用titanides.com及其子域 举例;示例名字都是假的,换成您的即可。文档里不会出现我们的 内网地址、凭据或示例密钥——如果您手里的版本出现了,说明拿到的是错误的副本。
同一套系统可以用两种方式装进集群,两者的产出必须等价。选哪条取决于场景,不取决于功能:
| 路径 A:Bundle 一键部署 | 路径 B:逐服务手动部署 | |
|---|---|---|
| 适合 | 首次安装、日常升级 | 排障、定制、安全审计 |
| 操作量 | 一份 YAML | 每个服务一份清单 |
| 出错时能改什么 | 改 Bundle 字段 | 改任意一处 |
| 对客户的要求 | 会 kubectl apply |
会读 Deployment 清单 |
日常用 A,出问题时用 B。「路径 B:逐服务手动部署」的每一步都会标注它在 Bundle 里对应哪个 pack, 这样两条路径可以互相校对。
路径 B 不是"备用方案"。它是路径 A 的展开视图——Bundle 的每个
pack展开后就是一个 Deployment。 写 B 的过程会反过来暴露 A 的 spec 漏掉了什么。
引导方式:集群内还是集群外
上面两条路解决「装什么」;还有一层独立的「谁去调 K8s API」,它和路径 A 组合出两种落地:
| 引导方式 | 怎么操作 | 什么时候用 |
|---|---|---|
集群内 kubectl apply |
按「一键部署」的底座三步走,再 apply Bundle | 默认。可复现,失败点最少 |
| 集群外本机 tethys | 本机跑三件 tethys 连集群,在界面里建 operator、加租户、导入 Bundle | 不想碰 YAML,或远程给客户装;见「集群外引导」 |
路径 B 不进这张表:逐服务手动部署本身就是 kubectl 操作,没有界面形态。
三种落地(集群内 Bundle / 界面导入 Bundle / 逐服务)产出的是同一套对象,差别只在谁执行、 手里有几份凭据。
前置条件
装之前请确认下面这些已经就绪。它们大多是您集群里本来就有的基础设施,不需要为我们单独采购; 真正需要事先申请的只有一个根域名(用它的子域就够)和对应的证书。
| 项目 | 要求 | 说明 |
|---|---|---|
| Kubernetes | 实测 v1.33(MicroK8s);更低的版本见下方警告 | 从零搭环境见集群准备 |
| Istio | 实测 1.30.2 | 需要 Gateway + VirtualService,见安装 Istio |
| PostgreSQL | 单一实例,按 schema 隔离;必须带 pgvector |
全部服务共用一个库,不按服务拆,见配置数据库 |
| 域名 | 一个根域名即可,子域不额外申请 | 身份用 accounts.titanides.com,网关用 gateway.titanides.com,控制台用 console.titanides.com;同一根域下跨子域是同站,Cookie 与 SSO 都不会遇到跨站限制 |
| TLS 证书 | 上述域名各一张 | 集群内或集群外终止均可 |
| 镜像仓库 | 可拉取我方镜像 | 私有仓库需提供 imagePullSecret |
| 对象存储(可选) | 任意 S3 兼容;我方线上用 Cloudflare R2 | 生成图片 / 视频的持久链接与站点素材。不配也能跑:结果退回模型方的临时 URL、展示区退化,见对象存储与静态资源 |
⚠️ Kubernetes 版本的支持范围以实测为准,不靠推断。 负责部署的 operator 编译时依赖的 客户端库版本比我们的参考环境更早,跨版本兼容性我们不会凭推断承诺。签约前,我们会在您的 目标版本集群上完整执行一次 Bundle 部署,再把支持范围写进交付文档。
网络要求
thia-gateway与themis-gateway需要从外部可达。themis-auth不应暴露到集群外。 浏览器做 OIDC 时访问的是themis-gateway的/authorize、/token、/jwks与/.well-known/openid-configuration,由网关代理给它; 其余调用(thia-gateway、rhea-gateway、phoebe-gateway)都在集群内直连。- 全部服务内部通信走 Kubernetes Service,不上 TLS(靠 Istio mTLS,如果启用)。
端口约定
所有 Service 的统一惯例是 port 80 → targetPort = 容器实际端口。Istio 路由里
填的也是 Service 端口 80,不是容器端口。自己写清单时这是最容易错的一处。
逐个服务(含容器端口、探针路径、要不要公网)见 Service 与端口。
那里面还有一条:探针路径不统一——有的在根路径,有的在 /api/v1 下面,Next.js 站点干脆没有。
域名、证书与 CDN
公网访问链路上有三件事容易混为一谈:DNS 记录、TLS 终止点、主机名绑定的服务。它们可以 分别配置,改动其中一处时要确认另外两处没跟着变。
- 一个主机名只能绑定一个服务。 把
gateway.titanides.com同时绑到两个网关,后绑定的生效, 另一条路径会静默 404。症状具有误导性:同一个域名下/api/v1/...能拿到数据,/graphql却是 404、预检返回 204 但没有Access-Control-Allow-Origin——看着像 CORS 配错,其实 是请求打到了别的服务。 - 浏览器读到的地址必须是公网地址。 服务之间调用的地址填 Service 名,但下发给浏览器的
地址(如
tethys-web的endpoint/wsEndpoint)必须填https://console.titanides.com; Service 名在用户浏览器里解析不到。 - TLS 通常在集群外终止。 nginx 或负载均衡持有证书,回源明文或再加密都行;证书在这一层 续期,集群内不需要知道。自建这一层的完整配置(含 WebSocket、上传上限与超时)见 边缘 nginx。
如果前面挂 CDN(以 Cloudflare 橙云为例,逐项配置见前置 Cloudflare),浏览器到边缘、边缘到源站是两段独立的 TLS: 浏览器看到的是 CDN 自己的证书,回源时 CDN 作为客户端去校验证书,不会替换源站那张。
- 回源加密选 Full (strict):源站证书的域名、有效期、证书链都要能通过校验。边缘配置要指向
fullchain.pem而不是cert.pem——CDN 不会像浏览器那样自动去抓中间证书。 - 源站看到的客户端 IP 会变成 CDN 的地址段。需要真实 IP 时,在边缘启用
real_ip_header(Cloudflare 是CF-Connecting-IP)并信任官方地址段,否则日志、限流、按 IP 的排查全部失效。 - 免费套餐单请求 body 上限 100 MB;有大文件上传接口时先实测一次,否则只会在用户上传时 才看到 413。
- 证书续期(HTTP-01)会从 CDN 边缘回源到
/.well-known/acme-challenge/,只要这条路径没被 规则拦住、没有被强制跳到别处,就照常通过。切换后执行一次certbot renew --dry-run。 - 切换后权威 DNS 是秒级生效,其余看旧记录的 TTL:TTL 300 即最多 5 分钟,浏览器自身的 DNS 缓存可能再拖几分钟。