OpenShip 部署 AI Agent 怎么做？2026 教程

OpenShip 官方 CLI 文档把完整部署闭环概括为 3 个核心动作：部署、查看部署记录、跟踪日志。这个数据点说明，OpenShip 部署 AI Agent 不应从“把所有功能一次性搬上云”开始，而应按照“最小服务 → 外部依赖 → 域名与密钥 → 故障回滚”的顺序推进。(官方 CLI 部署文档)

本周建议动作：先准备一个只返回健康状态、并完成一次模型调用的最小版本；确认服务可以重启、日志能够定位错误、旧版本能够恢复后，再接入数据库、缓存和工具调用。

这篇内容适合需要把本地 AI Agent 原型变成可访问服务的独立开发者，也适合希望通过 Git 推送触发部署、同时保留回滚能力的小团队。正在比较云端构建环境、自有服务器和远程 Mac 控制端的 AI SaaS 工程师，也可以用最后的验收清单判断当前方案是否达标。

最后更新于 2026 年 8 月 1 日，步骤核对自 OpenShip 官方安装文档、CLI 文档、部署指南及回滚指南。

动手前先判断 Agent 属于哪种部署形态

一个“能在本机运行”的 Agent，未必能直接作为线上服务运行。最常见的失败案例是：原型在本地可以写入 SQLite 或临时目录，但上线后容器重启，用户会话、任务状态和上传文件全部消失；如果开发者直到生产环境才发现这一点，问题已经从代码调试变成数据恢复。

先把项目拆成以下组件：

组件类型	线上运行方式	上线前必须确认
Web API	长驻容器，监听明确端口	健康检查、超时、并发和启动命令
长驻 Worker	独立后台服务	队列连接、重复执行、失败重试
定时任务	Cron 类任务或计划服务	执行频率、幂等性、单次运行日志
数据库与缓存	独立服务或托管实例	持久化、备份、网络访问和恢复责任
工具调用服务	独立容器或内部接口	权限边界、服务发现和上游超时

OpenShip 官方资料确认了 Git 仓库、本地目录、云端目标和自有服务器目标等部署入口，同时支持项目、服务、域名、环境变量和部署历史管理；但复杂多服务网络、特定框架兼容性以及生产稳定性，不能只根据宣传页面判断，必须通过目标项目的实际部署验证。(OpenShip 官方资料)

需要特别检查 3 个隐性限制：

运行时限制：如果 Agent 依赖特定 Serverless 事件模型、短生命周期函数或平台专属上下文，应先确认能否改造成普通容器服务。
持久化限制：容器文件系统适合临时缓存，不应默认承担用户数据、任务队列或数据库文件的长期保存。
权限限制：模型密钥、数据库密码、Git 凭据和部署令牌不能写进仓库、镜像层或构建日志。

先选代码入口，再固定构建与运行目标

OpenShip 部署项目通常有两条入口：从 Git 仓库部署，或从本地文件夹部署。Git 入口更适合团队协作和自动发布；本地目录更适合快速验证尚未整理好的原型。官方 CLI 会根据当前目录判断路径：在 Git 仓库内走 Git 部署，不在 Git 仓库内则打包当前目录上传。(OpenShip CLI 部署方式)

开始前，建议把代码整理成下面的最小结构：

ai-agent/
├── src/
├── package.json 或 requirements.txt
├── Dockerfile
├── .env.example
├── README.md
└── health/

其中，.env.example 只能写变量名和示例格式，不能放真实值。启动命令必须在本地完全执行一次，例如：

npm ci
npm run build
npm run start

或：

python -m venv .venv
pip install -r requirements.txt
python -m app

如果使用 Dockerfile，端口和启动命令应明确写出：

FROM node:22-slim

WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev

COPY . .
RUN npm run build

ENV PORT=3000
EXPOSE 3000
CMD ["npm", "run", "start"]

上面的端口只是示例，实际端口必须和应用监听端口一致。OpenShip 自身 CLI 服务默认偏好使用 API 4000 端口、控制面板 3001 端口，但官方文档同时说明端口被占用时会自动选择其他端口，因此不能把默认端口当作所有应用的生产端口。(OpenShip CLI 运行文档)

构建端也要提前固定。OpenShip 的官方部署路径强调，镜像可以在本机或云端构建，生产服务器主要负责运行服务，而不是临时编译项目。(官方部署说明) 如果本机架构、Node 或 Python 版本与目标环境差异明显，最好在部署前通过 Docker 或固定版本文件统一构建环境，避免“本机成功、线上缺依赖”。

用最小版本完成第一次 OpenShip 部署 AI Agent

第一次部署不要直接接入数据库、浏览器工具、文件上传和多模型路由。建议先只保留两个接口：

GET  /healthz
POST /v1/agent

健康检查接口不调用模型，只返回服务状态：

{
  "status": "ok",
  "version": "replace-with-commit"
}

模型接口则只做一次最短链路：接收用户输入、调用模型 API、返回文本。这样可以把“容器启动问题”“密钥问题”“网络问题”和“模型请求问题”分开定位。

可以按以下命令完成本地目录初始化和首次部署：

npm install -g openship

openship login

cd /path/to/ai-agent
openship init
openship deploy --watch

如果代码已经关联 Git 项目，则推送代码后使用：

git add .
git commit -m "deploy minimal agent"
git push origin main

openship deploy --branch main --env production --watch

官方文档中的 openship init 会在项目目录写入 .openship/project.json，后续命令可以根据该文件识别项目；openship deploy --watch 则会持续输出构建过程，适合第一次上线时观察依赖安装、镜像构建和容器启动。(OpenShip 项目与部署命令)

首次部署至少要留下 4 类证据：

构建日志：依赖安装和构建命令没有失败。
服务状态：容器进入运行状态，而不是只完成镜像构建。
健康检查：/healthz 能从公开端点访问。
模型请求：使用测试输入完成一次真实调用，并确认日志中没有泄露完整密钥。

部署完成后，不要立刻宣布上线。先执行：

curl -i https://<YOUR_DOMAIN>/healthz
curl -X POST https://<YOUR_DOMAIN>/v1/agent \
  -H "Content-Type: application/json" \
  -d '{"message":"ping"}'

域名尚未配置时，可先使用平台生成的临时地址，等应用容器和模型链路稳定后再绑定正式域名。

接入数据库、缓存和后台任务

带后端的 AI Agent 通常至少需要保存用户会话、任务状态、工具调用结果或计费记录。此时不要把所有组件塞进一个进程，而应按依赖顺序逐步加入：

第一步：数据库。
先建立数据库连接、迁移脚本和最小读写接口。必须确认数据库地址来自环境变量，应用重启后数据仍然存在，并且数据库备份由谁负责。

第二步：缓存或队列。
如果 Agent 有长任务、并行工具调用或异步通知，再接入 Redis 等缓存或队列服务。需要验证队列连接断开时的错误处理，不能只在网络正常时测试。

第三步：Worker。
将耗时任务从 Web API 中拆出，使用独立 Worker 处理。Worker 要有明确的重试上限、失败状态和任务幂等键，否则模型超时后重复执行可能造成重复扣费、重复写入或重复发送通知。

第四步：工具服务。
浏览器操作、文件解析、搜索、内部 API 等工具最好通过私有网络访问，不要为了省事把所有内部端口暴露到公网。

OpenShip 的多服务文档提供了服务依赖、端口、环境变量、重启策略和 Compose 同步等配置方式；官方 CLI 也支持通过 service sync 根据 Compose 文件同步服务。(OpenShip 多服务项目文档)

接入阶段	推荐验收动作	不通过时的处理
数据库	重启 API 后检查同一条记录仍存在	检查卷、连接串和迁移路径
缓存或队列	暂停服务后恢复，确认任务不会静默丢失	增加重试、超时和失败记录
Worker	提交一条测试任务，检查完成、失败和重试状态	拆分任务状态与日志
工具服务	禁止公网访问，只从内部网络调用	检查服务名、端口和权限
数据恢复	用备份恢复到隔离环境	明确谁负责恢复以及恢复窗口

这里最容易被忽略的是“重启后的数据保留方式”。首次启动成功只能说明配置基本可用，不能证明卷挂载、数据库备份和任务恢复已经成立。

配置域名、HTTPS 与模型密钥边界

正式域名配置应按照“添加域名 → 添加 DNS 记录 → 验证解析 → 检查证书 → 访问应用”的顺序进行。OpenShip 官方文档明确说明，添加域名本身不会让服务立即上线，DNS 记录解析成功并通过验证后，证书才会进入后续配置流程。(OpenShip 域名配置文档)

可以使用以下命令查看域名所需记录：

openship domain preview <YOUR_DOMAIN>
openship domain add <YOUR_DOMAIN> \
  --project <YOUR_PROJECT_ID> \
  --primary

openship domain verify <YOUR_DOMAIN_ID>

证书状态则单独检查：

openship deployment ssl status <YOUR_DOMAIN>

模型 API Key 的处理建议如下：

openship project env set <YOUR_PROJECT_ID> \
  --environment production \
  --set MODEL_API_KEY=<YOUR_MODEL_KEY> \
  --set MODEL_BASE_URL=<YOUR_MODEL_BASE_URL> \
  --set MODEL_NAME=<YOUR_MODEL_NAME> \
  --secret

命令中的值必须替换为实际配置，但不应把真实密钥直接写入 shell 历史、截图或文档。更稳妥的做法是通过控制台秘密配置、受保护的 CI 变量或临时输入完成设置。OpenShip CLI 支持对环境变量进行分环境管理，并可以将变量标记为秘密；官方资料还说明，秘密值在读取时会被遮蔽。

日志也要设置边界：

不输出完整的 Authorization 请求头。
不输出完整的模型请求体，尤其是用户隐私和系统提示词。
不把数据库连接串、签名 Cookie 和部署令牌写入异常堆栈。
给每次 Agent 请求生成追踪 ID，但只记录脱敏后的模型名称、耗时和结果状态。

上线前完成监控、重启和回滚验收

正式交付前，至少模拟 3 种故障：

模拟上游模型超时

让模型请求超过应用设定的超时时间，观察 API 是否返回可理解的错误，Worker 是否按照规则重试，日志是否记录追踪 ID。不能让请求无限等待，也不能把上游错误伪装成成功响应。

模拟应用启动失败

临时修改启动命令或引入一个可控配置错误，确认部署状态会进入失败，日志能指出失败阶段。修复后重新部署，并检查服务是否能够正常重启。

模拟新版本错误并回滚

先部署一个已知可用版本，再发布一个故意返回错误的新版本。记录当前部署 ID，执行：

openship deployment list

openship deployment rollback <HEALTHY_DEPLOYMENT_ID>

OpenShip 官方回滚说明强调，回滚恢复的是应用代码，数据库和持久化卷中的数据不会自动回退；如果旧构建产物已经被清理，则需要重新构建对应提交。官方文档还说明，每个项目最多可以固定 10 个部署版本作为长期回滚目标。(OpenShip 回滚与重新部署文档)

因此，回滚验收不能只看页面是否重新打开，还要检查：

旧版本接口是否恢复。
数据库结构是否与旧代码兼容。
新版本写入的数据是否需要单独处理。
环境变量是否仍然适用于旧版本。
回滚后 Worker 是否会重复消费任务。
团队成员能否根据文档在没有原作者参与的情况下执行恢复。

日志和监控应同时覆盖构建日志、容器运行日志和入口请求日志。OpenShip 官方 CLI 支持跟踪部署日志，也支持查看项目运行日志和边缘请求日志。

用这份清单判断是否真的可以上线

[ ] 项目已经明确区分 Web API、Worker、定时任务和数据库。
[ ] 启动命令、监听端口和健康检查接口已经在本地验证。
[ ] Git 仓库或本地目录入口已经固定，生产环境不会临时编译。
[ ] 首次部署只包含最小 Agent 功能，并完成一次真实模型调用。
[ ] 模型 API Key 使用秘密配置，没有进入仓库、镜像和日志。
[ ] 数据库重启后数据仍然存在，并且备份责任已经写清楚。
[ ] Worker 已测试失败重试、重复执行和队列恢复。
[ ] 正式域名已经完成 DNS 验证，HTTPS 证书状态正常。
[ ] 至少保留一个健康版本，并知道如何执行回滚。
[ ] 已验证回滚不会误以为能够恢复数据库和卷数据。
[ ] 已经记录部署版本、提交号、环境变量变更和交接联系人。

如果需要进一步处理环境权限、账号交接或服务使用边界，可以参考 Vuncloud 帮助中心；如果团队需要稳定的 macOS 构建与远程控制端，也可以了解云端 Mac 租用方案。

OpenShip FAQ

以上步骤回答的是实施顺序，但首次部署 AI SaaS 时，仍有几个容易混淆的边界：OpenShip 可以承载标准容器化服务，不代表任何依赖特定 Serverless 语义的项目都能原样迁移；平台能够管理数据库或后台任务，也不代表数据备份和恢复责任会自动消失。具体问答见文末 FAQ 数据。

对于独立开发者来说，最稳妥的交付物不是一张“部署成功”的截图，而是一组可以复核的证据：健康检查返回正常、服务重启后数据仍在、模型密钥没有泄露、错误日志可定位，并且旧版本能够恢复。

如果当前方案只是开发者个人电脑加临时脚本，常见缺点是电脑休眠会中断构建、网络和公网入口不稳定，团队成员也难以共享同一套运行环境；如果还需要持续在线的 macOS 构建端、远程协作环境或隔离测试机，长期维护本地设备往往比部署本身更容易成为瓶颈。此时可以按项目周期选择 Vuncloud 的远程 Mac 环境，把构建、测试和 OpenShip 控制端固定下来，但线上服务仍应按照本文的健康检查、重启、数据恢复和回滚证据完成验收，而不能把远程开发机直接当作生产服务器。