部署前需要先弄清楚什么
Merlin AI 常被用户理解为 AI 浏览器插件或智能助手入口，但在团队使用、内网演示、统一配置账号与模型参数等场景中，Docker 部署更便于运维。相比直接在本机安装，容器化方式可以把运行环境、依赖版本、端口、数据目录相对固定下来，后续迁移到另一台服务器时也更容易复现。
开始之前需要确认三件事：第一，镜像来源是否来自 Merlin 官方文档、官方仓库或可信维护者，不建议随意使用来路不明的镜像；第二，当前机器是否已经安装 Docker 与 Docker Compose；第三，准备好可用端口、数据保存目录以及必要的环境变量，例如访问密钥、模型服务地址、工作空间路径等。不同版本的 Merlin AI 镜像参数可能不同，实际部署时应以对应版本说明为准。
适用场景与推荐环境
Docker 部署适合个人开发者、本地测试环境、小型团队内部使用以及需要快速验证 AI 工具能力的场景。如果只是单人在浏览器里轻量使用，插件形态已经足够；如果希望多人共享一个服务入口、统一管理配置、保留会话数据或接入内部知识资料，容器部署更合适。
推荐环境为 2 核 CPU、4GB 内存起步，磁盘预留 10GB 以上空间。如果会保存较多对话记录、上传文档或缓存模型结果，应单独规划数据目录。操作系统可选择常见 Linux 发行版，也可以在 macOS、Windows 的 Docker Desktop 中运行。生产使用时建议部署在稳定主机上，并配合反向袋里、访问认证和日志轮转。
第一步：检查 Docker 环境
先确认 Docker 是否可用。在终端执行 docker version，能看到 Client 与 Server 信息，说明基础服务正常。再执行 docker compose version，确认 Compose 插件可用。如果提示命令不存在，需要先完成安装或升级。部署 AI 工具时，容器网络、挂载目录、端口占用是最常见问题，因此不要跳过环境检查。
还要检查目标端口是否已被占用。例如计划把 Merlin AI 映射到主机 8080 端口，可执行 ss -lntp | grep 8080 查看是否已有服务监听。如果端口被占用，可以改用 3000、8088 或其他未使用端口。对于服务器环境，还要确认主机防火墙和云控制台规则允许对应端口访问。
第二步：拉取 Merlin AI 镜像
镜像拉取建议使用官方提供的名称和标签。示例命令可写为 docker pull merlinai/merlin:latest。这里的 merlinai/merlin:latest 仅作为常见写法示例，真实镜像名应以项目文档为准。为了稳定运行，不建议长期依赖 latest 标签，正式环境更推荐固定版本号，例如 merlinai/merlin:1.2.0，便于后续升级和回滚。
拉取完成后可执行 docker images | grep merlin 查看镜像是否存在。若下载失败，通常与网络连通性、镜像名称错误、访问权限或仓库变更有关。不要随意替换成不明镜像，也不要把敏感配置写进自制镜像中。更稳妥的做法是使用环境变量文件或部署平台的密钥管理能力。
第三步：规划端口映射
端口映射决定了用户如何访问容器内服务。假设 Merlin AI 容器内部监听 3000 端口，希望通过主机 8080 访问，则运行时可使用 -p 8080:3000。前面的 8080 是主机端口，后面的 3000 是容器端口。访问地址通常是 https://服务器地址:8080。
如果只在本机测试，可以使用 -p 127.0.0.1:8080:3000，让服务只监听本机地址，减少外部访问风险。如果需要团队访问，再绑定到 0.0.0.0 或默认主机地址，并配合登录认证。不要把没有鉴权的 AI 服务直接暴露在公网，尤其是在已经配置模型密钥、文档资料或团队数据的情况下。
第四步：配置数据目录持久化
容器删除后，容器内部临时数据可能随之消失。因此需要把重要目录挂载到主机。例如准备目录 /opt/merlin/data，用于保存数据库、上传文件、缓存和配置。可先执行 mkdir -p /opt/merlin/data，再根据运行用户调整权限。若容器内使用非 root 用户，目录权限不足会导致启动失败或无法写入。
运行时可使用 -v /opt/merlin/data:/app/data，将主机目录挂载到容器内部 /app/data。这里的容器路径同样要参考官方说明，不同镜像可能使用 /data、/var/lib/merlin 或其他路径。持久化目录建议定期备份，升级前尤其要备份，避免配置或历史记录因版本迁移失败而丢失。
第五步：使用 docker run 启动
最简启动方式可以参考：docker run -d --name merlin-ai -p 8080:3000 -v /opt/merlin/data:/app/data --restart unless-stopped merlinai/merlin:1.2.0。参数含义分别是后台运行、指定容器名称、设置端口映射、挂载数据目录、异常退出后自动重启以及指定镜像版本。
如果 Merlin AI 需要模型服务地址、访问令牌、默认语言或管理员账号，可以追加 -e 参数。例如 -e APP_URL=https://localhost:8080、-e DATA_DIR=/app/data。敏感字段不建议直接写在命令历史中，推荐放入 .env 文件并限制文件权限，例如 chmod 600 .env。启动后执行 docker logs -f merlin-ai 观察日志，看到服务监听成功再打开页面验证。
第六步：用 Compose 管理配置
长期运行更推荐使用 Docker Compose，因为配置更清晰，也便于升级。可以在 /opt/merlin 目录下创建 compose.yaml，声明服务名、镜像版本、端口、挂载目录、环境变量和重启策略。后续启动只需执行 docker compose up -d，停止执行 docker compose down，查看日志执行 docker compose logs -f。
Compose 的优势在于可读性强，团队交接方便。比如端口从 8080 改为 8090，只需要修改 ports 字段后重新启动。数据目录、环境变量也能统一维护。需要注意的是，docker compose down 默认不会删除挂载到主机的数据目录，但如果使用了匿名卷或误加清理参数，仍可能造成数据丢失，操作前要确认影响范围。
升级、回滚与备份策略
升级前先做三项检查：查看新版说明是否存在配置变更，备份数据目录，记录当前镜像版本。推荐流程是先执行 tar -czf merlin-data-backup.tar.gz /opt/merlin/data 进行备份，再拉取新镜像，修改 Compose 中的版本号，最后 docker compose up -d。升级后重点检查登录、会话、文件上传、模型调用和日志是否正常。
如果新版运行异常，应尽快回滚到旧版本。回滚方式是把镜像标签改回旧版本并重新启动。由于数据结构可能已被新版迁移，回滚前最好恢复升级前备份的数据目录。生产环境不要直接跨多个大版本升级，应先在测试环境验证，确认插件端、网页端和服务端配置都兼容后再切换。
常见问题排查
页面打不开，优先检查容器是否运行：docker ps -a。若容器反复退出，查看 docker logs merlin-ai。常见原因包括环境变量缺失、数据目录无写入权限、容器内部端口写错、主机端口被占用。端口映射看似简单，但很多问题都来自把主机端口和容器端口写反。
能打开页面但功能不可用，通常要检查模型服务配置、密钥是否正确、后端接口是否连通。若上传文件失败，多半与挂载目录权限或磁盘空间有关。若重启后数据消失，说明数据没有挂载到正确目录，或使用了容器内部临时路径。若访问速度不稳定，应查看主机资源占用，必要时增加内存或限制并发。
安全边界与实用建议
Merlin AI 这类工具往往会接触提示词、文档内容、接口密钥和团队配置，部署时要坚持最小暴露原则。个人测试可只绑定本机地址；团队使用应增加登录控制；对外提供服务时建议放在反向袋里后，并启用 HTTPS。密钥、账号、内部资料不要写入镜像，也不要提交到公开仓库。
运维上建议固定镜像版本、保留 compose.yaml、.env 示例和部署记录。数据目录要定期备份，日志要定期清理，避免磁盘被占满。对于 AI 浏览器插件与 Docker 服务配合使用的情况，还要确认插件连接地址、跨域设置和访问凭据是否一致。只要镜像来源可信、端口映射清楚、数据目录持久化到位，Merlin AI 的容器化部署就能做到可维护、可迁移、可回滚。
