配置数据库
一个 PostgreSQL 实例,承载四类使用者。建库、扩展、账号与连接数在这里一次做完,后面各服务的安装章节只填连接串。
← 文档索引 · 上一章:安装 Istio · 下一章:边缘 nginx
1. 只有一个数据库实例
FewBox 不按服务拆库。用户、积分账本、会话消息、Agent 定义、任务与心跳都在同一个 PostgreSQL 实例里,靠 schema 与表名前缀隔离。理由很直接:跨服务的数据一致性(注册赠分、账本与订阅)如果拆 库就变成分布式事务,而单机 POC 与中等规模交付根本不需要那个复杂度。
| 使用者 | 连接方式 | 存什么 | 建表脚本 |
|---|---|---|---|
themis-auth |
DATABASE_URL |
用户、组织、凭据、OIDC 客户端、会话 | themis-auth-init.sql,全文见数据库表结构 |
thia-agent |
DATABASE_URL |
会话与消息、附件、记忆向量、Agent 定义、定时任务 | thia-agent-init-db.sql,全文见数据库表结构 |
rhea-payment |
DATABASE_URL |
订单、额度、流水、套餐、Stripe 映射 | rhea-payment-init-db.sql,全文见数据库表结构 |
mcp-analysis |
PG_DATABASES(JSON 数组) |
不建表,只读查询上面几个库 | — |
rhea-payment的DATABASE_URL不配也不会启动失败——它会退回内存存储:界面有余额、重启 归零、库里查不到行。这是最容易被误判为"功能未实现"的一类问题,装完必须到库里确认存在一行真实数据。
2. 版本与扩展
| 要求 | 值 | 不满足会怎样 |
|---|---|---|
| PostgreSQL | 14 及以上(参考环境 15+) | 语法与索引类型差异,迁移可能中途失败 |
pgvector |
必须 | thia-agent 的 vector(1024) 列建不出来,记忆与会话相关表迁移失败 |
| 编码 | UTF8 | 中文内容与 emoji 存储异常 |
| 时区 | UTC | 「每天 9 点」这类定时任务按库时区换算,错位后很难发现 |
装扩展(需要超级用户或有 CREATE EXTENSION 权限的账号):
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_trgm; -- 模糊搜索,可选但建议
验证:
SELECT extname, extversion FROM pg_extension;
3. 账号:最少三个
| 账号 | 权限 | 给谁 |
|---|---|---|
| 迁移账号 | 建表、建扩展、改结构 | 只在安装与升级时用,不进任何 Deployment |
| 应用账号 | 目标 schema 内的 SELECT/INSERT/UPDATE/DELETE |
三个服务共用(同一个库,靠 schema 分隔) |
| 只读账号 | 仅 SELECT,建议加 statement_timeout |
mcp-analysis |
不要把超级用户连接串写进 Deployment。 应用侧不需要 DDL 权限,给多了以后一次误操作就能改掉 表结构。迁移使用单独账号,在集群外执行。
4. 连接数:先算,再配
每个服务进程持有一个连接池。池大小是每个 Pod 的,所以总量是乘出来的:
峰值连接数 ≈ Σ(每个服务的副本数 × 该服务的池上限) + 迁移/排障占用 + 余量
参考环境的口径(单副本,池上限 10):themis-auth 10 + thia-agent 10 + rhea-payment 10 + mcp-analysis 5 + 余量 5 ≈ 40。如果您的托管 PG 默认 max_connections=60,这已经吃掉三分之二,
再开一个副本就会连不上。
两条经验:
- 托管服务通常在前面放连接池代理(PgBouncer 一类)。事务模式的代理不支持会话级的
prepared statement / 临时表;如果出现
prepared statement ... does not exist,先确认代理模式, 再决定改驱动还是改代理模式,不要急着调大max_connections; - 副本数翻倍前先算一次池总量。这个故障的表现是间歇性 500 与超时,日志里是
too many clients, 不是启动失败。
每个服务的池参数在哪配:thia-agent 在镜像内的 config/agentic.yaml(store 段)或环境变量;
themis-auth / rhea-payment 走连接串参数(如 ?max=10)。改完必须重启 Pod——环境变量不会热更新。
5. 建表:顺序比内容重要
每个库一份初始化脚本,都是全量的——新建的库执行一遍即可,不需要再补历史迁移文件。 三段脚本全文与逐段执行命令见数据库表结构,互不依赖,但顺序有要求:
- 先建库与扩展(本文第 2 节);
- themis-auth —— 它没有别的依赖;
- thia-agent —— 必须在建定时任务之前,否则任务运行时静默降级为关闭,
/jobs/*返回disabled,进程不退出; - rhea-payment —— themis-auth 的注册赠分要写
user_credits,缺表时注册仍成功,赠分静默不发。
执行时带上 psql -v ON_ERROR_STOP=1,否则中途失败不会中断,后面的语句照跑。
漏了建表不会报错。 启动成功、探针全绿、页面能开,直到某个功能第一次查那张表才 500。 装完必须按手动部署每节末尾的验证命令执行一遍。
6. 装完自检
# 连通性(从集群内一个 Pod 里执行,验证的是 Service 与网络策略,不只是主机)
kubectl -n <命名空间> exec deploy/<任一无状态服务> -- \
psql "$DATABASE_URL" -c 'select version();'
# 扩展
psql "$DATABASE_URL" -c "select extname from pg_extension where extname='vector';"
# 表是否真的建了(三个库各看一眼)
psql "$DATABASE_URL" -c '\dt' | head -20
# 连接数与上限
psql "$DATABASE_URL" -c 'show max_connections;'
psql "$DATABASE_URL" -c 'select count(*) from pg_stat_activity;'
最后一条在服务全部启动之后再看——空载时的数字不具参考价值。
7. 备份
备份只有三样:PostgreSQL、密钥、Bundle。数据库是唯一"重建不出来"的,其余在
升级、回滚与备份里。最低要求:每天一次 pg_dump -Fc,保留 7 份;升级前
额外做一份。恢复演练一年至少一次——没演练过的备份不算备份。