DEPLOYMENT · 三套编排

部署方式Compose · Nomad · Helm

同一套镜像,三种编排方案,对应三类交付场景:客户单机 VM、内部集群、云托管 Kubernetes。基础设施依赖完全一致,差异只在调度层与资源声明方式。

7
Compose 服务 · 单 VM 全栈
3
编排方案 · 镜像共用
4
有状态依赖 · PG/Redis/Milvus/S3
24
Helm 模板文件
01 — 服务拓扑

七个服务,三层依赖

以客户 VM 的 Compose 方案为基准,这是最完整也最能看清依赖关系的形态。

db-init
一次性迁移任务 · 建库建表 · 完成即退出
document-intelligence
文档识别容器 · 须 healthy 后其余服务才启动
api
ASP.NET Core · 用户与管理接口 · AI 网关 · :8080
job
异步任务执行器 · 入库管线与长任务 · 可水平扩展
web
前端静态资源
lgtm
可观测性栈 · 日志指标追踪
nginx
统一入口 · TLS 终止 · 路由分发
启动顺序:db-initdocument-intelligence(healthy)→ api / job / webnginx

外部依赖

PostgreSQL
主数据库。平台数据与应用数据分 schema 隔离,个人工作区使用独立 opsmate schema
Milvus
向量库。按知识库维度隔离 collection,支持 dense 与 sparse 双通道
Redis
缓存与任务队列
S3 / MinIO
对象存储。原始文件、解析产物、数据仓 Parquet 均落于此
Foundry
云端推理服务。gpt-5.4 对话模型,经 AI 网关统一代理
Document Intelligence
文档识别。以容器形态部署在内网,临床文档不出网
02 — 三套方案

按交付场景选择

方案 A · Docker Compose
客户单机 VM
面向客户内网单台高配 VM 的完整交付。模板经 envsubst 渲染镜像仓库与标签,其余变量运行期从 .env 解析,不硬编码。资源按 limits 与 reservations 两级声明——reservations 走 cgroups 软保证作为容量基线,limits 作为单容器 burst 天花板,允许适度超订换取尾延迟弹性。
方案 B · Nomad
内部集群
以 Terraform 管理作业定义与基础设施模块。用于内部测试与预发环境,配套环境状态检查脚本与分环境部署文档。
方案 C · Helm
Kubernetes 托管
24 个模板覆盖全部组件,含 API 水平自动扩缩、有状态组件 StatefulSet、迁移 Job、Ingress。提供 AKS 与 EKS 两套 values,以及一份生产部署 values。
03 — 配置要点

容易踩的几处

模型池
模型配置存在数据库里,不在环境变量里。环境变量只提供网关 master key 与默认池标识(embedding 默认 bge-m3、rerank 默认 reranker)。实际模型端点与凭据由网关按池查库获取,支持运行期切换而无需重启。
迁移顺序
db-init 必须先于 api 与 job 完成。迁移镜像已做 schema 无关化改造,可在多 schema 环境下正确执行。
DI 健康检查
文档识别容器启动较慢且是入库管线硬依赖,编排中显式声明 healthy 依赖。若跳过此检查,job 会在首批入库任务上连续失败。
Job 并发
入库管线为 IO 与模型调用密集型,job 服务按并发需求横向扩展。客户 VM 方案中规划 2 到 4 个实例。
前端主机白名单
开发态前端需在构建配置中声明允许的访问主机名。经反向代理暴露时若未加入白名单,将被前端开发服务器拒绝,表现为 403。
历史遗留 · 注意甄别

仓库中仍保留 src/vllm 目录、本地 GPU 模型部署脚本,以及客户 VM 模板中基于 8 张 A100 的资源规划注释。这些属于早期内网自建推理服务方案,当前生产已全面改用 Foundry 托管模型,内网仅保留 Document Intelligence。阅读部署材料时须区分,勿按 GPU 方案准备硬件。

04 — 数据落地形态

结构化数据不进 Postgres 表

这是运维时最容易误判的一点。个人工作区抽取出的事实数据,不以 Postgres 表形式存储

STEP 01
用户上传文件
原始文件落对象存储
STEP 02
识别规则匹配
按预置规则判定文件类型与目标表
STEP 03
用户确认抽取
字段映射可编辑,确认后才写入
STEP 04
落为 Parquet
写入对象存储,附 manifest
STEP 05
DuckDB 读时查询
Postgres 仅存元数据与行数
运维提示 · DuckDB 原生库

查询侧依赖 DuckDB 原生动态库。托管 NuGet 包不含原生库文件,若镜像未内置,表现为写入正常、元数据行数正确,但读取接口返回 500、前端显示「暂无数据」。这个故障形态具有欺骗性——日志与元数据都显示成功,只有实际读取才暴露。镜像重建后需确认该依赖仍在。

05 — 相关文档

继续阅读

系统全貌
项目历史、模块结构、自研 PIKE-RAG 的实现路径。
理论基础
四类问题分级与两项核心方法。
编排实现
为何只用 Agent、十六章如何组织。