TeGo-AI 标准生产部署文档

本文档定位为 4 服务器分离部署模式下的标准生产部署操作指南，旨在为技术人员提供标准化的部署配置参考。其核心价值在于通过服务分层部署提升系统稳定性与可扩展性，保障生产环境下中等规模并发业务的可靠运行，适用于企业日常生产环境搭建与业务支撑场景。

服务分布

四服务器部署架构中，采用"业务服务与基础服务分离"策略，通过清晰的服务分层设计实现资源隔离与负载均衡。服务分布矩阵如下：

服务层级 服务名称 部署节点 核心作用
负载均衡层 tego-proxy biz-node1、biz-node2（双节点冗余） 统一负载均衡，分发请求到业务节点
业务服务层 tego-os biz-node1、biz-node2（双节点冗余） 前端统一操作界面
tego-os-server biz-node1、biz-node2（双节点冗余） 后端API服务
tego-mcp biz-node1、biz-node2（双节点冗余） MCP服务，实现向量搜索等功能
tego-llm biz-node1、biz-node2（双节点冗余） LLM网关服务
tego-engine-main biz-node1、biz-node2（双节点冗余） 工作流主控节点
tego-engine-worker biz-node1、biz-node2（双节点冗余） 工作流执行节点
基础设施层 postgres-master infra-node（主节点） 主数据库，存储业务核心数据
redis infra-node（单点部署） 缓存/消息队列服务，提升数据访问性能
openldap infra-node（单点部署） 统一认证服务，管理用户身份与权限
embedding infra-node（单点部署） AI嵌入服务，生成与存储向量数据
灾备服务层 postgres-slave backup-node（从节点） 从数据库，同步主库数据并提供只读查询
data-sync backup-node（专用节点） 跨节点数据同步服务，支撑主从数据一致性

服务分布核心原则

  • 业务服务双节点冗余：负载均衡层与业务服务层所有服务在两台业务节点同时部署，通过负载均衡器实现请求分发与故障自动切换，保障业务连续性。
  • 基础设施集中部署：数据库、缓存、认证等核心基础服务集中部署在专用基础设施节点，减少资源竞争，提升数据安全性。
  • 灾备服务独立部署：备份节点独立运行从数据库与数据同步服务，通过实时同步机制实现数据容灾，确保在主节点故障时可快速切换。

环境配置

网络配置

四服务器部署环境需配置独立内网通信链路，确保节点间数据传输的稳定性与安全性。假设四台服务器配置如下内网IP：

  • 业务节点1（biz-node1）：192.168.1.10
  • 业务节点2（biz-node2）：192.168.1.11
  • 基础设施节点（infra-node）：192.168.1.12
  • 备份节点（backup-node）：192.168.1.13

所有节点需处于同一子网（子网掩码255.255.255.0），部署完成后需通过以下命令验证内网连通性：

连通性测试步骤

  • 在各节点执行跨节点ping测试：
# 在biz-node1执行
ping 192.168.1.11 -c 4  # 测试与biz-node2连通性
ping 192.168.1.12 -c 4  # 测试与infra-node连通性
ping 192.168.1.13 -c 4  # 测试与backup-node连通性
# 其他节点执行类似命令，确保所有节点间互通
  • 确保返回结果中丢包率为0%，RTT（往返时间）均值≤200ms

硬件配置

四服务器部署的硬件配置需满足服务分层部署需求，需要 4 台服务器，为业务服务与基础服务提供充足资源。以下为各节点的具体硬件参数：

服务器节点 系统 核心 内存 存储 部署服务详情 开放端口
biz-node1 Linux 8核 16GB 200GB 业务服务全集：tego-os, tego-os-server, tego-llm, tego-mcp, tego-proxy, tego-engine-main×2, tego-engine-worker×2 1. 外部访问：26000,27000,30000,31000
2. 内部通信：29000
biz-node2 Linux 8核 16GB 200GB 业务服务全集：同上 1. 外部访问：26000,27000,30000,31000
2. 内部通信：29000
infra-node
 Linux 8核 16GB 200GB 基础服务主节点：postgres-master, redis, openldap, embedding 1. 内部通信：5432,6379,389,11434
2. 管理端口：5678
3. 同步端口：22（仅对backup-node开放）
backup-node Linux 8核 16GB 200GB 基础服务从节点：postgres-slave, data-sync 1. 内部通信：5432
2. 同步端口：22（用于访问infra-node）

端口配置

根据服务类型及访问范围，端口划分为外部访问端口（面向用户或外部系统）和内部通信端口（节点间及服务间通信），配置如下：

外部访问端口
外部端口需通过防火墙策略严格限制访问来源，结合认证机制保障服务安全：

端口 服务名称 访问说明 安全建议
26000 tego-os 前端Web界面 配置HTTPS + 基于IP的访问控制列表
27000 tego-mcp MCP服务接口 部署API网关 + JWT令牌认证
29000 tego-os-server 后端API服务 仅允许前端服务（26000端口）访问
30000 tego-proxy 工作流负载均衡 仅允许外部负载均衡器（LB）访问
31000 tego-llm LLM网关服务 API网关 + 访问频率限制

内部通信端口
内部端口仅用于服务器节点间及服务组件间通信，需禁止外部网络访问：

端口 服务名称 访问说明
5432 postgres 数据库服务，仅允许业务节点（biz-node1/biz-node2）及backup-node访问
6379 redis 缓存服务，仅允许业务节点（biz-node1/biz-node2）访问
389 openldap 身份认证服务，仅允许业务节点（biz-node1/biz-node2）访问
11434 embedding 向量嵌入服务，仅允许业务节点（biz-node1/biz-node2）访问
22 SSH 远程管理，仅允许backup-node访问infra-node（用于数据同步）

详细部署步骤

通用环境准备

注意

  • 以下的所有操作在 所有4个节点 均需要执行，确保全节点配置一致性
  • 通用环境准备需按系统初始化→Docker安装→镜像加载的顺序执行，以下为各阶段完整操作流程及验证方法：

系统初始化
系统初始化包含基础依赖安装与时间同步配置，为后续部署提供底层环境支撑。

  • 依赖包安装
    首先执行以下命令安装系统基础依赖工具，包括压缩解压、文件同步及网络管理组件：
apt update && apt install -y bzip2 gzip rsync coreutils iptables
  • 时间同步配置
    采用chrony服务实现节点间时间一致性，操作步骤如下：
# 安装chrony服务
apt install -y chrony
# 启动服务并设置开机自启
systemctl enable --now chronyd
# 验证时间同步状态
timedatectl
  • 验证要点：
    • 执行timedatectl后，确保输出中System clock synchronized: yes及NTP service: active字段为正常状态，避免因时间偏差导致服务异常。

Docker安装
采用离线包方式安装Docker及Docker Compose，确保在无公网环境下的部署可行性：

  • 下载离线Docker安装包（版本24.0.9，适配部署需求）
wget https://zhama-public.oss-cn-heyuan.aliyuncs.com/base/offline-docker-24.0.9.tar.gz
  • 解压并执行安装脚本：
tar xf offline-docker-24.0.9.tar.gz
cd offline-docker-24.0.9
bash install.sh
  • 验证Docker安装成功（需显示版本信息）：
docker --version  # 需输出 Docker version 24.0.9+
docker compose version  # 需输出 Docker Compose version v2.20+

镜像加载

  • 下载TeGo全量镜像包（约数GB，需耐心等待）：
wget https://zhama-public.oss-cn-heyuan.aliyuncs.com/tego-all-images-v1.6.0.tar.bz2
  • 解压并加载镜像到Docker：
bzip2 -d tego-all-images-v1.6.0.tar.bz2  # 解压为.tar文件
docker load -i tego-all-images-v1.6.0.tar  # 加载镜像
  • 验证镜像加载成功（需显示包含“tego”的镜像列表）：
docker images | grep tego

加载配置

  • 下载部署配置压缩包：
wget https://zhama-public.oss-cn-heyuan.aliyuncs.com/tego-deploy-v1.6.0.tar
  • 解压并进入部署根目录：
tar xvf tego-deploy-v1.6.0.tar
cd product  # 后续所有部署操作均在此目录下执行

配置核心参数

setup.sh 脚本支持通过命令行参数配置IP地址，无需手动编辑配置文件：

参数 说明 默认值 示例值
-i, --infra-ip 基础设施节点内网IP 192.168.1.12 192.168.1.12
-b1, --biz1-ip 业务节点1外网IP地址 47.120.69.7 47.120.69.7
-b2, --biz2-ip 业务节点2外网IP地址 47.113.226.243 47.113.226.243
-bk, --backup-ip 备份节点内网IP地址 192.168.1.13 192.168.1.13
-h, --help 显示帮助信息 - -

生成的配置变量：

配置项 说明 生成规则
INFRA_HOST_IP_INTERNAL 基础设施节点内网IP 使用 --infra-ip 参数
INFRA_TEGO_EMBEDDING_URL Embedding模型服务URL（使用内网IP） http://内网IP:11434/v1
BIZ1_TEGO_ENGINE_URL 业务节点1引擎服务URL（外网IP/域名） http://业务节点1IP:30000
BIZ1_TEGO_LLM_URL 业务节点1网关服务URL（外网IP/域名） http://业务节点1IP:31000
BIZ1_TRUSTED_URL 业务节点1平台服务URL（外网IP/域名） http://业务节点1IP:26000
BIZ1_ORIGIN_HOST 业务节点1平台域名（外网IP/域名） 业务节点1IP
BIZ2_TEGO_ENGINE_URL 业务节点2引擎服务URL（外网IP/域名） http://业务节点2IP:30000
BIZ2_TEGO_LLM_URL 业务节点2网关服务URL（外网IP/域名） http://业务节点2IP:31000
BIZ2_TRUSTED_URL 业务节点2平台服务URL（外网IP/域名） http://业务节点2IP:26000
BIZ2_ORIGIN_HOST 业务节点2平台域名（外网IP/域名） 业务节点2IP
BACKUP_HOST_IP_INTERNAL 备份节点内网IP 使用 --backup-ip 参数

注意：请根据您的实际网络环境使用相应的IP地址参数

setup.sh 使用示例

查看帮助信息：

./setup.sh --help

常用部署场景：

  1. 单机测试环境（使用默认配置）：

    ./setup.sh

  2. 生产环境四节点部署：

    ./setup.sh -i 192.168.1.12 -b1 47.120.69.7 -b2 47.113.226.243 -bk 192.168.1.13

  3. 开发环境（仅指定基础设施节点IP）：

    ./setup.sh -i 172.16.0.100

脚本执行结果验证：

# 检查生成的配置文件
find . -name ".env" -exec echo "=== {} ===" \; -exec cat {} \;

# 确认IP地址配置正确
grep -r "192.168.1.12\|47.120.69.7\|47.113.226.243\|192.168.1.13" . --include="*.env"

setup.sh 脚本功能说明：

该脚本实现了以下核心功能：

  1. IP地址验证：自动验证输入的IP地址格式是否正确
  2. 配置文件自动生成：查找所有 .env.example 文件，根据参数生成对应的 .env 文件
  3. 参数替换：自动替换配置文件中的占位符为实际的IP地址
  4. 错误处理：提供详细的错误信息和帮助信息
  5. 配置验证：生成配置后提供验证命令，确保配置正确

脚本执行流程：

  1. 解析命令行参数并验证IP地址格式
  2. 查找项目中的所有 .env.example 文件
  3. 复制模板文件为 .env 文件
  4. 使用 sed 命令替换配置文件中的IP地址占位符
  5. 显示配置摘要和后续操作建议

基础设施节点（infra-node）部署

注：以下操作仅在 infra-node（192.168.1.12）上执行

步骤1：生成配置文件

使用 setup.sh 脚本配置并生成环境变量文件。脚本支持命令行参数，无需手动编辑：

# 使用自定义IP地址
./setup.sh -i <基础设施节点内网IP> -b1 <业务节点1外网IP> -b2 <业务节点2外网IP> -bk <备份节点内网IP>

# 示例：
./setup.sh -i 192.168.1.12 -b1 47.120.69.7 -b2 47.113.226.243 -bk 192.168.1.13

查看帮助信息：

./setup.sh --help

脚本执行后将自动：

  1. 验证IP地址格式
  2. 查找所有 env.example 文件
  3. 根据参数生成对应的 .env 文件
  4. 显示配置摘要信息

步骤2：配置核心服务密码

进入基础设施配置目录，编辑.env文件设置服务密码：

cd infrastructure/master
vim .env

设置核心服务密码（替换为实际密码）：

POSTGRES_PASSWORD=your_postgres_password
REDIS_PASSWORD=your_redis_password
LDAP_ADMIN_PASSWORD=your_ldap_password
LDAP_ORGANISATION=Your Organization
LDAP_DOMAIN=your.domain.com

步骤3：启动基础设施服务

启动基础服务（PostgreSQL主库、Redis、OpenLDAP、Embedding）：

docker compose up -d  # 后台启动服务

执行主库初始化脚本（配置PostgreSQL主从复制，需传入backup-node内网IP）：

# 语法：bash master-init.sh <PostgreSQL复制密码> <backup-node内网IP>
bash master-init.sh your_replication_password 192.168.1.13

重启基础服务，确保初始化生效：

docker compose down && docker compose up -d
cd ../..  # 返回product根目录

配置SSH免密（供backup-node访问）

  • 允许backup-node通过SSH访问infra-node进行数据同步：
# 创建.ssh目录（若不存在）
mkdir -p ~/.ssh && chmod 700 ~/.ssh
# 临时开放authorized_keys写入权限
touch ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys

验证基础设施状态

  • 查看容器运行状态（需全部显示Up）：
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
  • 查看关键服务日志（无报错即正常）：
# 查看基础服务日志
docker compose -f infrastructure/master/docker-compose.yml logs

备份节点（backup-node）部署

注：以下操作仅在 backup-node（192.168.1.13）上执行

步骤1：准备配置文件

在backup-node主机上解压部署包并执行 setup.sh 脚本生成配置文件：

# 下载并解压部署包
wget https://zhama-public.oss-cn-heyuan.aliyuncs.com/tego-deploy-v1.6.0.tar
tar xvf tego-deploy-v1.6.0.tar
cd product

# 生成配置文件（使用与基础设施节点相同的IP参数）
./setup.sh -i <基础设施节点内网IP> -b1 <业务节点1外网IP> -b2 <业务节点2外网IP> -bk <备份节点内网IP>

# 示例（使用与基础设施节点相同的配置）：
./setup.sh -i 192.168.1.12 -b1 47.120.69.7 -b2 47.113.226.243 -bk 192.168.1.13

注意：backup-node的配置参数应与基础设施节点保持一致

步骤2：配置Master-Slave SSH免密登录

  • 生成SSH密钥（一路回车，无需设置密码）：
ssh-keygen -t rsa -C tego-backup@your.domain.com
  • 查看公钥内容并复制：
cat ~/.ssh/id_rsa.pub
  • 登录 infra-node 节点，将backup-node的公钥添加到授权列表：
# 在infra-node节点执行
vim ~/.ssh/authorized_keys  # 粘贴backup-node的公钥内容后保存

启动备份服务

  • 进入备份服务目录，准备SSH密钥挂载目录：
cd infrastructure/slave
mkdir -p volumes/data-sync/ssh  # 创建密钥存储目录
cp ~/.ssh/* volumes/data-sync/ssh/  # 复制SSH密钥到数据卷
  • 编辑备份服务配置：
vim .env
  • 配置同步参数（替换为实际值）：
# 远程主机连接配置（指向infra-node）
REMOTE_HOST=192.168.1.12
REMOTE_USER=root
REMOTE_SSH_PORT=22

# 同步配置
SYNC_INTERVAL=3600  # 同步间隔(秒)
BACKUP_RETENTION_DAYS=7  # 备份保留天数
POSTGRES_PASSWORD=your_postgres_password  # 与infra-node保持一致
  • 启动备份服务（PostgreSQL从库、data-sync同步服务）：
docker compose up -d
cd ../..  # 返回product根目录

验证备份节点状态

  • 查看容器运行状态（需全部显示Up）：
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
  • 查看同步服务日志（重点确认数据同步正常）：
docker compose -f infrastructure/slave/docker-compose.yml logs

业务节点1（biz-node1）部署

注：以下操作仅在 biz-node1（192.168.1.10）上执行

步骤1：准备配置文件

在biz-node1主机上解压部署包并执行 setup.sh 脚本生成配置文件：

# 下载并解压部署包
wget https://zhama-public.oss-cn-heyuan.aliyuncs.com/tego-deploy-v1.6.0.tar
tar xvf tego-deploy-v1.6.0.tar
cd product

# 生成配置文件（使用与基础设施节点相同的IP参数）
./setup.sh -i <基础设施节点内网IP> -b1 <业务节点1外网IP> -b2 <业务节点2外网IP> -bk <备份节点内网IP>

# 示例（使用与基础设施节点相同的配置）：
./setup.sh -i 192.168.1.12 -b1 47.120.69.7 -b2 47.113.226.243 -bk 192.168.1.13

步骤2：配置业务服务连接参数

进入业务服务目录，编辑环境变量配置：

cd host1
vim .env

配置基础设施连接信息（替换为实际值）：

# 基础设施连接配置（指向infra-node）
POSTGRES_HOST=192.168.1.12
POSTGRES_PORT=5432
POSTGRES_PASSWORD=your_postgres_password  # 与infra-node一致
REDIS_HOST=192.168.1.12
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password  # 与infra-node一致

# 业务服务配置
TEGO_JWT_SECRET=your_jwt_secret
DATABASE_URL=postgresql://zhama:your_postgres_password@192.168.1.12:5432/zhama
SQL_DSN=host=192.168.1.12 port=5432 user=zhama password=your_postgres_password dbname=tego-llm sslmode=disable

# AI服务配置
USE_LOCAL_MODEL=false
MODEL_NAME=qwen3-embedding-4b
EMBEDDING_URL=http://192.168.1.12:11434/v1

步骤3：启动业务服务

启动Host1业务集群（包含前端、后端、AI网关等核心服务）：

docker compose up -d
cd ..  # 返回product根目录

验证业务节点1状态

  • 查看容器运行状态（需全部显示Up）：
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
  • 查看业务服务日志（无报错即正常）：
docker compose -f host1/docker-compose.yml logs

业务节点2（biz-node2）部署

注：以下操作仅在 biz-node2（192.168.1.11）上执行

步骤1：准备配置文件

在biz-node2主机上解压部署包并执行 setup.sh 脚本生成配置文件：

# 下载并解压部署包
wget https://zhama-public.oss-cn-heyuan.aliyuncs.com/tego-deploy-v1.6.0.tar
tar xvf tego-deploy-v1.6.0.tar
cd product

# 生成配置文件（使用与基础设施节点相同的IP参数）
./setup.sh -i <基础设施节点内网IP> -b1 <业务节点1外网IP> -b2 <业务节点2外网IP> -bk <备份节点内网IP>

# 示例（使用与基础设施节点相同的配置）：
./setup.sh -i 192.168.1.12 -b1 47.120.69.7 -b2 47.113.226.243 -bk 192.168.1.13

步骤2：配置业务服务连接参数

进入业务服务目录，编辑环境变量配置（与biz-node1配置一致）：

cd host2
vim .env

配置内容同biz-node1的.env文件（确保与基础设施连接参数一致）

步骤3：启动业务服务

启动Host2业务集群（与biz-node1服务一致，实现负载均衡）：

docker compose up -d
cd ..  # 返回product根目录

验证业务节点2状态

  • 查看容器运行状态（需全部显示Up）：
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
  • 查看业务服务日志（无报错即正常）：
docker compose -f host2/docker-compose.yml logs

全局部署验证

端口访问验证
在客户端或服务器本地，通过curl或浏览器验证端口可用性（替换为实际IP）：

# 验证业务节点1服务
curl http://<biz-node1外网IP>:26000  # 前端服务，应返回HTML内容
curl http://<biz-node1外网IP>:30000/health  # 引擎服务健康检查，应返回"ok"

# 验证业务节点2服务
curl http://<biz-node2外网IP>:26000
curl http://<biz-node2外网IP>:30000/health

# 验证基础设施服务（内部访问）
curl http://192.168.1.12:11434/v1  # Embedding服务，应返回API文档

主从数据同步验证
验证PostgreSQL主从复制是否正常（在infra-node节点执行）：

# 进入PostgreSQL主库容器
docker exec -it infrastructure-master-postgres-1 bash
# 连接数据库，查看从库状态（需显示backup-node节点信息）
psql -U postgres
SELECT client_addr, state FROM pg_stat_replication;
# 若显示state为"streaming"，说明主从同步正常

负载均衡验证
配置外部负载均衡器指向biz-node1和biz-node2的30000端口后，执行：

# 多次执行，验证请求是否分发到不同节点
curl http://<负载均衡器IP>:30000/hostname
# 应交替返回biz-node1和biz-node2的主机标识

故障排除

常见问题

  1. 端口冲突：使用netstat -tulpn检查端口占用情况，确保部署的端口未被其他服务占用
  2. 权限问题：执行usermod -aG docker $USER将当前用户加入docker用户组，避免权限不足
  3. 网络连通性：通过traceroute排查节点间网络不通问题，确保内网防火墙规则允许相关端口通信
  4. 数据同步失败：检查backup-node与infra-node的SSH免密配置，验证同步服务日志docker logs data-sync-1
  5. 业务服务启动失败：确认.env文件中基础设施连接参数正确，特别是数据库密码与IP地址是否匹配
  6. 时间同步异常：执行chronyc sources检查时间服务器连接状态，确保所有节点时间偏差≤1秒
✕ 原图
← 上一张
→ 下一张
↑ 放大
↓ 缩小
🖱️ 拖拽移动
ESC 关闭