TeGo-AI 体验版部署文档
服务分布
双服务器部署架构中，需要 2 台服务器，服务分布需结合业务连续性需求与资源效率进行分层设计。通过构建服务分布矩阵表，可清晰呈现各服务在 Master/Slave 节点的部署策略、核心作用及冗余机制，为系统运维与故障排查提供可视化参考。
服务部署矩阵
| 服务层级 | 服务名称 | 部署节点 | 核心作用 |
|---|---|---|---|
| 负载均衡层 | tego-proxy | 双节点冗余 | 统一负载均衡，分发请求到业务节点 |
| 业务服务层 | tego-os | 双节点冗余 | 前端统一操作界面 |
| tego-os-server | 双节点冗余 | 后端API服务 | |
| tego-mcp | 双节点冗余 | MCP 服务，实现向量搜索等功能 | |
| tego-llm | 双节点冗余 | LLM网关服务 | |
| tego-engine-main | 双节点冗余 | 工作流主控节点 | |
| tego-engine-worker | 双节点冗余 | 工作流执行节点 | |
| 基础设施层 | postgres-master | 单点部署（Master 节点），Slave 节点通过 data-sync 备份 | 主数据库，存储业务核心数据 |
| postgres-slave | 从节点部署（Slave 节点，主从复制） | 从数据库，同步主库数据并提供只读查询 | |
| redis | 单点部署（Master 节点），Slave 节点通过 data-sync 备份 | 缓存/消息队列服务，提升数据访问性能 | |
| openldap | 单点部署（Master 节点），Slave 节点通过 data-sync 备份 | 统一认证服务，管理用户身份与权限 | |
| embedding | 单点部署（Master 节点），Slave 节点通过 data-sync 备份 | AI 嵌入服务，生成与存储向量数据 | |
| data-sync | 从节点部署（Slave 节点，数据同步专用） | 跨节点数据同步服务，支撑主从数据一致性 |
服务分布核心原则
- 业务服务双节点冗余：负载均衡层与业务服务层所有服务（如 tego-os、tego-llm 等）均在 Master 和 Slave 节点同时部署，通过双活机制实现故障自动切换，保障业务连续性。
- 核心基础服务主从分离：基础设施层关键服务（如 postgres、redis）采用"主节点部署+从节点备份"模式，主节点承担生产读写任务，从节点通过 data-sync 服务实时同步数据，既降低单点故障风险，又避免资源浪费。
环境配置
硬件配置
双服务器部署的硬件配置需满足核心服务运行需求，并预留资源冗余以保障系统稳定性。以下为 Master 节点与 Slave 节点的具体硬件参数及配置说明（假设 IP 已标注）：
服务器硬件参数表
| 服务器节点 | 系统 | 核心 | 内存 | 存储 | 部署服务详情 | 开放端口 |
|---|---|---|---|---|---|---|
| master | Linux | 4核 | 4GB | 50GB | 业务服务：tego-os, tego-os-server, tego-llm, tego-mcp, tego-proxy, tego-engine-main×1, tego-engine-worker×1 基础服务：postgres-master, redis, openldap, embedding |
1. 外部访问：26000,27000,30000,31000 2. 内部通信：22,5432,6379,389,11434,29000 3. 管理端口：5678 |
| slave | Linux | 4核 | 4GB | 50GB | 业务服务：tego-os, tego-os-server, tego-llm, tego-mcp, tego-proxy, tego-engine-main×1, tego-engine-worker×1 基础服务：postgres-slave, data-sync |
1. 外部访问：26000,27000,30000,31000 2. 内部通信：22,5432,29000 3. 管理端口：5678 4. data-sync：无独立端口（依赖 SSH 22） |
网络配置
双服务器部署环境需配置独立内网通信链路，确保节点间数据传输的稳定性与安全性。本次部署假设两台服务器内网 IP 如下：
- 主节点（Master）：
- 内网 IP：192.168.1.10
- 外网 IP：47.120.69.7
- 从节点（Slave）：
- 内网IP：192.168.1.11
- 外网IP：47.113.226.243
两节点需处于同一子网（子网掩码255.255.255.0），部署完成后需通过以下命令验证内网连通性：
连通性测试步骤
- 在Master节点执行：
ping 192.168.1.11 -c 4 - 在Slave节点执行：
ping 192.168.1.10 -c 4 - 确保返回结果中丢包率为0%，RTT（往返时间）均值≤200ms
端口配置
根据服务类型及访问范围，端口划分为外部访问端口（面向用户或外部系统）和内部通信端口（节点间及服务间通信），配置如下：
外部访问端口
外部端口需通过防火墙策略严格限制访问来源，结合认证机制保障服务安全：
| 端口 | 服务名称 | 访问说明 | 安全建议 |
|---|---|---|---|
| 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 | 数据库服务，仅允许业务服务访问 |
| 6379 | redis | 缓存服务，仅允许业务服务访问 |
| 389 | openldap | 身份认证服务，仅允许业务服务访问 |
| 11434 | embedding | 向量嵌入服务，仅允许业务服务访问 |
| 22 | SSH | 远程管理，仅允许Slave节点（192.168.1.11）访问Master节点（192.168.1.10） |
详细部署步骤
通用环境准备
注意：以下操作在Master（192.168.1.10）和Slave（192.168.1.11）节点均需执行，确保双服务器配置一致性，需按系统初始化→Docker安装→镜像加载顺序执行。
系统初始化
系统初始化包含基础依赖安装与时间同步配置，为后续部署提供底层环境支撑。
- 依赖包安装
执行以下命令安装系统基础依赖工具，包括压缩解压、文件同步及网络管理组件：
apt update && apt install -y bzip2 gzip rsync coreutils iptables
- 时间同步配置
采用chrony服务实现节点间时间一致性，操作步骤如下：
# 安装chrony服务
apt install -y chrony
# 启动服务并设置开机自启
systemctl enable --now chronyd
# 验证时间同步状态（需显示System clock synchronized: yes）
timedatectl
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.bash
- 验证Docker安装成功（需显示版本信息）：
# 需输出 Docker version 24.0.9+
docker --version
# 需输出 Docker Compose version v2.20+
docker compose version
镜像加载
- 下载TeGo全量镜像包
# 下载镜像包，大小约数GB，需耐心等待
wget https://zhama-public.oss-cn-heyuan.aliyuncs.com/tego-all-images-v1.6.0.tar.bz2
- 解压并加载镜像到Docker
# 解压为.tar文件（约数GB，解压过程需耐心等待）：
bzip2 -d tego-all-images-v1.6.0.tar.bz2
# 加载镜像
docker load -i tego-all-images-v1.6.0.tar
- 验证镜像加载成功（需显示包含"tego"的镜像列表）：
docker images | grep tego
# 输出以下信息代表镜像加载成功
ghcr.io/zhama-ai/tego-os v1.6.0 d0df873dc367 7 days ago 332MB
ghcr.io/zhama-ai/tego-llm v1.6.0 47ab885a9415 8 days ago 201MB
ghcr.io/zhama-ai/tego-os-server v1.6.0 0cb56e5d462a 9 days ago 208MB
ghcr.io/zhama-ai/tego-engine v1.6.0 9c1c0a146254 9 days ago 991MB
ghcr.io/zhama-ai/tego-mcp v1.6.0 b80b6ea963b9 10 days ago 2.04GB
加载配置与核心参数设置
- 下载部署配置压缩包：
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地址，无需手动编辑配置文件：
| 参数 | 说明 | 默认值 | 示例值 |
|---|---|---|---|
-m, --master-ip |
Master节点内网IP | 192.168.1.10 | 192.168.1.10 |
-s, --slave-ip |
Slave节点内网IP | 192.168.1.11 | 192.168.1.11 |
-me, --master-external |
Master节点外网IP | 47.120.69.7 | 47.120.69.7 |
-se, --slave-external |
Slave节点外网IP | 47.113.226.243 | 47.113.226.243 |
-h, --help |
显示帮助信息 | - | - |
生成的配置变量：
| 配置项 | 说明 | 生成规则 |
|---|---|---|
| MASTER_HOST_IP_INTERNAL | Master节点内网IP | 使用 --master-ip 参数 |
| MASTER_TEGO_EMBEDDING_URL | Embedding模型服务URL（使用内网IP） | http://内网IP:11434/v1 |
| MASTER_TEGO_ENGINE_URL | Master引擎服务URL（外网IP/域名） | http://Master外网IP:30000 |
| MASTER_TEGO_LLM_URL | Master网关服务URL（外网IP/域名） | http://Master外网IP:31000 |
| MASTER_TRUSTED_URL | Master平台服务URL（外网IP/域名） | http://Master外网IP:26000 |
| MASTER_ORIGIN_HOST | Master平台域名（外网IP/域名） | Master外网IP |
| SLAVE_TEGO_ENGINE_URL | Slave引擎服务URL（外网IP/域名） | http://Slave外网IP:30000 |
| SLAVE_TEGO_LLM_URL | Slave网关服务URL（外网IP/域名） | http://Slave外网IP:31000 |
| SLAVE_TRUSTED_URL | Slave平台服务URL（外网IP/域名） | http://Slave外网IP:26000 |
| SLAVE_ORIGIN_HOST | Slave平台域名（外网IP/域名） | Slave外网IP |
注意：请根据您的实际网络环境使用相应的IP地址参数
Master 节点部署
注：以下操作仅在Master节点（192.168.1.10）执行
步骤1：生成配置文件
使用 setup.sh 脚本配置并生成环境变量文件。脚本支持命令行参数，无需手动编辑：
# 使用自定义IP地址
./setup.sh -m <Master节点内网IP> -s <Slave节点内网IP> -me <Master节点外网IP> -se <Slave节点外网IP>
# 示例：
./setup.sh -m 192.168.1.10 -s 192.168.1.11 -me 47.120.69.7 -se 47.113.226.243
脚本将自动生成配置文件。
步骤2：启动基础设施服务
启动LLM基础设施（Embedding服务）：
cd infrastructure/llm
docker compose up -d # 后台启动服务
启动Master基础服务（PostgreSQL主库、Redis、OpenLDAP）：
cd ../master # 进入Master基础服务目录
docker compose up -d
执行主库初始化脚本（配置PostgreSQL主从复制，传入Slave内网IP192.168.1.11）：
# 语法：bash master-init.sh <PostgreSQL复制密码> <Slave内网IP>
bash master-init.sh your_replication_password 192.168.1.11
重启Master基础服务，确保初始化生效：
docker compose down && docker compose up -d
cd ../.. # 返回product根目录
启动Master业务服务
启动Host1业务集群（包含前端、后端、AI网关等核心服务）：
cd host1
docker compose up -d
cd .. # 返回product根目录
验证Master节点状态
- 查看所有容器运行状态（需全部显示
Up）：
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
- 查看关键服务日志（无报错即正常）：
# 查看LLM服务日志
docker compose -f infrastructure/llm/docker-compose.yml logs
# 查看Master基础服务日志
docker compose -f infrastructure/master/docker-compose.yml logs
# 查看Host1业务服务日志
docker compose -f host1/docker-compose.yml logs
Slave 节点部署
注：以下操作仅在Slave节点（192.168.1.11）执行
步骤1：准备配置文件
在Slave主机上解压部署包并执行 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
# 生成配置文件（使用与Master节点相同的IP参数）
./setup.sh -m <Master节点内网IP> -s <Slave节点内网IP> -me <Master节点外网IP> -se <Slave节点外网IP>
# 示例（使用与Master节点相同的配置）：
./setup.sh -m 192.168.1.10 -s 192.168.1.11 -me 47.120.69.7 -se 47.113.226.243
注意：Slave节点的配置参数应与Master节点保持一致
步骤2：配置Master-Slave SSH免密登录
Slave需通过SSH同步Master的OpenLDAP数据，需配置免密登录：
在Slave节点生成SSH密钥（一直按回车键往下执行，无需设置密码）：
ssh-keygen -t rsa -C zhama@zhama.com
查看Slave的公钥内容并复制：
cat ~/.ssh/id_rsa.pub
登录Master节点（192.168.1.10），将Slave的公钥添加到授权列表：
# 在Master节点执行，粘贴Slave的公钥内容后保存
vim ~/.ssh/authorized_keys
[!IMPORTANT]
- 1、生成完sshkey后，把
/.ssh/id_rsa.pub内容，拷贝在 Master节点的/.ssh/authorized_keys文件里面。这样才能对openldap存储进行备份- 2、把.ssh目录的内容拷贝到当前目录下面的ssh目录，如： ./volumes/data-sync/ssh
启动Slave基础设施服务
- 进入Slave基础服务目录，准备SSH密钥挂载目录：
cd infrastructure/slave
# 创建密钥存储目录
mkdir -p volumes/data-sync/ssh
# 复制Slave的SSH密钥到数据卷
cp ~/.ssh/* volumes/data-sync/ssh/
- 启动Slave基础服务（PostgreSQL从库、data-sync同步服务）：
docker compose up -d
# 返回product根目录
cd ../..
启动Slave业务服务
启动Host2业务集群（与Master的Host1服务一致，实现负载均衡）：
cd host2
# 返回product根目录
docker compose up -d
cd ..
验证Slave节点状态
- 查看Slave容器运行状态（需全部显示
Up）：
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
- 查看Slave关键服务日志（无报错即正常）：
# 查看Slave基础服务日志（重点看data-sync是否正常同步）
docker compose -f infrastructure/slave/docker-compose.yml logs
# 查看Host2业务服务日志
docker compose -f host2/docker-compose.yml logs
全局部署验证
端口访问验证
在客户端或服务器本地，通过curl或浏览器验证端口可用性（使用假设的外网IP）：
# 验证Master节点服务，前端服务，应返回HTML内容
curl http://47.120.69.7:26000
# 引擎服务健康检查，应返回"ok"
curl http://47.120.69.7:30000/health
# Embedding服务，应返回API文档
curl http://47.120.69.7:11434/v1
# 验证Slave节点服务
curl http://47.113.226.243:26000
curl http://47.113.226.243:30000/health
主从数据同步验证
验证PostgreSQL主从复制是否正常（在Master节点执行）：
# 进入PostgreSQL主库容器
docker exec -it infrastructure-master-postgres-1 bash
# 连接数据库，查看从库状态（需显示Slave节点内网IP192.168.1.11）
psql -U postgres
SELECT client_addr, state FROM pg_stat_replication;
# 若显示state为"streaming"，说明主从同步正常
访问系统
恭喜你！你已经完成了整个系统的部署，接下来可以通过以下链接访问完整的系统，进行相关的产品体验：
- Master节点前端：
http://47.120.69.7:26000 - Slave节点前端：
http://47.113.226.243:26000