
 ## 背景与目标

### 2.1 业务背景

智能体系统（xxx AI Agent）采用 Docker 容器化部署，后端为 FastAPI + Celery，前端为 Next.js standalone 服务。生产环境部署需要把构建产物（镜像包 backend.tar / frontend.tar）以及一个 deploy/ 编排目录，从构建环境安全、可控地送达生产部署机器。
### 2.2 现状痛点

当前生产环境文件上传方式是：
1. 本地打包镜像文件；

1. 通过**通讯工具（IM/网盘等）**把文件发给生产环境部署人员；

1. 部署人员**手动**把文件上传到生产环境机器；

1. 文件就位后再开始准备部署。

存在问题：
- 文件上传至生产环境经过**中间服务过多**（通讯工具链路不属于内网可信通道）；

- **网络带宽受限**，大体积镜像包（数百 MB ~ GB 级）传输极慢；

- 无法满足**快速部署 / 快速回滚**的运维要求；

- 传输过程**缺乏审计与权限管控**，存在合规与安全风险。

### 2.3 设计目标


| | |
|:-:|:-:|
|目标|说明|
|传输提速|利用数据中心内网（数据中心）SCP 传输，避免公网/通讯工具瓶颈|
|链路收敛|将"本地 → 通讯工具 → 部署人员 → 生产机"收敛为"构建机 → 跳板机 → 生产机"|
|权限可控|所有跨机访问通过 IP 设备全生命周期平台申请网络策略，最小权限开放 22 端口|
|可追溯|跳板机集中存放待部署产物，传输动作可审计、可重放|
|可落地|与现有 save_images.sh 构建链路、start.sh/docker-compose.yml 启动链路天然衔接|
### 2.4 非目标（Out of Scope）

- 不实现 CI/CD 全自动发布流水线（保留人工在跳板机触发生产上传/部署的管控点）；

- 不引入对象存储/制品库（如 Harbor/Nexus）作为中转，保持当前轻量方案；

- 不涉及数据库迁移、回滚策略以外的应用层变更（由 deploy 流程另行规范）。

  ---- 
1. ## 术语与缩略语


| | | |
|:-:|:-:|:-:|
|术语|全称|说明|
|SCP|Secure Copy Protocol|基于 SSH 的安全文件拷贝协议，依赖 22 端口|
|跳板机|Bastion / Jump Host|具备内网双向访问能力的开发环境机器，作为文件上传中转节点|
|构建机|Build Node|运行 Jenkins 打包镜像的服务器|
|生产部署机|Prod Node|最终承载 mail-* 容器服务的生产服务器|
|数据中心|Data Center|南数（南方数据中心），三台机器同属该 DC 内网|
|网络策略|Network Policy|通过 IP 设备全生命周期平台申请的跨机 22 端口访问授权|
  ---- 
1. ## 总体架构

### 4.1 架构原则

- **内网优先**：所有大文件传输均在数据中心内网完成，不走公网。

- **跳板收敛**：以开发环境机器作为唯一中转，降低生产机的直接暴露面。

- **最小权限**：仅开放 SSH(22) 端口，且按"源 IP → 目的 IP → 端口"精确授权。

- **解耦构建与部署**：构建产物（tar）与编排目录（deploy/）分离，部署动作不依赖构建机在线。

### 4.2 拓扑结构

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           部署流程网络拓扑                                    │
└─────────────────────────────────────────────────────────────────────────────┘

┌──────────────────┐         ┌──────────────────┐         ┌──────────────────┐
│    构建机         │   SCP   │    跳板机         │   SCP   │   生产机          │
│  (Jenkins)       │  (22)   │   (开发环境)      │  (22)   │   (生产环境)      │
│                  │ ──────▶ │                  │ ──────▶ │                  │
│  IP: 127.0.0.94  │         │  IP: 127.0.0.12  │         │  IP: 10.x.x.x    │
│                  │         │                  │         │                  │
│  /app/custom-ai/ │         │  /app/custom-ai/ │         │  /app/custom-ai/ │
│                  │         │  prod-deploy/    │         │  xxx-ai-agent/   │
│                  │         │  xxx-ai-agent/   │         │  deploy/         │
└──────────────────┘         └──────────────────┘         └──────────────────┘
│                            │                            │
▼                            ▼                            ▼
┌──────────────────┐         ┌──────────────────┐         ┌──────────────────┐
│  步骤一：构建镜像  │         │  步骤二：上传跳板机│         │  步骤三：上传生产机│
│                  │         │                  │         │                  │
│  ✅ 已完成        │         │  ✅ 已完成        │         │  ⏳ 待执行        │
│                  │         │                  │         │                  │
│  - backend.tar   │         │  tar 落盘         │         │  tar 落盘         │
│  - frontend.tar  │         │  部署人员手动触发  │         │  docker load     │
│                  │         │                  │         │  docker compose up│
└──────────────────┘         └──────────────────┘         └──────────────────┘
```
>三台机器均属于**同一数据中心（数据中心）**，SCP 在**内网环境**中进行，传输速率满足部署时效要求。

### 4.3 节点角色与目录约定


| | | | | |
|:-:|:-:|:-:|:-:|:-:|
|节点|IP|角色|关键目录|操作主体|
|构建机|127.0.0.94|Jenkins 打包镜像，导出 tar|Jenkins workspace|CI 自动|
|跳板机|127.0.0.12|中转存储待部署产物|/app/custome-ai/prod-deploy/xxx-ai-agent|部署人员|
|生产部署机|10.x.x.x|加载镜像并启动服务|/app/custome-ai/xxx-ai-agent/deploy|部署人员|
  ---- 
1. ## 详细设计与实现流程

### 5.1 步骤一：构建部署镜像（已完成）

由 Jenkins 在 **127.0.0.94** 上执行镜像构建，产物为两个 tar 包：
- backend.tar （xxx-backend:latest，FastAPI + Celery Worker）

- frontend.tar （xxx-frontend:latest，Next.js standalone）

>与项目实际链路对齐：等价于在 deploy/ 目录执行 ./save_images.sh production，该脚本会 docker compose build 后 docker save -o backend.tar / frontend.tar。构建机侧已具备此能力，本方案默认该步骤已完成，仅关注**产物的上传与分发**。

### 5.2 步骤二：构建机 → 跳板机

#### 5.2.1 申请 SCP 网络权限

在 **IP 设备全生命周期平台**申请网络访问策略：

| | | | |
|:-:|:-:|:-:|:-:|
|源|目的|协议/端口|用途|
|127.0.0.94（构建机）|127.0.0.12（跳板机）|TCP/22|SCP 文件传输|
#### 5.2.2 验证网络权限

在 **127.0.0.94** 上执行：
```
# 验证 22 端口网络策略是否已开通telnet 127.0.0.12 22
```
预期：telnet 能建立到 22 端口的 TCP 连接（出现 SSH 横幅或 Connected to ...）。
#### 5.2.3 SCP 上传至跳板机

网络策略开通后，在 **127.0.0.94** 上执行：
```
SCP ./backend.tar  root@127.0.0.12:/app/custome-ai/prod-deploy/xxx-ai-agent
SCP ./frontend.tar root@127.0.0.12:/app/custome-ai/prod-deploy/xxx-ai-agent
```
>建议：生产环境应使用**专用部署账号**而非 root，并通过 SSH 公钥免密 + 限定源 IP 增强安全性（见第 8 章安全设计）。

### 5.3 步骤三：跳板机 → 生产部署机器

#### 5.3.1 申请 SCP 网络权限

在 **IP 设备全生命周期平台**申请网络访问策略：

| | | | |
|:-:|:-:|:-:|:-:|
|源|目的|协议/端口|用途|
|127.0.0.12（跳板机）|10.x.x.x（生产部署机）|TCP/22|SCP 文件传输|
#### 5.3.2 验证网络权限

在 **127.0.0.12（跳板机）** 上执行：
```
# 验证到生产机的 22 端口网络策略是否已开通telnet 10.x.x.x 22
```
#### 5.3.3 SCP 上传至生产机并启动

网络策略开通后，在 **127.0.0.12（跳板机）** 上执行：
```
# 进入待部署已打包的文件目录cd /app/custome-ai/prod-deploy/xxx-ai-agent
# 上传镜像包到生产部署机器SCP ./backend.tar  root@10.x.x.x:/app/custome-ai/xxx-ai-agent/deploy
SCP ./frontend.tar root@10.x.x.x:/app/custome-ai/xxx-ai-agent/deploy
```
随后在生产部署机 **10.x.x.x** 上执行启动（与现有 deploy/ 流程衔接）：
```
cd /app/custome-ai/xxx-ai-agent/deploy
chmod +x *.sh./start.sh production
```
start.sh 会依次执行 docker load -i backend.tar → docker load -i frontend.tar → docker compose up -d，拉起 xxx-backend / xxx-worker-* / xxx-frontend。
### 5.4 步骤四：部署验证（建议补充）

在生产部署机上验证服务健康：
```
# 容器状态docker ps --filter "name=xxx-"
# 后端健康检查curl -f http://localhost:8000/health
# 前端可访问curl -I http://localhost:3001
```
  ---- 
1. ## 目录与产物规范

### 6.1 跳板机目录结构

```
/app/custome-ai/prod-deploy/xxx-ai-agent/
├── backend.tar # 后端镜像包（构建机 SCP 上传）
├── frontend.tar         # 前端镜像包（构建机 SCP 上传）
└── (可选) deploy/        # 如需在跳板机暂存编排目录，可一并归档
```
### 6.2 生产机目录结构

```
/app/custome-ai/xxx-ai-agent/deploy/
├── docker-compose.yml   # 编排文件（所有环境共享）
├── backend.tar          # 后端镜像包（跳板机 SCP 上传）
├── frontend.tar         # 前端镜像包（跳板机 SCP 上传）
├── start.sh             # 启动脚本（加载镜像 + compose up）
├── stop.sh # 停止脚本
└── data/uploads/        # 用户上传文件持久化（bind mount）
```
>配置（.env.production）在构建时已内嵌镜像，生产机**无需**配置文件，仅需镜像包 + 编排目录。

  ---- 
1. ## 关键设计决策（ADR）

### ADR-1：采用"构建机 → 跳板机 → 生产机"三段式而非直传

- **背景**：原方案经通讯工具多跳传输，速度慢且不可控。

- **决策**：引入开发环境机器作为跳板机，所有大文件在数据中心内网 SCP 传输。

- **后果（正向）**：传输链路收敛、速率满足要求、跳板机可审计。

- **后果（负向/风险）**：跳板机成为单点中转，需对其做磁盘容量与权限管控（第 8 章）。

### ADR-2：保留人工在跳板机触发生产上传

- **背景**：生产环境要求部署动作有显式人为确认。

- **决策**：步骤三（跳板机 → 生产机）由部署人员手动执行 SCP + start.sh，不自动化。

- **后果**：牺牲部分自动化效率，换取生产操作的可控性与合规性。

### ADR-3：沿用现有 save_images.sh / start.sh 链路

- **背景**：项目已有成熟的镜像构建与启动脚本。

- **决策**：本方案只解决"产物如何到达生产机"，不改动构建/启动逻辑，保持解耦。

- **后果**：方案与代码库现状零冲突，落地风险低。

  ---- 
1. ## 安全设计


| | |
|:-:|:-:|
|风险点|控制措施|
|明文传输|SCP 基于 SSH 加密通道，内网传输亦不降级为明文 rcp/ftp|
|账号滥用|生产/跳板机建议创建专用部署账号，禁用 root 直登；SSH 仅允许公钥认证|
|端口暴露|仅开放 TCP/22，且通过全生命周期平台按"源 IP + 目的 IP + 端口"精确授权，不开放全端口|
|跳板机单点|跳板机目录限制写入权限，定期清理已上线版本的 tar 包，避免磁盘占满|
|权限过期|网络策略申请应设置有效期，临时开通的调试策略及时回收|
|产物完整性|建议在构建机对 tar 包生成 sha256sum 校验值，跳板机/生产机加载前校验，防止传输损坏|
**建议补充的校验步骤（可选落地增强）**：
```
# 构建机：生成校验和sha256
sum backend.tar frontend.tar > checksums.txt
SCP checksums.txt root@127.0.0.12:/app/custome-ai/prod-deploy/xxx-ai-agent
# 跳板机 / 生产机：校验sha256sum -c checksums.txt
```
  ---- 
1. ## 网络与权限申请清单


| | | | | | |
|:-:|:-:|:-:|:-:|:-:|:-:|
|序号|申请项|源 IP|目的 IP|端口|申请平台|
|1|构建机→跳板机 SCP|127.0.0.94|127.0.0.12|TCP/22|IP 设备全生命周期平台|
|2|跳板机→生产机 SCP|127.0.0.12|10.x.x.x|TCP/22|IP 设备全生命周期平台|
>两项策略均需在**实际执行 SCP 前**完成审批与开通，并通过 telnet <ip> 22 验证。

  ---- 
1. ## 部署操作流程（SOP，速查版）

### 阶段 A：构建机（127.0.0.94）

```
# 1. 构建并导出镜像（已完成则跳过）cd deploy && ./save_images.sh production
# 2. 申请"构建机→跳板机"22 端口策略（平台操作）
# 3. 验证 + 上传telnet 127.0.0.12 22
SCP ./backend.tar  root@127.0.0.12:/app/custome-ai/prod-deploy/xxx-ai-agent
SCP ./frontend.tar root@127.0.0.12:/app/custome-ai/prod-deploy/xxx-ai-agent
```
### 阶段 B：跳板机（127.0.0.12）

```
# 1. 确认产物到位ls -lh /app/custome-ai/prod-deploy/xxx-ai-agent/*.tar
# 2. 申请"跳板机→生产机"22 端口策略（平台操作）
# 3. 验证 + 上传telnet 10.x.x.x 22cd /app/custome-ai/prod-deploy/xxx-ai-agent
SCP ./backend.tar  root@10.x.x.x:/app/custome-ai/xxx-ai-agent/deploy
SCP ./frontend.tar root@10.x.x.x:/app/custome-ai/xxx-ai-agent/deploy
```
### 阶段 C：生产机（10.x.x.x）

```
cd /app/custome-ai/xxx-ai-agent/deploy
chmod +x *.sh./start.sh production
# 验证
docker ps --filter "name=xxx-"
curl -f http://localhost:8000/health
```
  ---- 
1. ## 异常处理与回滚


| | | |
|:-:|:-:|:-:|
|异常场景|现象|处置|
|网络策略未开通|telnet 超时 / No route to host|确认平台审批状态，未生效则等待或联系网络运维|
|SCP 中断|传输中途断开、tar 不完整|重新执行 SCP；生产机加载前用 sha256sum -c 校验|
|镜像加载失败|docker load 报错|确认 tar 未损坏，重新从跳板机拉取|
|启动后健康检查失败|/health 返回非 200|查看 docker logs xxx-backend，回退上一版本 tar 重新 start.sh|
|跳板机磁盘占满|SCP 写入失败|清理历史已上线 tar 包，保留最近 2 个版本即可|
**回滚原则**：保留上一稳定版本的 backend.tar / frontend.tar，应急时直接对旧 tar 执行 start.sh 即可回退，无需重新构建。
  ---- 
1. ## 验收标准

- [ ] 构建机 → 跳板机 22 端口策略已开通并通过 telnet 验证

- [ ] backend.tar / frontend.tar 成功落盘跳板机指定目录

- [ ] 跳板机 → 生产机 22 端口策略已开通并通过 telnet 验证

- [ ] 两个 tar 包成功上传至生产机 deploy/ 目录

- [ ] ./start.sh production 成功拉起 xxx-backend / xxx-worker-* / xxx-frontend

- [ ] 后端 /health 返回 200，前端页面可访问

- [ ] （增强项）sha256sum -c 校验通过

  ---- 
1. ## 附录

### 13.1 与项目 deploy/ 现有流程的映射


| | |
|:-:|:-:|
|本方案步骤|对应项目文件/脚本|
|步骤一 构建镜像|deploy/save_images.sh|
|步骤二/三 上传|SCP（手动/脚本化）|
|步骤四 启动|deploy/start.sh + deploy/docker-compose.yml|
|停止/更新|deploy/stop.sh|
### 13.2 后续演进方向（可选）

- 跳板机侧增加 rsync 增量同步，避免每次全量 SCP；

- 引入制品库（Harbor）替代 tar 直传，支持版本管理与镜像签名；

- 将步骤三封装为受权限管控的发布脚本，降低人为操作失误。

智能体系统（xxx AI Agent）采用 Docker 容器化部署，后端为 FastAPI + Celery，前端为 Next.js standalone 服务。生产环境部署需要把构建产物（镜像包 backend.tar  frontend.tar）以及一个 deploy 编排目录，从构建环境安全、可控地送达生产部署机器。

智能体服务 — 生产环境部署文件上传方案设计

智能体服务 — 生产环境部署文件上传方案设计全、可控地送达生产部署机器。

运维

后端

架构设计

采用数据中心内网SCP三段式传输方案，将构建机镜像包经跳板机安全送达生产机，替代通讯工具中转。通过IP平台精确申请22端口策略，实现最小权限管控与全程审计。保留人工触发部署确认点，衔接现有save_images.sh与start.sh链路，支持快速回滚，满足合规要求。

容器服务

代码解释

文件传输

对象存储

数据中心

服务器

数据库

智能体

AI Agent

Docker

容器

Agent

2026上云采购 | AI焕新·智启新局

coding

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

智能体服务 — 生产环境部署文件上传方案设计-腾讯云开发者社区-腾讯云

智能体服务 — 生产环境部署文件上传方案设计

智能体服务 — 生产环境部署文件上传方案设计

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐