软件部署
OmniCortex 官方容器镜像支持从单机开箱即用极速体验到对接企业级外部数据库的高可用生产集群全套部署形态。官方纯净镜像内置了 Web 管理控制台与全量自研扩展插件,支持 linux/amd64 与 linux/arm64 双 CPU 架构,拉取镜像即可独立启动运行。
一、 获取官方镜像
OmniCortex 提供官方标准多架构容器镜像,无需本地编译即可快速获取:
docker pull omnicortex/omnicortex:latest镜像核心特性:
- 纯净单镜像集成:单个容器镜像已完整集成网关引擎内核、自研扩展插件以及现代化 Web 前端管理控制台;
- 全架构支持:原生支持
linux/amd64(x86_64 生产服务器)与linux/arm64(Apple Silicon、Graviton 等 ARM 架构); - 自适应启动引擎:内置自适应启动脚本,依据环境变量自动在 SQLite 本地嵌入式模式与外部 PostgreSQL + Redis 集群模式之间无缝切换。
二、 部署形态选型与拓扑架构
根据业务评估与落地阶段,OmniCortex 提供两种核心部署形态:
三、 形态一:快速启动实操 (开箱即用)
适用于本地评估与 PoC 阶段,无需外部基础设施依赖。
3.1 极简轻量启动 (内置 SQLite,单容器零依赖)
通过一条命令拉起网关,自动持久化配置与审计日志至宿主机本地:
# 1. 创建本地持久化数据目录 (避免 Linux 下 Docker 自动创建目录引发权限异常)
mkdir -p ./data
# 2. 启动网关容器
docker run -d \
--name omnicortex \
-p 8080:8080 \
-v "$(pwd)/data:/app/data" \
omnicortex/omnicortex:latest运行机制说明:
- 容器内部自动检测到无外部数据库环境变量,自动以 SQLite 模式运行;
- 宿主机
./data目录下将自动生成并持久化维护两座嵌入式数据库:omnicortex.db:主业务配置数据库(纳管模型、供应商凭证池、团队架构、RBAC 用户与访问策略等);logs.db:LLM 全量调用审计日志库与安全拦截记录;
- 启动成功后,浏览器访问
http://localhost:8080即可进入 Web 管理控制台。
3.2 一体化全栈尝鲜 (内置独立 PG 16 + Redis 容器)
若希望体验完整的 PostgreSQL 审计索引与 Redis 缓存能力,但本地缺乏外部数据库服务,可通过 Docker Compose 在同一网络下编排全套独立组件:
# docker-compose.yml (一体化尝鲜版)
version: '3.8'
services:
# 本地专用 PostgreSQL 数据库
postgres:
image: postgres:16-alpine
container_name: omnicortex-demo-pg
environment:
POSTGRES_USER: omnicortex
POSTGRES_PASSWORD: omnicortex_password
POSTGRES_DB: omnicortex
volumes:
- pg_data:/var/lib/postgresql/data
ports:
- "5432:5432"
restart: unless-stopped
# 本地专用 Redis 缓存
redis:
image: redis:7-alpine
container_name: omnicortex-demo-redis
ports:
- "6379:6379"
restart: unless-stopped
# OmniCortex 统一网关
omnicortex:
image: omnicortex/omnicortex:latest
container_name: omnicortex-demo-app
depends_on:
- postgres
- redis
ports:
- "8080:8080"
environment:
- DB_TYPE=postgres
- POSTGRES_HOST=postgres
- POSTGRES_PORT=5432
- POSTGRES_USER=omnicortex
- POSTGRES_PASSWORD=omnicortex_password
- POSTGRES_DB=omnicortex
- POSTGRES_AUTO_CREATE_DB=true
- REDIS_URL=redis://redis:6379/0
- ENABLE_VECTOR_STORE=false
- GOGC=200
- GOMEMLIMIT=1800MiB
ulimits:
nofile:
soft: 65536
hard: 65536
restart: unless-stopped
volumes:
pg_data:在同级目录下执行启动命令:
docker compose up -d四、 形态二:生产高可用集群部署 (直连外部数据库服务)
在企业级生产环境中,数据库与缓存通常由高可用基础设施(如云厂商托管 RDS、自建 PostgreSQL 物理主从高可用集群、Redis Sentinel/Cluster)提供。
在此模式下:
- 纯无状态计算节点:每个 OmniCortex 容器均为纯粹的无状态网关实例,容器内不运行任何数据库进程;
- 多节点共享存储:集群中的所有网关节点共享同一套外部 PostgreSQL 数据库;
- 毫秒级集群热同步:通过外部 Redis 的 Pub/Sub 通道,激活内置的
ext_cluster_sync插件。当运维管理员在任意一个节点的控制台上更新模型配置、轮换密钥或调整限流策略时,变更将在毫秒级实时热广播至集群中所有节点,无需重启进程或重载配置; - 水平自由扩缩容:前端配合云厂商负载均衡器(ALB/SLB)或 Nginx/HAProxy,随时增减网关容器副本数(Replicas)。
4.1 生产集群 Compose 编排 (多节点水平扩展)
以下编排展示了多节点生产网关直连企业外部 RDS 与 Redis 的标准范式:
# docker-compose.cluster.yml (生产无状态集群 - 直连外部基础设施)
version: '3.8'
services:
# ============================================================================
# OmniCortex 生产无状态网关节点 1
# ============================================================================
omnicortex-node-1:
image: omnicortex/omnicortex:latest
container_name: omnicortex-prod-node1
ports:
- "8080:8080"
environment:
- APP_PORT=8080
- APP_HOST=0.0.0.0
- LOG_LEVEL=info
- LOG_STYLE=json
- GOGC=200
- GOMEMLIMIT=1800MiB
# 外部 PostgreSQL 数据库连接 (填写云 RDS 或已有 PG 集群地址)
- DB_TYPE=postgres
- POSTGRES_HOST=192.168.1.100
- POSTGRES_PORT=5432
- POSTGRES_USER=omnicortex_app
- POSTGRES_PASSWORD=your_rds_secure_password
- POSTGRES_DB=omnicortex
- POSTGRES_SSLMODE=disable
- POSTGRES_AUTO_CREATE_DB=false # 生产环境建议保持默认关闭,由 DBA 预建库
# 外部 Redis 服务连接 (负责节点间配置更新实时热广播)
- REDIS_URL=redis://:your_redis_password@192.168.1.101:6379/0
ulimits:
nofile:
soft: 65536
hard: 65536
healthcheck:
test: ["CMD", "wget", "--no-verbose", "--tries=1", "-O", "/dev/null", "http://localhost:8080/health"]
interval: 15s
timeout: 5s
retries: 3
restart: unless-stopped
# ============================================================================
# OmniCortex 生产无状态网关节点 2 (同机或跨主机水平扩展)
# ============================================================================
omnicortex-node-2:
image: omnicortex/omnicortex:latest
container_name: omnicortex-prod-node2
ports:
- "8081:8080"
environment:
- APP_PORT=8080
- APP_HOST=0.0.0.0
- LOG_LEVEL=info
- LOG_STYLE=json
- GOGC=200
- GOMEMLIMIT=1800MiB
- DB_TYPE=postgres
- POSTGRES_HOST=192.168.1.100
- POSTGRES_PORT=5432
- POSTGRES_USER=omnicortex_app
- POSTGRES_PASSWORD=your_rds_secure_password
- POSTGRES_DB=omnicortex
- POSTGRES_SSLMODE=disable
- POSTGRES_AUTO_CREATE_DB=false
- REDIS_URL=redis://:your_redis_password@192.168.1.101:6379/0
ulimits:
nofile:
soft: 65536
hard: 65536
healthcheck:
test: ["CMD", "wget", "--no-verbose", "--tries=1", "-O", "/dev/null", "http://localhost:8080/health"]
interval: 15s
timeout: 5s
retries: 3
restart: unless-stopped启动生产集群:
docker compose -f docker-compose.cluster.yml up -d4.2 生产集群 Docker CLI 纯命令启动 (直连外部服务)
如果不借助 Docker Compose,也可以直接使用 docker run 命令启动无状态网关实例:
# 启动节点 1
docker run -d \
--name omnicortex-node1 \
-p 8080:8080 \
-e DB_TYPE=postgres \
-e POSTGRES_HOST=192.168.1.100 \
-e POSTGRES_PORT=5432 \
-e POSTGRES_USER=omnicortex_app \
-e POSTGRES_PASSWORD=your_rds_secure_password \
-e POSTGRES_DB=omnicortex \
-e POSTGRES_SSLMODE=disable \
-e REDIS_URL=redis://:your_redis_password@192.168.1.101:6379/0 \
-e GOGC=200 \
-e GOMEMLIMIT=1800MiB \
--ulimit nofile=65536:65536 \
omnicortex/omnicortex:latest
# 在另一台机器或同机不同端口启动节点 2 (加入集群多活)
docker run -d \
--name omnicortex-node2 \
-p 8081:8080 \
-e DB_TYPE=postgres \
-e POSTGRES_HOST=192.168.1.100 \
-e POSTGRES_PORT=5432 \
-e POSTGRES_USER=omnicortex_app \
-e POSTGRES_PASSWORD=your_rds_secure_password \
-e POSTGRES_DB=omnicortex \
-e POSTGRES_SSLMODE=disable \
-e REDIS_URL=redis://:your_redis_password@192.168.1.101:6379/0 \
-e GOGC=200 \
-e GOMEMLIMIT=1800MiB \
--ulimit nofile=65536:65536 \
omnicortex/omnicortex:latest五、 环境变量完整参考手册
通过环境变量,可以在启动容器时无侵入覆盖所有系统配置,无需挂载静态配置文件:
| 环境变量 | 默认值 | 生产建议值 | 作用说明 |
|---|---|---|---|
APP_PORT | 8080 | 8080 | 网关服务在容器内的监听端口。 |
APP_HOST | 0.0.0.0 | 0.0.0.0 | 服务监听网络地址(容器内保持 0.0.0.0)。 |
LOG_LEVEL | info | info | 日志输出级别:debug, info, warn, error。 |
LOG_STYLE | json | json | 日志输出格式:json(适合企业日志采集分析)或 pretty。 |
DB_TYPE | sqlite | postgres | 存储引擎类型。配置为 postgres 时激活外部数据库模式。 |
POSTGRES_HOST | localhost | (RDS地址) | PostgreSQL 服务主机地址(设置该项会自动触发外部 PG 模式)。 |
POSTGRES_PORT | 5432 | 5432 | PostgreSQL 服务端口。 |
POSTGRES_USER | omnicortex | (业务账号) | PostgreSQL 数据库认证用户。 |
POSTGRES_PASSWORD | omnicortex_secret | (强密码) | PostgreSQL 数据库认证密码。 |
POSTGRES_DB | omnicortex | omnicortex | 主业务配置数据库名称(存储模型、凭证、策略、团队等元数据)。 |
POSTGRES_LOGS_DB | (同 POSTGRES_DB) | (按需独立分库) | 独立请求审计日志库名称。支持配置库与审计日志物理分库存储。 |
POSTGRES_SSLMODE | disable | disable / require | PostgreSQL SSL 连接模式:disable, require, verify-full。 |
POSTGRES_AUTO_CREATE_DB | false | false | 自动建库开关:若为 true,容器启动时自动探测并创建数据库(模拟 IF NOT EXISTS)。生产环境建议保持 false 由 DBA 预建库。 |
REDIS_URL | (空) | redis://... | Redis 连接串。配置后自动激活 ext_cluster_sync 多节点热同步广播插件。 |
ENABLE_VECTOR_STORE | false | false | 外部向量库挂载开关:仅在启用复杂路由语义向量(Embedding)决策器时设为 true;若使用标准规则决策引擎(Rules / Heuristic),完全无需开启,保持默认 false 即可。 |
VECTOR_STORE_TYPE | redis | redis | 外部向量库类型(默认 redis,依赖包含 RediSearch 扩展的 Redis Stack)。 |
GOGC | 200 | 200 | Go 运行时垃圾回收阈值。高吞吐生产环境建议 200,受限低内存环境建议 100。 |
GOMEMLIMIT | 1800MiB | (内存限额90%) | Go 运行时软内存上限。建议配置为容器物理内存限额的 85%~90%,防止触发 OOM Killer。 |
六、 PostgreSQL 自动建库与生产安全实践
PostgreSQL 协议要求握手连接时目标数据库必须预先存在,否则握手直接报错断开连接。OmniCortex 为此提供了开箱即用的安全建库流水线与生产最佳实践:
💡 开发 / 测试 / 快速 PoC 场景(推荐开启)
配置环境变量 -e POSTGRES_AUTO_CREATE_DB=true。
容器启动时会自动连接 PostgreSQL 维护库(postgres),安全模拟 IF NOT EXISTS 查询系统元数据表;若目标库不存在则自动创建,并显式指定 UTF8 编码与 OWNER。即使集群多节点并发冷启动,也能自动容错并发冲突。
⚠️ 企业生产环境与托管云 RDS(推荐保持默认关闭)
生产环境遵循最小权限原则 (Least Privilege),DBA 分配给业务系统的账号通常没有 CREATEDB 权限,且禁止访问维护库。
在生产部署中,请保持 POSTGRES_AUTO_CREATE_DB=false(默认值),由 DBA 预先创建好主数据库(如 omnicortex)后,网关容器直接连接目标库,并在启动时自动执行表结构与元数据的版本化安全迁移。
七、 生产高并发性能调优与资源规划
要在企业生产环境中支撑数千 RPS 的高并发调度与低延迟穿透,建议在容器编排中落实以下工程优化配置:
7.1 CPU 核心自动感知 (GOMAXPROCS)
OmniCortex 内置集成了 automaxprocs 驱动,容器启动时会自动识别 Linux cgroup CPU Quota 配额(例如 Kubernetes 的 CPU limits),并动态调整 Go 运行时的工作线程池大小,无需在环境变量中手动指定 GOMAXPROCS。
7.2 垃圾回收与内存硬边界保护
- GC 阈值调优 (
GOGC=200):网关内核采用深度对象复用池技术,在高并发场景下将 GC 触发阈值从 Go 默认的 100 调整至 200,可显著降低垃圾回收带来的 CPU 抖动,提升系统吞吐吞吐能力; - 软内存上限保护 (
GOMEMLIMIT):为了防止在流量激增时突发内存占用触发 Linux 内核的 OOM Killer 导致进程被强杀,必须配置GOMEMLIMIT。建议公式为: $$\text{GOMEMLIMIT} = \text{容器内存上限} \times 90%$$
7.3 系统句柄与连接上限 (ulimits)
Linux 容器默认通常仅分配 1024 个文件句柄。在高并发 HTTP 长连接与大模型流式 SSE(Server-Sent Events)推送场景下,短时间内会耗尽句柄并抛出 too many open files 错误。在所有生产 Compose 与 Kubernetes Pod 描述文件中,务必调大系统句柄上限:
ulimits:
nofile:
soft: 65536
hard: 655367.4 容器规格选型与资源推荐表
根据预期的网关并发吞吐规模(RPS),参考下表规划计算资源配额:
| 预期网关 RPS 规模 | 推荐 CPU 配额 | 推荐内存 (RAM) | 推荐 GOMEMLIMIT | 推荐 GOGC | 建议 ulimits nofile |
|---|---|---|---|---|---|
| 100 ~ 500 RPS | 1 ~ 2 核 | 1 GB | 900MiB | 100 ~ 200 | 16384 |
| 500 ~ 2000 RPS | 2 ~ 4 核 | 2 GB | 1800MiB | 200 | 65536 |
| 2000 ~ 5000 RPS | 4 ~ 8 核 | 4 GB | 3600MiB | 200 | 65536 |
| 5000+ RPS | 8+ 核 | 8 GB+ | 7200MiB | 200 ~ 400 | 65536+ |
7.5 容器健康检查与服务探活
网关内置了极轻量的探活端点 /health,支持被 Kubernetes Liveness/Readiness 探针或企业负载均衡器(F5/Nginx/SLB)调用:
curl -f http://localhost:8080/health返回 HTTP 200 状态码即代表网关内核与关键路由管道处于正常健康运行状态。
八、 下一步行动指南
完成软件部署后,建议按照以下指引展开业务接入与全流程验证:
- 2.1 5分钟极速起步 (getting-started.md) —— 按照 4 步指引快速完成模型纳管、策略配置与首条 API 调用;
- 2.3 企业管理控制台导览 (console-tour.md) —— 探索控制台全模块动线、组织工作区与安全中心全景操作;
- 2.4 模型调试中心 (model-playground.md) —— 零代码跨模型参数对比、多轮会话测试与流式思考体验;
- 3.1 统一模型资产目录 (model-catalog.md) —— 统一纳管企业内多云商用与私有开源大模型资产;
- 4.1 团队与组织架构划分 (teams-organization.md) —— 建立部门级多团队协作与配额隔离。