# SmartFlow 容器化部署说明

## 1. 方案定位

这套方案把“开发启动”和“服务器部署”拆开处理。

1. 本地开发继续使用 `backend/scripts` 下的 PowerShell 脚本，适合频繁改代码与频繁重启。

2. 服务器部署使用 [`docker-compose.full.yml`](/D:/SmartFlow-Agent/docker-compose.full.yml) 管理“依赖 + 后端 + 前端”全栈容器。

3. 离线或半离线环境通过 [`deploy/docker-pack.ps1`](/D:/SmartFlow-Agent/deploy/docker-pack.ps1) 在本地打包镜像，再用 [`deploy/docker-load.sh`](/D:/SmartFlow-Agent/deploy/docker-load.sh) 在 Linux 服务器导入。

## 2. 为什么国内弱网更适合这个方案

如果服务器不稳定访问国外镜像源，真正要调整的不是“要不要继续用 Docker Compose”，而是“镜像分发方式”。

1. Compose 继续负责启动、重启、网络、卷和服务依赖。

2. 镜像构建与拉取放到本地或一台网络更好的机器上完成。

3. 服务器只做 `docker load` 和 `docker compose up -d`，避免上线时卡在拉镜像。

结论就是：弱网环境会让“脚本直起进程”更难维护，但会让“Compose + 离线镜像包”更有优势。

## 3. 关键文件

1. 后端共享镜像定义：[`backend/Dockerfile`](/D:/SmartFlow-Agent/backend/Dockerfile)

2. 前端镜像定义：[`frontend/Dockerfile`](/D:/SmartFlow-Agent/frontend/Dockerfile)

3. 前端反向代理配置：[`frontend/nginx.conf`](/D:/SmartFlow-Agent/frontend/nginx.conf)

4. 容器专用后端配置模板：[`backend/config.docker.yaml`](/D:/SmartFlow-Agent/backend/config.docker.yaml)

5. 全栈 Compose：[`docker-compose.full.yml`](/D:/SmartFlow-Agent/docker-compose.full.yml)

6. Compose 环境变量示例：[.env.full.example](/D:/SmartFlow-Agent/.env.full.example)

## 4. 推荐流程

### 4.1 本地构建并导出镜像

在 Windows 开发机执行：

```powershell
cd D:\SmartFlow-Agent
.\deploy\docker-pack.ps1 -AppTag 20260506 -IncludeInfra
```

执行后会得到：

1. `.docker-bundles/smartflow-app-20260506.tar`

2. `.docker-bundles/smartflow-infra-20260506.tar`

### 4.2 传到 Linux 服务器并导入

首次使用前建议先给脚本执行权限：

```bash
chmod +x ./deploy/docker-load.sh
```

然后执行：

```bash
cd /data/smartflow
./deploy/docker-load.sh .docker-bundles
```

### 4.3 准备配置并启动

1. 复制 [.env.full.example](/D:/SmartFlow-Agent/.env.full.example) 为根目录 `.env`。

2. 按实际情况修改 [`backend/config.docker.yaml`](/D:/SmartFlow-Agent/backend/config.docker.yaml) 中的密钥、模型配置与业务参数。

3. 启动全栈服务：

```bash
docker compose -f docker-compose.full.yml up -d
```

如需 Attu：

```bash
docker compose -f docker-compose.full.yml --profile ops up -d
```

## 5. 镜像源困难时的处理方式

### 5.1 最稳妥：完全离线导入

适合服务器几乎拉不到外网镜像的情况。

1. 本地 `docker build` / `docker pull`

2. 本地 `docker save`

3. 服务器 `docker load`

4. 服务器 `docker compose up -d`

这是当前最推荐的落地方式。

### 5.2 次优方案：改成国内可访问的镜像地址

如果您有私有仓库或云厂商镜像加速源，可以在 `.env` 里修改这些变量：

1. `SMARTFLOW_MYSQL_IMAGE`

2. `SMARTFLOW_REDIS_IMAGE`

3. `SMARTFLOW_KAFKA_IMAGE`

4. `SMARTFLOW_ETCD_IMAGE`

5. `SMARTFLOW_MINIO_IMAGE`

6. `SMARTFLOW_MILVUS_IMAGE`

7. `SMARTFLOW_ATTU_IMAGE`

这样无需改 Compose 文件本身。

## 6. 选型结论

把“国内服务器拉镜像困难”考虑进去之后，结论会更明确。

1. 开发启动继续保留本地脚本方案。

2. 生产与测试部署优先选 `Docker Compose`，不要回退到 `main.go` 或手写启动脚本。

3. 镜像分发优先选“本地打包 + 服务器导入”，而不是让服务器现场构建或现场拉国外镜像。