部署前先理解：Docker 方式适合哪些场景

Make AI 通常用于组合大模型能力、接口调用、任务编排和工作流自动化。它适合个人效率工具、团队内部助手、内容处理流水线、客服辅助、数据整理等场景。

相比直接在主机上安装运行环境，Docker 部署的优势是：依赖隔离、迁移方便、升级和回退更可控。只要镜像、配置文件和数据目录保存完整，换一台服务器也能较快恢复服务。

这种方式尤其适合已有 Linux 服务器、NAS、云主机或本地开发机的用户。

• 短期体验：可以使用单容器启动。
• 长期运行：建议使用 docker compose 管理服务。把端口、数据卷、环境变量和重启策略写入配置文件，后续维护会更清晰。

准备工作：确认系统、Docker 与镜像来源

主机配置要求：建议至少 2 核 CPU、4GB 内存、10GB 以上可用磁盘空间。如果处理大量文件、日志或向量数据，磁盘空间应预留更多。

系统可以是常见 Linux 发行版，也可以是支持 Docker 的桌面系统。生产环境建议使用 64 位 Linux，并保持系统时间准确。否则接口鉴权、定时任务和日志排查可能出现偏差。

确认 Docker 是否可用：

• 执行 docker version 查看客户端与服务端信息。
• 执行 docker ps 验证当前用户是否有运行容器的权限。
• 若提示权限不足，可将当前用户加入 docker 用户组，或临时使用管理员权限执行命令。

镜像来源：镜像名称以 Make AI 官方文档或项目仓库说明为准。常见格式可能类似 make-ai/make-ai:latest 或 ghcr.io/xxx/make-ai:latest。不建议随意使用来源不明的镜像，避免引入被篡改的程序或隐藏风险。

第一步：拉取 Make AI 镜像

拉取镜像

确认镜像地址后，可以先拉取镜像：docker pull make-ai/make-ai:latest。如果项目提供固定版本号，建议优先使用明确版本，例如 make-ai/make-ai:1.2.0，而不是长期使用 latest。

latest 虽然方便，但升级内容不透明，可能导致配置项变化、数据结构调整或插件不兼容。

确认镜像并查看说明

拉取完成后，使用 docker images 查看镜像是否存在，并记录镜像 ID、标签和创建时间。正式部署前，建议查看项目发布说明，确认该版本是否需要额外的数据库、缓存组件或模型服务。

• 如果 Make AI 支持仅依赖本地目录运行，部署会更简单。
• 如果需要外部服务，则要提前准备连接地址、账号密钥和网络访问策略。

第二步：规划端口映射

端口映射决定外部如何访问容器内的 Web 页面或 API。假设 Make AI 容器内默认监听 3000 端口，可以将主机 8080 端口映射到容器 3000 端口：docker run -d --name make-ai -p 8080:3000 make-ai/make-ai:latest。启动后访问 http://服务器地址:8080 即可进入服务页面。

端口规划注意事项：

• 避免与主机已有服务冲突。用 ss -lntp 或 netstat -lntp 查看端口占用情况。
• 若 8080 已被占用，可改为 18080、13000 等不冲突端口。
• 对团队内部使用的服务，不建议直接暴露到公网。应限制访问来源，或放在内网环境中使用。
• 若需要对外提供访问，至少要启用登录认证、强密码、访问日志和请求限制。

第三步：配置数据目录，实现持久化

Docker 容器删除后，内部未挂载的数据可能随之丢失。因此，Make AI 的配置、上传文件、工作流定义、日志、插件数据等应挂载到主机目录。

操作步骤：

1. 在主机创建目录：mkdir -p /opt/make-ai/data /opt/make-ai/config /opt/make-ai/logs。
2. 启动时加入数据卷参数，例如：docker run -d --name make-ai -p 8080:3000 -v /opt/make-ai/data:/app/data -v /opt/make-ai/config:/app/config -v /opt/make-ai/logs:/app/logs make-ai/make-ai:latest。

注意事项：

• 容器内路径必须以官方说明为准，不同镜像可能使用 /data、/app/storage 或其他目录。
• 第一次运行后，可用 docker exec -it make-ai sh 进入容器查看目录结构，或通过日志判断配置是否加载成功。
• 目录权限同样重要。如果容器无法写入挂载目录，页面可能报错、工作流无法保存或日志为空。可根据镜像运行用户调整目录属主，避免简单粗暴地给所有目录开放过高权限。

第四步：通过环境变量完成基础配置

多数 AI 自动化工具都会通过环境变量配置站点地址、密钥、模型接口、上传限制、日志等级等参数。

常见配置写法：在启动命令中添加 -e，例如：-e APP_URL=http://your-host:8080 -e TZ=Asia/Shanghai -e LOG_LEVEL=info。如果需要连接大模型服务，还可能配置 AI_API_BASE、AI_API_KEY、DEFAULT_MODEL 等变量，具体名称应以 Make AI 文档为准。

密钥安全：密钥不要写进公开脚本、截图或多人共享文档。生产环境建议使用单独的环境变量文件，例如 --env-file /opt/make-ai/.env，并限制该文件读取权限。若团队多人维护，应明确谁有修改配置的权限，变更前先备份，变更后记录时间、修改项和影响范围，便于出现故障时定位。

推荐方式：使用 docker compose 管理

为什么推荐 docker compose

长期运行时，docker compose 比单条命令更适合维护。可以在 /opt/make-ai 下创建 compose 配置，设置镜像、容器名、端口、数据卷、环境变量和重启策略。核心思路是把运行参数固化。

后续使用 docker compose up -d 启动，使用 docker compose logs -f 查看日志，使用 docker compose down 停止服务。

重启策略与日志管理

• 重启策略建议设置为 unless-stopped，主机重启后服务会自动恢复。
• 日志要定期检查，避免异常重试造成磁盘占满。
• 若 Make AI 依赖额外组件，compose 可以把多个服务放在同一文件中管理，并通过内部服务名互相访问，减少手工配置错误。

升级、回退与备份策略

升级前务必做三件事：备份数据目录、记录当前镜像版本、查看新版说明。

• 备份可直接复制 /opt/make-ai 目录，或使用压缩包保存配置、数据和日志中的关键部分。
• 升级时先拉取新镜像，再停止旧容器，并以相同数据目录启动新版本。
• 若页面异常、工作流丢失或接口调用失败，应立即停止新容器，使用旧版本镜像重新启动。

升级注意事项：

• 不要在业务高峰期直接升级。
• 不要连续跨多个大版本升级。
• 更稳妥的做法是：先在测试环境验证已有工作流、定时任务、外部接口和权限配置，确认没有问题后，再迁移到正式环境。
• 对于重要自动化任务，建议保留导出的工作流文件和关键参数清单，避免只依赖单一数据目录。

常见问题排查

• 页面打不开：先检查容器是否运行：docker ps。如果容器反复重启，查看日志：docker logs make-ai --tail=200。常见原因包括端口冲突、环境变量缺失、数据目录无写入权限、镜像架构与主机不匹配。
• 其他设备无法访问：若主机能访问但其他设备不能访问，需要检查防火墙规则、云主机安全策略和服务监听地址。
• 工作流无法保存：多半与数据目录挂载或权限有关。
• 模型调用失败：检查接口地址、密钥、模型名称、额度状态和请求格式。
• 上传文件失败：可能是上传目录不可写或系统限制过小。
• 容器时间不对：可配置 TZ=Asia/Shanghai，并确保主机时间同步正常。
• 日志过大：可以配置 Docker 日志轮转，避免长期运行后占满磁盘。

安全边界与实用建议

Make AI 可以连接外部接口、处理文件和执行自动化任务，因此安全边界必须提前设定。

核心安全原则：

• 不要把高权限密钥交给未经验证的工作流使用。
• 不要让不可信用户随意导入脚本或插件。
• 不要把内部资料直接交给未知来源的模型接口。
• 团队使用时，应区分管理员、编辑者和普通使用者，减少误操作影响范围。

实用建议：

• 把部署目录、镜像版本、端口、环境变量说明和恢复步骤写成运维文档。
• 每次修改配置后，先观察日志和核心功能，再交给团队使用。
• 对于个人用户：最重要的是固定版本、做好备份、少开端口。
• 对于团队用户：还要关注权限分层、访问记录和变更流程。

只要镜像来源可信、端口规划清楚、数据目录持久化到位，Docker 部署 Make AI 就能兼顾上手速度与长期稳定性。